Authentication and Authorization in the Encompass Lending Platform

This week’s Developer Spotlight post shares insights into how the Encompass^® Digital Lending Platform authenticates and authorizes users and applications. The first step when using the Platform is to be authenticated as a user and/or application. Once authenticated, the application needs to obtain an access token which, in turn, defines what actions the application is permitted to perform, which tenants (e.g. Encompass instances) it can access, and a host of other behaviors. But what exactly is an access token, why is it so important, and what does it mean to authenticate an application?

We will answer those questions, but before delving deeper into the nuances of the Ellie Mae’s OAuth Server, let’s take a step back and review some terminology.

Key Authorization Terminology

OAuth 2.0 is an authorization framework that enables an application to obtain limited access to application programming interfaces (APIs) on behalf of itself or a user. Note, authorization is orthogonal to and separate from authentication and federation.

OAuth 2.0 defines four roles:

• An application is a client An
• API is hosted by a resource server
• A user is a resource owner
• The overarching process is governed by an authorization serve

To minimize the exposure of user credentials, OAuth 2.0 uses access tokens, also known as bearer tokens, to represent specific permissions and periods of access, granted by the resource owner, and enforced by the resource and authorization servers.

Obtaining Access Tokens

The Encompass Digital Lending Platform provides three ways to obtain an access token:

1. Client credentials grant : Ideal for headless, system-to-system interactions like partner integrations. In this flow, an application sends the client credentials to the authorization server and receives an access token in return.
2.  Authorization code grant : This is the way to go for web applications built on top of Encompass Developer Connect . With this flow, the user is first redirected by the application to the authorization server where they authenticate themselves. Next, the user is redirected back to the application along with an authorization code where the application exchanges that authorization code for an access token. 
3. Resource owner password credentials grant : This grant type is used for all other scenarios, like a first-party desktop application for example. In this flow, an application retrieves user credentials, either directly from the user or by loading them from a secure source, then exchanges the client and user credentials for an access token.

Regardless of the grant type, an application is always identified by a client ID and secret. Note, the OAuth client ID should not be confused with an Encompass client ID or instance ID.

An Encompass client ID is a unique, 8-digit identifier (e.g. 12345678) for a consumer or partner whereas an instance ID is a unique, alphanumeric identifier for an Encompass instance (e.g. BE12345678). There is, however, a direct relationship between OAuth and Encompass client IDs. For lenders, the cardinality is one-to-one, and for partners, it is one-to-two, one for test and another for production.

Client credentials can be administered, in the Encompass Developer Connect or Encompass Partner Connect portals, by users with the Super Administrator persona.

Access tokens issued by the Encompass Digital Lending Platform are backed by a sliding-window session with an idle timeout of 15 minutes and a total duration of up to 2 hours. To avoid expiry due to inactivity, an access token must be used as part of an API request or introspected at least once during its time-to-live (TTL). Token introspection is an API for clients to check the validity of an access token and fetch the associated metadata. For more information about token introspection, please refer to the Encompass Developer Connect or Encompass Partner Connect portals.

Additional Protections

The “claims”, which are available in the introspection response, determine which products, features, tenants and actions an application can use as well as the concurrency limit and daily quota. More specifically, entitlements and rate limits are linked to the Encompass client ID (i.e. encompass_client_id), tenant access is governed by the identity type (i.e. identity_type) and Encompass instance ID (i.e. compass_instance_id) and fine-grained permissions are derived from the username (i.e. username, Encompass username).

What’s Next?

To improve security and interoperability, Ellie Mae is currently working on several new features that use the OAuth 2.0 framework as a foundation.

One such feature is dynamic client registration. Today, OAuth clients must be administered through the Encompass Developer Connect or Encompass Partner Connect portals and this model works well when the number of applications is relatively small, but as usage grows, it is beneficial to automate the registration process. The client registration enables you to register (and maintain) OAuth 2.0 clients programmatically.

Another upcoming feature is lender-supplied or bring your own MFA (BYOMFA). With BYOMFA, you can replace the default second-factor (i.e. PingID) with either Duo Mobile or Okta Verify. Initially, this feature will be confined to Encompass Loan Officer Connect^® , but we can apply this functionality to other products in the future.

Pairing SAML 2.0 or OpenID Connect (OIDC) 1.0 with the OAuth 2.0 protocol opens the door for federated single sign-on (SSO). Currently, the Encompass Lending Platform supports consumer federation via SAML 2.0, but lender federation and OIDC is certainly on the radar. Ultimately, the goal is to facilitate both inbound federation with an external identity provider and cross-product SSO.

Join the Developer Summit at Ellie Mae Experience 19

To get more insights into best practices, strategies and techniques to innovate, extend and customize the Encompass Lending Platform and open APIs to meet your unique needs, join us at the Ellie Mae Experience 19 Developer Summit . This year, separate from our system administrator’s tracks and content, we invite you to attend our dedicated Developer Summit tailored for our developer community, including tracks focused on platform development, data and analytics, hands-on training, collaboration opportunities, demos and more. Register now to receive early bird pricing and reserve your seat!