Whitepaper
Single Sign-On with Microsoft Entra ID or Active Directory Federation Services

Introduction

Single Sign-On (SSO) allows users to log in to multiple systems automatically by logging in to just one system, provided that all systems use SSO. Thanks to this simplification, users can, for example, log in to Atlassian Confluence and will then be automatically logged in to Mindbreeze InSpire as well. Mindbreeze InSpire uses the user’s existing session and verifies its validity using OAuth2 and JWT validation.

The following chapters describe the steps required to configure SSO via Microsoft Active Directory Federation Services (AD FS) or Microsoft Entra ID (ME-ID) and use it with Mindbreeze InSpire.

Hint: Microsoft Entra ID (ME-ID) is the new name for Microsoft Azure Active Directory (Azure AD). For more information about what Microsoft Entra ID is and what changes to note with the name change, see What is Microsoft Entra ID? - Microsoft Entra | Microsoft Learn and New name for Azure Active Directory - Microsoft Entra | Microsoft Learn.

Requirements

To use single sign-on with Microsoft Entra ID or Microsoft Active Directory Federation Services, OAuth2 and JWT or SAML must be configured on the respective identity provider (IdP).

The configuration of OAuth2 and JWT in Microsoft Entra ID is described in the following chapter Configuration of OAuth2 and JWT in Microsoft Entra ID.

The configuration of OAuth2 and JWT in Microsoft Active Directory Federation Services is described in the following chapter Configuration of OAuth2 and JWT in Microsoft Active Directory Federation Services.

The configuration of SAML in Microsoft Entra ID is described in the documentation SAML-based Authentication - Configuration with Microsoft Entra ID.

The configuration of SAML in Microsoft Active Directory Federation Services is described in the documentation SAML-based Authentication - Configuration with Microsoft Active Directory Federation Services (ADFS).

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 ME-ID or AD FS, one of the following sections will help you.

Configuration of OAuth2 and JWT in Microsoft Entra ID

If you use Microsoft Entra ID (ME-ID) as the IDP for SSO, please follow the steps described in this section.

Step 1: Registering a Microsoft Azure application

During registration, enter a name for the new Microsoft Azure application and select the appropriate option under “Supported account types”. For example, you can select the option “Accounts in any organizational directory (Any Microsoft Entra ID tenant – Multitenant)” if you want to support accounts that come from a different Microsoft Entra ID. Also, assign a URI in the “Redirect URI” setting that redirects to your appliance’s Search App and select Single-page application (SPA).

For more information on registering a Microsoft Azure application, see How to register an app in Microsoft Entra ID - Microsoft identity platform | Microsoft Learn.

Step 2: Defining a Scope

By default, Microsoft Azure issues Single-Page Applications (SPAs) with OAuth 2 JWTs for the Microsoft Graph API, which can only be validated by the Microsoft Graph API itself. However, in order for Mindbreeze InSpire to validate these issued JWTs, a new scope must be defined.

For more information on how to define a scope, see How to configure an application to expose a web API - Microsoft identity platform | Microsoft Learn.

Step 3: Add the scope as an access right

Add the scope you just created as an access right.

For more information on how to assign access rights, see Web API app registration and API permissions - Microsoft identity platform | Microsoft Learn.

Agree to the change by confirming with “Grant admin consent for <Tenant>”.

The Microsoft Azure application is now fully configured.

Configuration of JWT token validation in Mindbreeze InSpire for ME-ID

In order for JWTs issued by the created ME-ID 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:

Configuration of OAuth2 and JWT in Microsoft Active Directory Federation Services

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

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 $origin

(Replace $origin 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...
   

1. Select Send LDAP Attributes as Claims as Claim rule template
   

1. 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
2. 
   
3. 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:

Adjusting the Search App

To configure the Mindbreeze application object in the search app snippet, please refer to the details of the setting “msalConfig”.

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.