Configuring Single Sign-on (SSO) using Authorization Code + PKCE

Note: if you are using Microsoft Entra ID, see Configuring Single Sign-on (SSO) using Microsoft Entra ID.

Single Sign-on (SSO) enables you to configure your tenancy so that Advance automatically signs in users.

Configuring Single Sign-on requires that you both configure your tenancy to use Single Sign-on and register Advance with your Single Sign-on provider.

Prerequisites

  • Single Sign-on provider - you must have a Single Sign-on provider with which you can register HotDocs Advance

To configure single sign-on

The process of configuring SSO for Advance depends on the SSO provider you use. Generally you will need to complete the following steps:

  • Register Advance as a new application with your SSO provider
  • Add the appropriate request claims to the application registration
  • Configure Advance; you will need the following information from your SSO provider:
    • Metadata Endpoint – the URL from which to download the OpenID Connect metadata document provided by your identity service
    • Client Identifier – the ID of the client with permissions to access the metadata endpoint

1. Register Advance with your single sign-on provider

Each single sign-on provider will require different steps to register Advance. However, all SSO providers will need an appropriate redirect URI for Advance.

The redirect URI IS the URI for the Advance auth application for your tenancy, appended with /.oidc/callback. For example:

https://yourtenancy.yourorganization.com/hdaauth/.oidc/callback

The URI is case sensitive and must be lower case.

2. Add request claims

You must also configure the request claims for your SSO provider.

2.1 ID Token Claims

The ID Token must have the following claims:

  • given_name
  • family_name
  • email

2.2 Authorization Code with PKCE flow

You must enable the Authorization Code with PKCE flow for the client.

3. Update your tenancy SSO configuration

Once Advance is registered with your SSO provider, you should now have the following information:

  • Metadata endpoint
  • Client identifier

To configure SSO for your tenancy

  1. Log in to the Advance Auth Application
  2. Click the SSO Configuration link in the page header.
  3. Click the Create button.
  4. Enter the following information into the fields:
    • Metadata Endpoint – the URL from which to download the OpenID Connect metadata document provided by your identity service
    • Client Identifier – the ID of the client with permissions to access the metadata endpoint
    • Client Secret – enter any dummy value here
    • IsActive – select the IsActive checkbox to immediately activate SSO on your tenancy; if you leave the checkbox empty, you can still activate SSO later
    • IdentityProviderFlow - AuthCodePkce
  5. Click the Save button; Advance redirects you to the SSO Configuration page.
  6. On the SSO configuration page, there is a highlighted URI next to the text The value to provide is. For example,

    https://yourtenancy.yourorganization.com/hdaauth/.oidc/callback. Check that this matches the Redirect URI you set when registering Advance with Azure AD.

Your tenancy is now configured to use Single Sign-on.