SSO with Microsoft AAD or AD FS
via SAML / OAuth 2

Introduction

This documentation supports you to set up Single Sign On (SSO) of Microsoft Active Directory Federation Services (AD FS) or Microsoft Azure Active Directory (AAD) also for Mindbreeze InSpire. SSO allows users to avoid the need to additionally log in to Mindbreeze InSpire if they are already logged in via another system that also uses SSO. For example, users who have logged into Atlassian Confluence via SSO (e.g. via SAML on AAD) are automatically logged into Mindbreeze InSpire. Mindbreeze InSpire uses the existing user session and checks its validity (using OAuth2 and JWT validation).

Requirements

SSO via AAD or AD FS in Mindbreeze InSpire is especially useful if your other systems also support SSO. Regardless of whether you use AAD or AD FS as your IDP, SAML must be set up on your IDP. In addition, you need OAuth 2 on your IDP.

At help.mindbreeze.com you can find instructions on how to set up SAML on your IDP and in Mindbreeze InSpire:

• SAML-based Authentication – Configuration with Microsoft Azure Active Directory
• SAML-based Authentication – Configuration with Microsoft Active Directory Federation Services (AD FS)

The configuration of OAuth 2 is explained later.

Configuration

Once you have set up SAML on your IDP and on Mindbreeze InSpire, you can start the necessary configuration for SSO. Depending on whether you want to use AAD or AD FS, one of the following sections will help you.

Microsoft Azure Active Directory (AAD)

If you use Azure Active Directory (AAD) as the IDP for SSO, please follow the steps described in this section.

Configuration of OAuth 2 in AAD

Register a new app in the Azure Portal by clicking on + New registration: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps

Then assign a name. If you want to support accounts coming from another Azure AD directory, select Accounts in any organizational directory. Assign a Redirect URI that redirects to your appliance's search app and select Single-page appliaction (SPA). Confirm your entries with the Register button.

