How To Topic

Configuring Single Sign-on (SSO) using Azure Active Directory

Note: if you are not using Azure Active Directory, 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 Azure Active Directory (AD) as the SSO provider.

Prerequisites

• Create a tenancy – Advance must have at least one tenancy before you can configure Single Sign-on.
• Azure Active Directory (AD) – you must have Azure AD as your SSO provider

To configure Single sign-on

1. Register Advance with Azure AD

You will require this information when configuring SSO in Advance.

1. Log in to your Azure Portal.
2. Navigate to Azure Active Directory > 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 Azure AD. This is used by Advance to authenticate with Azure AD.

To create a new client secret:

1. Click the Certificates and Secrets link in the sidebar.
2. Click the New client secret button.
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 the Add button.
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 Azure AD, you should now 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 Azure AD.

Your tenancy is now configured to use Azure AD for single sign-on.