Links

Single Sign-On (SSO)

SSO Options

The Revvin platform supports SSO for the Borrower Portal and Lender Portal. The configuration for each of these portals is distinct, so you can use one system for Borrower Portal SSO and a separate system for Lender Portal SSO.
We support two paths for SSO integration:
  • Auth0: By default, we use a middleware system called Auth0 for authentication. Auth0 is a full featured Customer Identity and Access Management (CIAM) platform and supports many different SSO protocols. Auth0 also makes setup and testing very convenient.
  • Direct OIDC integration: Revvin can also act as an OIDC client directly to an identity provider that supports OIDC. This option is appropriate when the lender already has an OIDC compliant identity provider and when the expected volume of user authentication would make Auth0 cost prohibitive.
In both cases, the Revvin front-end acts as an OIDC compliant client.

Auth0 SSO Integration

Auth0 authorization is based around the concept of applications. By default, each Revvin Borrower Portal site has a corresponding Auth0 application, and the Lender Portal also has a corresponding Auth0 application. By default, each of these applications are connected to an Auth0 database connection which allows borrowers to register and login, and allows Lender Portal users to login (but not register).
These applications can be associated with additional Auth0 connections to enable a 3rd party identity provider system instead of the Auth0 database. For a full list of Auth0 connection types, see the Auth0 documentation.
To enable SSO with Auth0, we generally follow these high level steps:
  1. 1.
    Revvin will invite one or more lender administrators to the Auth0 system so they can have direct access to the configuration options.
  2. 2.
    The lender administrators will create and configure Auth0 connections that correspond to an identity provider they are using (e.g. Active Directory, Salesforce, Encompass, Identity Server 4, etc).
  3. 3.
    The lender administrator will test the connection using the Auth0 test feature and make sure it allows login and provides an appropriate profile with attributes to Auth0. Revvin depends on the email attribute being populated in Auth0 and depends on the email being unique between separate users.
  4. 4.
    Revvin enables the new connection for one or more applications.
  5. 5.
    For Lender Portal applications, Revvin sets up an Auth0 rule to link accounts from the lender's identity provider to accounts provisioned in the Auth0 database based on an email match.
  6. 6.
    Revvin and the lender test the integration end to end to make sure it works and catch any edge cases.

Direct OIDC SSO Integration

For the direct OIDC SSO Integration, the lender will provide the OIDC connection information directly to Revvin for configuration in the Revvin platform. The following information is required:
  • Authority (e.g. http://login.lender1.com)
  • ClientId
The OIDC must be configured with the following requirements. In the examples below [sitedomain] refers to the domain of the Borrower Portal site, which could be something like apply.yourdomain.com
  1. 1.
    The OIDC identity provider must provide tokens in JWT format and being configured to use JWKS (JSON Web Key Set) for signing the tokens. The JWKS public keys must be available at a jwks_uri specified within the OIDC configuration.
  2. 2.
    Configuration metadata must be available at the authority URL well-known OIDC configuration path (e.g. http://login.yourdomain.com/.well-known/openid-configuration). This standard OIDC configuration page includes JSON data with all of the relevant endpoints and configuration parameters needed by Revvin.
  3. 3.
    The Identity provider must provide tokens in JWT format and be configured to use JWKS (JSON Web Key Set) for signing the tokens. The JWKS public keys must be available at a jwks_uri specified within the OIDC configuration well known URL.
  4. 4.
    The identity provider must allow the following callback URL:
    • https://[sitedomain]/authorize
  5. 5.
    The identity provider must allow the following logout URLs:
    • https://[sitedomain].com/
    • https://[sitedomain]/login
    • https://[sitedomain]/signup
    • https://[sitedomain]/claim
    • https://[sitedomain]/logout
    • https://[sitedomain]/session-timeout
    • https://[sitedomain]/forced-logout
    • https://[sitedomain]/loggedout
  6. 6.
    CORS must be configured to allow access to your domain.
  7. 7.
    The identity provider must support the following scopes, and can be configured to request additional scopes if appropriate:
    • openid
    • profile
    • email
  8. 8.
    The Identity provider must support the following response types:
    • token
    • id_token
  9. 9.
    Extra query parameters may be configured that Revvin will pass to the OIDC authorization endpoint. This can be used to add hints/flags to the authorization page.

Borrower Portal Registration Options

We support 2 methods for borrowers to register when using SSO - these apply to both Auth0 SSO and direct OIDC SSO:
  1. 1.
    Registration within the OIDC authorization flow - preferred when possible
  2. 2.
    Registration with a custom URL - appropriate when the lender has created a registration flow outside of the identity provider or the identity provider is using a non-OIDC protocol like SAML.

Registration within the OIDC Authorization Flow

In this case, when the borrower clicks a button in Revvin to register a new account, they will be taken to the OIDC authorization endpoint with a query parameter of prompt=signup.
It is up to the OIDC authorization page to receive this parameter and show the borrower a registration page instead of a login page. After the borrower completes registration, they will be returned to Revvin and their session will be associated with the newly registered account.

Registration with a custom URL

In this case, when the borrower clicks a button in Revvin to register a new account, they will be taken to a custom URL provided by the lender. After registration at the custom URL, the browser must be redirected back to a special "connect" URL, with this format: https://[sitedomain]/connect. This URL will initiate another OIDC authorization redirect to establish the newly registered borrower's identity and then the borrower session will be associated with the newly registered account.

Logout URL

OIDC compliant identity providers may provide a logout URL that Revvin should redirect to when a borrower requests to logout. Revvin also supports a custom logout URL that can be configured outside of the OIDC process.

Forced "/connect" Path vs Silent Authentication

Currently, when a borrower arrives at the Revvin root page and they do not already have an active Revvin session, they will be assumed to be an unauthenticated user. To force Revvin to check if the borrower is already logged into the identity provider, the lender must send the borrower to the special "connect" URL, with this format: https://[sitedomain]/connect. This link currently redirects to the identity provider and forces the borrower to login or register.
In the near future, Revvin will be adding an option to enable silent authentication on the /connect page and also on each page load. This will redirect the borrower to the identity provider with an OIDC parameter prompt=none. This tells the identity provider not to ask the borrower to login, but just redirect back to Revvin and establish the borrower session if the borrower is already logged in. This allows the borrower to follow different paths to Revvin and always be in sync with whether or not they are logged into the identity provider.