Developer Spotlight
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.
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:
- 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.
- 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!