Single Sign-On (SSO)

SSO Options

The Maxwell platform supports SSO for the Borrower Hub and Lender Hub. The configuration for each of these Hubs is distinct, so you can use one system for Borrower Hub SSO and a separate system for Lender Hub 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: Maxwell 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 Maxwell front-end acts as an OIDC compliant client.

Auth0 SSO Integration

Auth0 authorization is based around the concept of applications. By default, each Maxwell Borrower Hub site has a corresponding Auth0 application, and the Lender Hub 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 Hub 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. Maxwell will invite one or more lender administrators to the Auth0 system so they can have direct access to the configuration options.

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. 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. Maxwell depends on the email attribute being populated in Auth0 and depends on the email being unique between separate users.

4. Maxwell enables the new connection for one or more applications.

5. For Lender Hub applications, Maxwell 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. Maxwell 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 Maxwell for configuration in the Maxwell 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 Hub site, which could be something like apply.yourdomain.com

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

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. The identity provider must allow the following callback URL:

   • https://[sitedomain]/authorize

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. CORS must be configured to allow access to your domain.

7. The identity provider must support the following scopes, and can be configured to request additional scopes if appropriate:

   • openid

   • profile

   • email

8. The Identity provider must support the following response types:

   • token

   • id_token

9. Extra query parameters may be configured that Maxwell will pass to the OIDC authorization endpoint. This can be used to add hints/flags to the authorization page.

Borrower Hub Registration Options

We support 2 methods for borrowers to register when using SSO - these apply to both Auth0 SSO and direct OIDC SSO:

1. Registration within the OIDC authorization flow - preferred when possible

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 Maxwell 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 Maxwell 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 Maxwell 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 Maxwell should redirect to when a borrower requests to logout. Maxwell 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 Maxwell root page and they do not already have an active Maxwell session, they will be assumed to be an unauthenticated user. To force Maxwell 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, Maxwell 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 Maxwell and establish the borrower session if the borrower is already logged in. This allows the borrower to follow different paths to Maxwell and always be in sync with whether or not they are logged into the identity provider.