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”.

Step 1: Retrieve a Bearer Token

The first step is to acquire a token for the a 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

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

RESPONSE

{
  "access_token": "0002lVfX1HupwVF1MgbGVKNOh3X7",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer"
}

Step 3: 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.

3.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

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
    }
}

3.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

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.

3.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

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"
}

User impersonation is a powerful and necessary capability when writing an application that must act on behalf of many users.