By default, when using OAuth 2, Azure Single-Page Applications (SPAs) issue JWTs for the Microsoft Graph API, which can only be validated by the Microsoft Graph API itself. However, in order that Mindbreeze InSpire can validate the issued JWTs, a new scope must be defined. To do this, click on Expose to API in the menu and then on + Add a scope. If no application ID has been created for this app yet, you will be asked to define one (default value: api://<Client ID>). The default value is sufficient. Confirm your entries with the Save and continue button.

Fill out the mandatory fields and confirm your selection with Add scope.

Add the scope you just created as a permission. Go to API permissions and then to Add a permission. Then select the created app in the My APIs tab (not shown in the screenshot). Select the permission and confirm your selection with the button Add permissions.

Approve the permission by clicking Grant admin consent for <Tenant>.

Configuration of JWT token validation in Mindbreeze InSpire for AAD

In order for JWTs issued by the created AAD app to be validated in Mindbreeze InSpire and the UPN of the logged in user to be read, JWT Authentication must be activated and configured in Mindbreeze InSpire.

To do this, go to Configuration in the Mindbreeze Management Center. Then switch to the Client Services tab and activate the Advanced Settings. Then scroll to the JWT Authentication Settings area and configure the settings as follows:

• Enable JWT Authentication: yes
• Optional JWT Authentication: yes (so that SAML is used as fallback)
• JWK JSON: open https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys in a browser (replace <tenant-id> with the Azure tenant, not to be confused with the Client ID; the Tenant ID can be found e.g. in the Azure Portal in the created app under Overview with the name Directory (tenant) ID). Then copy the JSON into the JWK JSON configuration field.
• As an alternative to the "JWK JSON" option, you can use the "JWK URI" option to specify a file URI pointing to a JWK file in the file system of the appliance, e.g. file:///data/jwks-cognito.json or /data/jwks-cognito.json. To do this, create the JSON file (e.g. /data/jwks-cognito.json) in the Management Center (MMC) in "File Manager", "Local Filesystem" and paste the contents of the JSON.
  Note: Changes in the configured "JWK JSON" file are effective immediately; thus, a restart of the client service is not necessary.
• Configure Required Claims Patterns (+ Add Property)
  • Required Claims Patterns [1]
    • Claim Name: aud
    • Claim Pattern: the Application ID of the created App, can be found in the Azure Portal in the App under Expose an API, e.g. api:// 11111111-2222-3333-4444-555555555555
  • Required Claims Patterns[2]
    • Claim Name: iss
    • Claim Pattern: https://sts.windows.net/<tenant-id>/ (replace <tenant-id> with the Azure tenant)
• JWT Identity Claim Name: upn

Microsoft Active Directory Federation Services (AD FS)

If you use Active Directory Federation Services (AD FS) as the IDP for SSO, please follow the steps described in this section.

Configuration of OAuth2 in AD FS

Create an application group and an application on your AD FS Server. See the section Registering the public client in AD FS in the Microsoft documentation: https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/development/single-page-application-with-ad-fs#registering-the-public-client-in-ad-fs

For the Redirect URI please use the URL of your Mindbreeze InSpire search app, e.g. https://inspire.myorganization.com.

Since the search app uses the OAuth 2.0 Authorization Code Flow, which requires CORS, CORS must be enabled on the AD FS server. To do this, execute the following commands in the PowerShell:

Set-AdfsResponseHeaders -EnableCORS $true

Set-AdfsResponseHeaders -CORSTrustedOrigins $hostname

(Replace $hostname with the hostname of your Mindbreeze InSpire appliance, including the protocol, e.g. https://inspire.myorganization.com.)

Additionally, include the redirect URI in the trusted origins by executing the following command:

Set-AdfsResponseHeaders -CORSTrustedOrigins $redirect_uri

(Replace $redirect_uri with the configured redirect URI. If multiple redirect URIs are configured, you can specify them separated by commas.)

Additionally, JWTs issued by AD FS must include the UPN claim so that Mindbreeze InSpire can identify the uses of the token. To do this, perform the following steps:

1. In AD FS Management, navigate to Application Groups and open the Application Group properties.
2. Edit the properties of the Web application there
   
3. Navigate to the Issuance Transform Rules tab and click Add Rule...
   
4. Select Send LDAP Attributes as Claims as Claim rule template
   
5. Set a Claim rule name and select Active Directory at Attribute store. Add a mapping entry:
   1. LDAP Attribute: User-Principal-Name
   2. Outgoing Claim Type: UPN
6. 
   
7. Finish the configuration with the Finish button.

Configuration of JWT token validation in Mindbreeze InSpire for AD FS

In order for JWTs issued by the created AD FS application to be validated in Mindbreeze InSpire and the UPN of the logged in user to be obtained, JWT Authentication must be enabled and configured in Mindbreeze InSpire.

To do this, go to Configuration in the Mindbreeze Management Center. Then switch to the Client Services tab and activate the Advanced Settings. Then scroll to the JWT Authentication Settings area and configure the settings as follows:

• Enable JWT Authentication: yes
• Optional JWT Authentication: yes (so that SAML is used as fallback)
• JWK JSON: open https://<adfs-server>/adfs/discovery/keys in a browser (replace <adfs-server> with the FQHN of the AD FS server) and insert the JSON from the response.
• As an alternative to the "JWK JSON" option, you can use the "JWK URI" option to specify a file URI pointing to a JWK file in the file system of the appliance, e.g. file:///data/jwks-cognito.json or /data/jwks-cognito.json. To do this, create the JSON file (e.g. /data/jwks-cognito.json) in the Management Center (MMC) in "File Manager", "Local Filesystem" and paste the contents of the JSON.
  Note: Changes in the configured "JWK JSON" file are effective immediately; thus, a restart of the client service is not necessary.

• Configure Required Claims Patterns (+ Add Property)
  • Required Claims Patterns [1]
    • Claim Name: aud
    • Claim Pattern: microsoft:identityserver:<client-id> (replace <client-id> e.g. microsoft:identityserver:6f28992d-cdf7-4311-b4f2-fa67241257fd)
  • Required Claims Patterns[2]
    • Claim Name: iss
    • Claim Pattern: http://<adfs-server>/adfs/services/trust (replace <adfs-server> with the FQHN of the AD FS server)
• JWT Identity Claim Name: upn

Adjusting the Search App

To configure the Mindbreeze application object in the search app snippet, please refer to the details of the setting ‘msalConfig’ in Development of Insight Apps

Troubleshooting

Common errors when configuring the Azure App / InSpire Search App

If errors occur in the browser in the developer console, mostly a faulty configuration of the Azure SPA / AD FS configuration is the reason or something went wrong with the parameterization of the InSpire Search App.

One reason may be that the Redirect URI in Azure / AD FS does not exactly match the one in the search app. For example a missing slash (/) at the end of the URI can be a cause for authentication not to work.

JWTs are not valid

If 403 responses are displayed in the browser in the developer console for users which are already logged in, Mindbreeze InSpire Client Service checks the JWTs as not valid. This is often due to an incorrect configuration of the JWT authentication. In the first step you can have the sent JWTs decoded on https://jwt.io/ and check if the configuration of aud and iss is correct. Additionally, check the JWK JSON again. If you cannot find any errors, activate Full Logging (Advanced Settings must be activated) and check the Client Service Log.