How To Topic

Configuring Single Sign-on (SSO) using Microsoft Entra ID

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

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. This topic provides instructions for configuring SSO using Microsoft Entra ID as the SSO provider.

Prerequisites

• Create a tenancy – Advance must have at least one tenancy before you can configure Single Sign-on.
• Microsoft Entra ID – you must have Microsoft Entra ID as your SSO provider

To configure Single Sign-on

1. Register Advance with Microsoft Entra ID

You will require this information when configuring SSO in Advance.

1. Log in to your Azure Portal.
2. Navigate to Microsoft Entra ID > App Registrations.
3. Click the New Registration button.
4. Type a name into the Name field to identify the application. For example, HotDocsAdvance.
5. For Supported account types, select the option that best suits.
6.  In the Redirect URI field, type the URI for the Advance auth application for your tenancy, appended with /.oidc/callback. For example: https://yourtenancy.yourorganization.com/HdaAuth/.oidc/callback
7. Click the Register button; Azure redirects you to the Application Overview page, where you can configure your request claims.
8. From the Application Overview page, copy the following information:
   • MetadataEndpoint – from the OpenID Connect Metadata document field
   • ClientIdentifier – the value in the Application (client) ID field

The URI is case sensitive and must be lower case.

2. Configuring the Request Claims

1. Click Manifest.
2. In the editor, navigate to the optionalClaims section.
3. Replace the optionalClaims section with the following JSON:

   "optionalClaims": {
           "idToken": [
               {
                   "name": "given_name",
                   "source": null,
                   "essential": true,
                   "additionalProperties": []
               },
               {
                   "name": "family_name",
                   "source": null,
                   "essential": true,
                   "additionalProperties": []
               },
               {
                   "name": "email",
                   "source": null,
                   "essential": true,
                   "additionalProperties": []
               }
           ],
           "accessToken": [],
           "saml2Token": []
   },

4. Navigate to the oauth2AllowIdTokenImplicitFlow setting and set its value to true:
   "oauth2AllowIdTokenImplicitFlow": true
5. Click Save.

3. Create a new client secret

You must create a new client secret for the new app registration in Microsoft Entra ID. This is used by Advance to authenticate.

To create a new client secret:

1. In the sidebar, click Certificates and Secrets.
2. Click New client secret .
3. In the Description field, type a description of the new client secret.
4. In the Expires drop-down list, select the expiration time for the new client secret.
5. Click Add.
6. Copy the new secret value; you will need it when configuring SSO in Advance.

4. Configure SSO for your Advance tenancy

Once Advance is registered with Microsoft Entra ID, you should have the following information:

• Metadata endpoint
• Client identifier
• Client secret

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 – the secret for the client
   • IsActive – select the IsActive checkbox to immediately activate SSO on your tenancy; if you leave the checkbox empty, you can still activate SSO later
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 Microsoft Entra IDMicrosoft Entra ID.

Your tenancy is now configured to use Microsoft Entra ID for Single Sign-on.