Sure, you can handle it. But should you?
Let our experts manage the tech maintenance while you focus on your business.
Let our experts manage the tech maintenance while you focus on your business.
Handbuch
Single Sign-On mit Microsoft Entra ID oder Active Directory Federation Services
Einleitung
Single Sign-On (SSO) gibt Benutzer:innen die Möglichkeit sich durch die Anmeldung in einem System automatisch für mehrere Systeme anzumelden, vorausgesetzt alle Systeme verwenden SSO. Durch diese Vereinfachung können sich Benutzer:innen zum Beispiel in Atlassian Confluence anmelden und werden dann auch automatisch in Mindbreeze InSpire angemeldet. Mindbreeze InSpire verwendet dabei die bestehende Session des Benutzers und überprüft deren Gültigkeit mittels OAuth2- und JWT-Validierung.
In den folgenden Kapiteln werden die notwendigen Schritte beschrieben, um SSO via Microsoft Active Directory Federation Services (AD FS) oder Microsoft Entra ID (ME-ID) zu konfigurieren und mit Mindbreeze InSpire zu verwenden.
Achtung: Microsoft Entra ID (ME-ID) ist der neue Name für Microsoft Azure Active Directory (Azure AD). Für mehr Informationen, was Microsoft Entra ID ist oder welche Änderungen es bei Azure Active Directory zu beachten gibt, siehe What is Microsoft Entra ID? - Microsoft Entra | Microsoft Learn und New name for Azure Active Directory - Microsoft Entra | Microsoft Learn.
Voraussetzungen
Um Single Sign-On mit Microsoft Entra ID oder Microsoft Active Directory Federation Services zu verwenden, muss OAuth2 und JWT oder SAML auf dem jeweiligen Identity Provider (IdP) konfiguriert sein.
Die Konfiguration von OAuth2 und JWT in Microsoft Entra ID wird im nachfolgenden Kapitel Konfiguration von OAuth2 und JWT in Microsoft Entra ID beschrieben.
Die Konfiguration von OAuth2 und JWT in Microsoft Active Directory Federation Services wird im nachfolgenden Kapitel Konfiguration von OAuth2 und JWT in Microsoft Active Directory Federation Services beschrieben.
Die Konfiguration von SAML in Microsoft Entra ID wird in der Dokumentation SAML Authentifizierung - Konfiguration mit Microsoft Entra ID beschrieben.
Die Konfiguration von SAML in Microsoft Active Directory Federation Services wird in der Dokumentation SAML Authentifizierung - Konfiguration mit Microsoft Active Directory Federation Services (ADFS) beschrieben.
Konfiguration
Wenn Sie SAML auf Ihrem IDP und in Mindbreeze InSpire eingerichtet haben, können Sie mit der benötigten Konfiguration für SSO beginnen. Je nachdem, ob Sie ME-ID oder AD FS verwenden wollen, hilft Ihnen einer der folgenden Abschnitte dabei.
Konfiguration von OAuth2 und JWT in Microsoft Entra ID
Wenn Sie Microsoft Entra ID (ME-ID) als IDP für SSO verwenden, führen Sie folgende Schritte durch.
Schritt 1: Registrierung einer Microsoft Azure Applikation
Geben Sie bei der Registrierung einen Namen für die neue Microsoft Azure Applikation an und wählen Sie die passende Option bei „Supported account types“ aus. Zum Beispiel können Sie die Option „Accounts in any organizational directory (Any Microsoft Entra ID tenant – Multitenant)“ auswählen, wenn Sie Accounts unterstützen wollen, die von einer anderen Microsoft Entra ID kommen. Vergeben Sie auch eine URI bei der Einstellung „Redirect URI“, die auf die Search App Ihrer Appliance weiterleitet und wählen Sie Single-page application (SPA) aus.
Mehr Informationen zur Registrierung einer Microsoft Azure Applikation finden Sie unter How to register an app in Microsoft Entra ID - Microsoft identity platform | Microsoft Learn.
Schritt 2: Definition eines Scope
Standardmäßig werden von Microsoft Azure Single-Page Applications (SPAs) bei der Verwendung von OAuth 2 JWTs für die Microsoft Graph API ausgestellt, die nur von der Microsoft Graph API selbst validiert werden können. Damit die ausgestellten JWTs jedoch von Mindbreeze InSpire validiert werden können, muss ein neuer Scope definiert werden.
Für mehr Informationen, wie man einen Scope definiert, siehe How to configure an application to expose a web API - Microsoft identity platform | Microsoft Learn.
Schritt 3: Scope als Zugriffsrecht hinzufügen
Fügen Sie den gerade erstellen Scope als Zugriffsrecht hinzu.
Für mehr Informationen, wie man Zugriffsrechte vergibt, siehe Web API app registration and API permissions - Microsoft identity platform | Microsoft Learn.
Stimmen Sie der Änderung zu, indem Sie mit „Grant admin consent for <Tenant>“ bestätigen.
Die Microsoft Azure Applikation ist nun vollständig konfiguriert.
Konfiguration der JWT Token Validierung in Mindbreeze InSpire für ME-ID
Damit JWTs, die von der erstellten ME-ID App ausgestellt werden, in Mindbreeze InSpire validiert werden können und der UPN des angemeldeten Users ausgelesen werden kann, muss JWT Authentication in Mindbreeze InSpire aktiviert und konfiguriert werden.
Gehen Sie dazu im Mindbreeze Management Center auf Configuration. Wechseln Sie anschließend zum Tab Client Services und aktivieren Sie die Advanced Settings. Scrollen Sie anschließend zum Bereich JWT Authentication Settings und konfigurieren Sie die Einstellungen folgendermaßen:
Eingabe | |||||||
Enable JWT Authentication | Aktivieren | ||||||
Optional JWT Authentication | Aktivieren | ||||||
JWK JSON | Beispiel: {"keys":[{"kty":"RSA","use":"sig","kid":"CNv… (sehr verkürzte Version des JWK JSON) Hinweis: Sie können das JWK JSON aus einem Browser-Fenster kopieren, indem Sie den Link „https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys“ verwenden. Die Tenant ID finden Sie als „Directory (tenant) ID“ in „Overview“ Bereich ihrer Microsoft Azure Applikation. | ||||||
JWK URI | Verwenden Sie diese Einstellung als Alternative zur Einstellung „JWK JSON“. Geben Sie dazu eine File-URI an, die auf eine JWK-Datei im Dateisystem der Appliance zeigt, wie zum Beispiel file:///data/jwks-cognito.json oder /data/jwks-cognito.json. Erstellen Sie dazu im Management Center unter „File Manager“ im „Local Filesystem“ die JSON-Datei (z.B. /data/jwks-cognito.json) und fügen Sie den Inhalt des JWK JSON ein.
| ||||||
Required Claims Patterns | |||||||
Required Claims Patterns[1] |
| ||||||
Required Claims Patterns[2] |
| ||||||
JWT Identity Claim Name | upn | ||||||
Konfiguration von OAuth2 und JWT in Microsoft Active Directory Federation Services
Wenn Sie Active Directory Federation Services (AD FS) als IDP für SSO verwenden, führen Sie bitte die in diesem Abschnitt beschriebenen Schritte durch.
Erstellen Sie eine Application Group und eine Application auf Ihrem AD FS Server. Lesen Sie dazu den Abschnitt Registering the public client in AD FS in der Microsoft Dokumentation: 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
Als Redirect URI nehmen Sie bitte die URL Ihrer Mindbreeze InSpire Search App, z.B. https://inspire.myorganization.com.
Da die Search App den OAuth 2.0 Authorization Code Flow verwendet, welche CORS erfordert, muss CORS am AD FS Server aktiviert werden. Führen Sie dazu in der PowerShell folgende Befehle aus:
Set-AdfsResponseHeaders -EnableCORS $true
Set-AdfsResponseHeaders -CORSTrustedOrigins $origin
(Ersetzen Sie $origin mit dem Hostname Ihrer Mindbreeze InSpire Appliance, inklusive Protokoll, z.B. https://inspire.myorganization.com.)
Nehmen Sie zusätzlich die Redirect URI in den trusted Origins auf, indem Sie folgenden Befehl ausführen:
Set-AdfsResponseHeaders -CORSTrustedOrigins $redirect_uri
(Ersetzen Sie $redirect_uri mit der konfigurierten Redirect URI. Wenn mehrere Redirect URIs konfiguriert sind, können Sie diese mit Beistrichen getrennt angeben.)
Zusätzlich müssen die von AD FS ausgestellten JWTs den UPN Claim inkludieren, damit Mindbreeze InSpire den Benutzer des Tokens identifizieren kann. Führen Sie dazu die folgenden Schritte durch:
- In AD FS Management, navigieren Sie zu Application Groups und öffnen Sie die Properties der Appliaction Group.
- Bearbeiten Sie dort die Properties der Web Application
- Navigieren Sie zum Tab Issuance Transform Rules und klicken Sie auf Add Rule…
- Wählen Sie Send LDAP Attributes as Claims als Claim rule template aus
- Setzen Sie einen Claim rule name und wählen Sie Active Directory bei Attribute store aus. Fügen Sie einen Mapping Eintrag hinzu:
- LDAP Attribute: User-Principal-Name
- Outgoing Claim Type: UPN
- Schließen Sie die Konfiguration mit der Schaltfläche Finish ab.
Konfiguration der JWT Token Validierung in Mindbreeze InSpire für AD FS
Damit JWTs, die von der erstellten AD FS Application ausgestellt werden, in Mindbreeze InSpire validiert werden können und der UPN des angemeldeten Users ausgelesen werden kann, muss JWT Authentication in Mindbreeze InSpire aktiviert und konfiguriert werden.
Gehen Sie dazu im Mindbreeze Management Center auf Configuration. Wechseln Sie anschließend zum Tab Client Services und aktivieren Sie die Advanced Settings. Scrollen Sie anschließend zum Bereich JWT Authentication Settings und konfigurieren Sie die Einstellungen folgendermaßen:
Eingabe | |||||||
Enable JWT Authentication | Aktivieren | ||||||
Optional JWT Authentication | Aktivieren (damit SAML als Fallback verwendet wird). | ||||||
JWK JSON | Öffnen Sie https://<adfs-server>/adfs/discovery/keys in einem Browser (ersetzen Sie <adfs-server> mit dem FQHN des AD FS Servers) und fügen Sie das JSON von der Response ein. | ||||||
JWK URI | Verwenden Sie diese Einstellung als Alternative zur Einstellung „JWK JSON“. Geben Sie dazu eine File-URI an, die auf eine JWK-Datei im Dateisystem der Appliance zeigt, wie zum Beispiel file:///data/jwks-cognito.json oder /data/jwks-cognito.json. Erstellen Sie dazu im Management Center unter „File Manager“ im „Local Filesystem“ die JSON-Datei (z.B. /data/jwks-cognito.json) und fügen Sie den Inhalt des JWK JSON ein.
| ||||||
Required Claims Patterns | |||||||
Required Claims Patterns[1] |
| ||||||
Required Claims Patterns[2] |
| ||||||
JWT Identity Claim Name | upn | ||||||
Anpassen der Suchanwendung
Zur Konfiguration des Mindbreeze Application Objects im search app snippet, lesen Sie bitte die Details der Einstellung „msalConfig“.
Troubleshooting
Häufige Fehler beim Konfigurieren der Azure App / InSpire Search App
Wenn im Browser in der Entwicklerkonsole Fehler auftreten, ist meistens eine fehlerhafte Konfiguration der Azure SPA / AD FS Konfiguration der Grund oder bei der Parametrisierung der InSpire Search App traten Fehler auf.
Eine Ursache kann sein, dass die Redirect URI in Azure / AD FS nicht exakt mit der in der Search App übereinstimmt. Beispielsweise kann ein fehlender Schrägstrich (/) am Ende der URI eine Ursache dafür sein kann, dass die Authentifizierung fehlschlägt.
JWTs sind nicht valide
Wenn im Browser in der Entwicklerkonsole 403 Responses bei bereits eingeloggten Benutzern zu sehen sind, dann sind die JWTs laut dem Mindbreeze InSpire Client Service nicht valide. Das ist oft auf eine falsche Konfiguration der JWT Authentication zurückzuführen. Zur Diagnose können Sie die gesendeten JWTs beispielsweise auf https://jwt.io/ dekodieren lassen und überprüfen, ob die Konfiguration von aud und iss korrekt ist. Überprüfen Sie zusätzlich nochmal das JWK JSON. Falls Sie keine Fehler entdecken können, aktivieren Sie Full Logging (Advanced Settings muss aktiviert sein) und überprüfen sie den Client Service Log.