Authentication

❗️

IMPORTANT

THE API CLIENT SECRET (part of your API Key) SHOULD NOT BE SHARED WITH ANYONE OUTSIDE YOUR ORGANIZATION, INCLUDING ICE MORGAGE TECHNOLOGY. IT SHOULD BE TREATED LIKE A PASSWORD.

YOU CAN REGENERATE THE API CLIENT SECRET USING THE API KEY MANAGEMENT PAGE. ONCE YOU REGENERATE THE SECRET, THE OLD SECRET EXPIRES IMMEDIATELY. ALL YOUR CLIENT INTEGRATIONS WILL NEED TO BE UPDATED WITH THE NEW CLIENT SECRET.

The Encompass Platform uses OAuth 2.0 for authentication and authorization. OAuth enables a client application to access information on behalf of the user without disclosing the credentials.

If you are new to OAuth, you can learn more from the OAuth 2.0 specification or the one of the many beginner’s guides available online. If you are already familiar with OAuth, continue with Supported Authorization Flows.

Supported Authorization Flows

🚧

Per the OAuth 2.0 specification, the Encompass Platform uses HTTP Basic authentication to authenticate client applications. This means the authorization header must contain the base64 encoded API key, which includes the API client ID and secret in the format: client_id:client_secret. This API key is available from your Encompass super administrator.

The Encompass Platform supports the following authorization flows:

• Authorization Code
  The authorization code flow, also known as three-legged OAuth, allows an application to obtain an access token through a two-step process: obtain an authorization code by authenticating the user (using the authorization endpoint) and then exchange the authorization code for an access token (using the token endpoint).

• Resource Owner Password Credentials (commonly used)
  The resource owner password credentials flow (i.e., username and password) allows an application to obtain an access token via a single API call, simply exchange user credentials for an access token (using the token endpoint).
  Note: This grant type should only be used when the authorization code flow is not viable (e.g. console applications).

• Client Credentials
  This flow allows users to log in to your application with their credentials and supports User Token Impersonation. The client credentials flow is the preferred flow when Single Sign-On (SSO) is enabled in Encompass.

📘

Important!

Grant type client_credentials is for ISV partners only, lenders must use grant type = password.

Support for SSO
Developer Connect supports SSO authentication with Developer Connect API integrations and SSO-enabled Encompass instances. Please note the following:

• SSO authentication with Developer Connect API integrations is meant to be used with authorization code UI login flow (grant_type = authorization_code).


• SSO authentication with Developer Connect API integrations is supported for lenders, not ISV partners.


• For information about setting up SSO for Developer Connect, see the Setting Up SSO for Encompass Connect Products guide or visit the Resource Center: ICE Mortgage Technology Identity Management Solutions page page for additional guides, webinars, and videos.

• User Impersonation
  Developer Connect supports the user impersonation flow. Once an access token is obtained, it can be exchanged by a privileged Encompass user to perform actions in Encompass under a different user account. For user impersonation, Developer Connect utilizes a grant type token exchange (urn:elli:params:oauth:grant-type:token-exchange) which provides the currently logged-in user with a new access token that includes impersonation semantics. This flow is supported for lenders with grant type resource owner password credentials. To learn how to impersonate a user and make API loan calls as the impersonated user, see Best Practices: User Impersonation.

OAuth Endpoints

The OAuth 2.0 endpoints for the Encompass Platform are:

Authorization Code

Step 1: Authorize User

The first step is to direct the user to the authorization endpoint supplying the query parameters described below.

Example for Non-SSO:

https://idp.elliemae.com/authorize?client_id=<client_id>&response_type=code&redirect_uri=<redirecturi>&scope=lp&is_sso=false

Example for SSO:

https://idp.elliemae.com/authorize?client_id=<client_id>&response_type=code&redirect_uri=<redirecturi>&scope=lp&is_sso=true&instance_id=BE12222222

On the login page, the user will either enter their Encompass instance ID, user ID and password, or will enter their IdP username and password if SSO is configured.

Step 2: Receive Authorization Code

Once authenticated, the Encompass Platform issues an HTTP 302 to the redirect URI. As part of the redirect, the callback receives an authorization code, which is a single-use grant that expires in one minute.

Step 3: Obtain an Access Token

Next, exchange the authorization code for an access token. To do this, pass the authorization code to the token issuance endpoint, https://api.elliemae.com/oauth2/v1/token.

curl -X POST\
     -u '{{client_id}}:{{client_secret}}'\
     -d 'grant_type=authorization_code'\
     -d 'redirect_uri={{redirect_uri}}'\
     -d 'code={{authorization_code}}'\
     https://api.elliemae.com/oauth2/v1/token

{
  "access_token": "6v8wKWREGjeECskvcibQtdiO7tWn",
  "token_type": "Bearer"
}

You now have an access token. The access token is active for 15 minutes, up to a maximum of 120 minutes (2 hours). To avoid expiration, the access token must be used (by calling an API) at least once every 15 minutes.

Resource Owner Password Credentials

To obtain an access token, pass the user's credentials to the token issuance endpoint, https://api.elliemae.com/oauth2/v1/token.

curl -X POST\
     -u '{{client_id}}:{{client_secret}}'\
     -d 'grant_type=password'\
     -d 'username={{username}}'\
     -d 'password={{password}}'\
     https://api.elliemae.com/oauth2/v1/token

