User Impersonation
User impersonation is the ability for a higher privileged user to assume the identity of a user at the same privileged level or a lower privileged level and make API calls as the “impersonated user”. When making calls as the impersonated user, permissions of the impersonated user will be enforced. Usernames for both the impersonator and the impersonated user are logged in the audit trail for loan operations.
The steps below show each API call (the path, request header/body and the response) needed for impersonating a user and for making API loan calls as the impersonated user. The scenario presented below is an application that is running as Super Admin user that desires to make one or more actions as a loan officer with an Encompass login “jmillerlo”.
User impersonation is a powerful and necessary capability when writing an application that must act on behalf of many users.
Step 1: Retrieve a Bearer Token
The first step is to acquire a token for the Super Admin user. A token is used by every API call to see if the caller has permission to make the requested call and provide the user attributes about the person making the call.
POST /oauth2/v1/token
BODY
PARAMETER | VALUE |
---|---|
grant_type | password |
username | {{smart_client_user}}@encompass:{{instance}} |
password | {{smart_client_password}} |
client_id | {{client_id}} |
client_secret | {{client_secret}} |
RESPONSE
{
"access_token": "0002zQgdd9kTIOO2SoPLT9ersU84",
"token_type": "Bearer"
}
Step 2: Retrieve an Impersonation Token
Using the bearer token for Super Admin, retrieve a second bear token (“impersonation token”) which will allow future API calls to execute as “jmillerlo”. To accomplish this, we utilize the same API call as in Step 1, but change the body of the call. A new parameter subject_user_id will be the login of the person which will be impersonated, "jmillerlo". The actor_token is the token retrieved by super-admin. An impersonation token will be returned from this API call.
POST /oauth2/v1/token
BODY
PARAMETER | VALUE |
---|---|
grant_type | urn:ietf:params:oauth:grant-type:token-exchange |
actor_token_type | urn:ietf:params:oauth:token-type:access_token |
subject_user_id | {{subjectUserId} |
actor token | {{actor_token}} |
scope | The token scope is "lp" for Lending Platform. |
client_id | {{client_id}} |
client_secret | {{client_secret}} |
RESPONSE
{
"access_token": "0002lVfX1HupwVF1MgbGVKNOh3X7",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer"
}
Step 3: Introspect Impersonation Token
In this example we will examine the token and retrieve the data associated with the token. This is referred to as token introspection. We can see by the response that the user name returned is "jmillerlo@encompass:debe11223333". We expect to see "jmillerlo" as the user name, as this is who we are impersonating.
POST /oauth2/v1/token/introspection
HEADER
PARAMETER | VALUE |
---|---|
Authorization | 0002lVfX1HupwVF1MgbGVKNOh3X7 |
BODY
None
RESPONSE
{
"active": true,
"scope": "lp",
"client_id": "ccclaaa",
"username": "jmillerlo@encompass:debe11223333",
"token_type": "Bearer",
"exp": 1643045952,
"sub": "jmillerlo@encompass:debe11223333",
"bearer_token": "DEBE11223333_166215b9-0a2d-46b5-ac83-1038d292029b",
"encompass_instance_id": "DEBE11223333",
"actor_user_name": "admin",
"user_name": "jmillerlo",
"user_key": "jmillerlo@encompass:debe11223333",
"encompass_user": "Encompass\\DEBE11223333\\jmillerlo",
"identity_type": "Enterprise",
"actor_encompass_user": "Encompass\\DEBE11223333\\admin",
"encompass_instance_type": "INTERNAL",
"encompass_client_id": "3011223333",
"realm_name": "encompass:debe11223333"
}
Step 4: Utilize the Impersonation Access Token
To make API calls as “jmillerlo” use the new impersonation bear token returned in the response of Step 2 in the access_token field "0002lVfX1HupwVF1MgbGVKNOh3X7". In the steps below, we will make a few API calls with the new access token.
4.1 - Retrieve the Current Profile
The first example will retrieve the User Profile for the impersonation access token.
GET /encompass/v1/company/users/me
HEADER
PARAMETER | VALUE |
---|---|
Authorization | 0002lVfX1HupwVF1MgbGVKNOh3X7 |
BODY
None
RESPONSE
{
"id": "jmillerlo",
"lastName": "Miller",
"firstName": "LO",
"fullName": "LO Miller",
"email": "[email protected]",
"workingFolder": "Adverse Loans",
"subordinateLoanAccess": "ReadOnly",
"userIndicators": [
"TopLevelUser",
"Enabled"
],
"peerLoanAccess": "Disabled",
"lastLogin": "2021-08-16T16:01:44Z",
"personalStatusOnline": false,
"comments": "",
"personas": [
{
"entityId": "7",
"entityType": "Persona",
"entityName": "Loan Officer"
}
],
"ccSite": {
"useParentInformation": true
}
}
4.2 - Determine Eligible Role
In this example, we retrieve the Eligible Roles for the utilizing the impersonation token.
GET /encompass/v3/users/me/eligibleRoles
HEADER
PARAMETER | VALUE |
---|---|
Authorization | 0002lVfX1HupwVF1MgbGVKNOh3X7 |
BODY
None
{
"roles": [
{
"entityId": "1",
"entityName": "Loan Officer",
"entityType": "Role"
}
]
}
As we can see from the response, a Loan Officer role was retrieved. This is what we would expect using the "jmillerlo" Encompass login.
Updated 2 months ago