Client Credentials

To obtain an access token, pass the grant_type = client_credentials, the instance_id and scope = ‘lp’ with client_id and client_secret in the headers.

📘

Important!

Grant type client_credentials is for ISV partners only, lenders must use grant type = password. In Encompass, ISV Partners are setup as "API Users". Please see the API User" section below for more information.

curl -L -X POST 'https://api.elliemae.com/oauth2/v1/token' \
--header 'Authorization: Basic dDB2OWVhaDpaMnRoNUszRjgxRGsmcTFNMW04YjlGa2gjeVJqWEJGaGFSMzZLWHVZekFqdjk4bzFKWiNUb2w4UFVuQDBDaFVy'\
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'instance_id={{instance_id}}' \
--data-urlencode 'scope=lp'

API User

ISV Partners are setup as "API Users" in the Encompass lender instance.

The "API User" checkbox grants a supported Encompass Partner access to the lender instance using the Encompass Developer Connect APIs. The ISV partner can use the APIs for the integrations they are building.

To setup an API user, partner API Client ID is required. The ISV partner can request API Keys from ICE Mortgage Technology on the ICE Mortgage Technology Partner Portal.

Once the Partner and the Encompass administrator complete the required process, the Partner will be recognized as a Supported Encompass Partner. Then, they will be issued partner API Keys and will be able to make API calls for the specific lender Encompass instance.

The ISV partner who is engaged with multiple lenders will have separate API keys for each partner/lender pair.

Obtain an Impersonation Token

For user impersonation, exchange the access token for an Impersonation Token. To do this, pass the token-exchange grant type, the recently generated access token (actor_access_token), and impersonated user to be impersonated as the subject user ID, in addition to the client ID and client secret to the token issuance endpoint, https://api.elliemae.com/oauth2/v1/token.

📘

Supported Impersonation Scenarios

Impersonation scenarios currently supported by Developer Connect are provided below. In all cases when a user impersonates another user, the access privileges of the impersonated user are applied to the API calls.

• Super Administrator - Can impersonate all other Encompass users, including other SuperAdmin users.
• API Users - Lenders with grant type resource owner password credentials can impersonate any other users at the same level or below them in the organization hierarchy.

curl -X POST\
     -d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange'\
     -d 'actor_token_type=urn:ietf:params:oauth:token-type:access_token'\
     -d 'subject_user_id={{impersonated_user}}'\
     -d 'actor_token={{token}}'\
     -d 'scope=lp'\
     -d 'client_id={{client_id}}'\
     -d 'client_secret={{client_secret}}'\
     https://api.elliemae.com/oauth2/v1/token

{
  "access_token": "6v8wKWREGjeECskvcibQtdiO7tWn",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access-token",
  "token_type": "Bearer"
}

Token Introspection

To check the status of an access token (and retrieve the associated metadata), pass the API client ID and secret, plus the access token to the token introspection endpoint, https://api.elliemae.com/oauth2/v1/token/introspection.

curl -X POST\
--location 'https://api.elliemae.com/oauth2/v1/token/introspection' \
--header 'Authorization: Basic <Base64 encoded username and password>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=<ACCESS_TOKEN>'

If the token is valid, a JSON string is returned; otherwise, an error is raised.

Response for Authorization Code and Resource Owner Password Credentials Flows

{
  "active": true,
  "scope": "lp",
  "client_id": "nurgbm0b",
  "username": "abcmortgage@encompass:be79039931",
  "token_type": "Bearer",
  "exp": 1481704218,
  "sub": "abcmortgage@encompass:be79039931",
  "encompass_instance_id": "be79039931",
  "user_name": "abcmortgage",
  "user_key": "abcmortgage@encompass:be79039931",
  "encompass_user": "Encompass\\be79039931\\abcmortgage",
  "identity_type": "Enterprise",
  "encompass_client_id": "3569564881",
  "realm_name": "encompass:be79039931"
}

Response for User Token Impersonation Flow
The introspection endpoint returns additional information in the impersonation token response that identifies the impersonated user as well as the impersonator (actor_encompass_user).

📘

User names for both the impersonator and the impersonated user are logged in the audit trail table for loan operations.

{
  "active": true,
  "scope": "lp",
  "client_id": "nurgbm0b",
  "username": "lpusername@encompass:be79039931",
  "token_type": "Bearer",
  "exp": 1620929058,
  "sub": "lpusername@encompass:be79039931",
  "bearer_token ": "be79039931-xxxxcx", “
  "encompass_instance_id": "be79039931",
  "user_name": "lpusername ",
  "user_key": "lpusername@encompass:be79039931",
  "encompass_user": "Encompass\\be79039931\\lpusername",
  "identity_type": "Enterprise",
  "actor_encompass_user": "Encompass\\be79039931\\admin
  "encompass_client_id": "3569564881",
  "realm_name": "encompass:be79039931"
}

Token Revocation

To revoke an access token, pass the API client ID and secret plus the access token to the token revocation endpoint, https://api.elliemae.com/oauth2/v1/token/revocation.

curl -X POST\
     -u '{{client_id}}:{{client_secret}}'\
     -d 'token={{access_token}}'\
     https://api.elliemae.com/oauth2/v1/token/revocation

If the token is successfully revoked, the API returns a 204 status; otherwise, an error is returned.