SSO mit Microsoft AAD oder AD FS

via SAML / OAuth 2

Einleitung

Diese Dokumentation unterstützt Sie, Single Sign On (SSO) eines Microsoft Active Directory Federation Services (AD FS) oder Microsoft Azure Active Directory (AAD) auch für Mindbreeze InSpire einzurichten. SSO ermöglicht den Benutzern, dass sie sich nicht mehr zusätzlich in Mindbreeze InSpire einloggen müssen, wenn sie schon über ein anderes System eingeloggt sind, das auch SSO verwendet. So sind beispielsweise Benutzer automatisch in Mindbreeze InSpire eingeloggt, die sich mittels SSO bei Atlassian Confluence angemeldet haben (z.B. über SAML auf AAD). Mindbreeze InSpire verwendet dabei die bestehende Session des Benutzers und überprüft deren Gültigkeit (mittels OAuth2 und JWT-Validierung).

Voraussetzungen

SSO via AAD oder AD FS in Mindbreeze InSpire ist vor allem dann sinnvoll, wenn Ihre anderen Systeme auch SSO unterstützen. Unabhängig davon, ob Sie als IDP AAD oder AD FS verwenden, muss SAML auf Ihrem IDP eingerichtet werden. Zusätzlich dazu benötigen Sie OAuth 2 auf Ihrem IDP.

Auf help.mindbreeze.com finden Sie eine Anleitung, wie Sie SAML auf ihrem IDP und in Mindbreeze InSpire einrichten können:

• SAML Authentifizierung – Konfiguration mit Microsoft Azure Active Directory
• SAML Authentifizierung – Konfiguration mit Microsoft Active Directory Federation Services (AD FS)

Auf die Konfiguration von OAuth 2 wird später noch eingegangen.

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 AAD oder AD FS verwenden wollen, hilft Ihnen einer der folgenden Abschnitte dabei.

Microsoft Azure Active Directory (AAD)

Wenn Sie Azure Active Directory (AAD) als IDP für SSO verwenden, führen Sie bitte die in diesem Abschnitt beschriebenen Schritte durch.

Konfiguration von OAuth 2 in AAD

Registrieren Sie eine neue App im Azure Portal, indem Sie auf + New registration klicken: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps

Vergeben Sie anschließend einen Namen. Wenn Sie Accounts unterstützen wollen, die von einem anderen Azure AD Directory kommen, wählen Sie Accounts in any organizational directory aus. Vergeben Sie eine Redirect URI, die auf die Search App Ihrer Appliance weiterleitet und wählen Sie Single-page appliaction (SPA) aus. Bestätigen Sie Ihre Eingaben mit der Schaltfläche Register.

Standardmäßig werden von 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. Klicken Sie dazu im Menü auf Expose an API und anschließend auf + Add a scope. Wenn noch keine Application ID für diese App erzeugt wurde, werden aufgefordert, eine zu definieren (Standardwert: api://<Client ID>). Der Standardwert ist ausreichend. Bestätigen Sie Ihre Eingaben mit der Schaltfläche Save and continue.

Füllen Sie die Pflichtfelder aus und bestätigen Sie Ihre Auswahl mit Add scope.

Fügen Sie den gerade erstellen Scope als Permission hinzu. Gehen Sie dazu auf API permissions und anschließend auf Add a permission. Wählen Sie dann im Reiter My APIs die erstellte App aus (nicht im Screenshot zu sehen). Wählen Sie die Permission aus und bestätigen Sie Ihre Auswahl über die Schaltfläche Add permissions.

Stimmen Sie der Berechtigung zu, indem Sie auf Grant admin consent for <Tenant> klicken.

Konfiguration der JWT Token Validierung in Mindbreeze InSpire für AAD

Damit JWTs, die von der erstellten AAD 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:

• Enable JWT Authentication: ja
• Optional JWT Authentication: ja (damit SAML als Fallback verwendet wird)
• JWK JSON: öffnen Sie https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys in einem Browser (ersetzen Sie <tenant-id> mit dem Azure Tenant, nicht zu verwechseln mit der Client ID; die Tenant ID kann z.B. im Azure Portal in der erstellten App unter Overview mit dem Namen Directory (tenant) ID gefunden werden). Kopieren Sie das JSON und fügen Sie es im Konfigurationsfeld JWK JSON ein
• JWK URI: Alternativ zur Option „JWK JSON“ können Sie die Option „JWK URI“ verwenden, um eine File-URI anzugeben, die auf eine JWK-Datei im Dateisystem der Appliance zeigt, z.B. file:///data/jwks-cognito.json oder /data/jwks-cognito.json. Erstellen Sie dazu im Management Center (MMC) in „File Manager“, „Local Filesystem“ die JSON-Datei (z.B. /data/jwks-cognito.json) und fügen Sie den Inhalt des JWK JSON ein.
  Hinweis: Änderungen in der konfigurierten „JWK JSON“ Datei sind sofort wirksam; ein Neustart des Client Service ist also nicht notwendig.
• Konfigurieren Sie Required Claims Patterns (+ Add Property)
  • Required Claims Patterns[1]
    • Claim Name: aud
    • Claim Pattern: die Application ID der erstellten App, kann im Azure Portal in der App unter Expose an API gefunden werden, z.B. api://11111111-2222-3333-4444-555555555555
  • Required Claims Patterns[2]
    • Claim Name: iss
    • Claim Pattern: https://sts.windows.net/<tenant-id>/ (ersetzen Sie <tenant-id> mit dem Azure Tenant)
• JWT Identity Claim Name: upn

Microsoft Active Directory Federation Services (AD FS)

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.

Konfiguration von OAuth2 in AD FS

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.mycompany.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 $hostname

(Ersetzen Sie $hostname mit dem Hostname Ihrer Mindbreeze InSpire Appliance, inklusive Protokoll, z.B. https://inspire.mycompany.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:

1. In AD FS Management, navigieren Sie zu Application Groups und öffnen Sie die Properties der Appliaction Group.
2. Bearbeiten Sie dort die Properties der Web Application
   
3. Navigieren Sie zum Tab Issuance Transform Rules und klicken Sie auf Add Rule…
   
4. Wählen Sie Send LDAP Attributes as Claims als Claim rule template aus
   
5. Setzen Sie einen Claim rule name und wählen Sie Active Directory bei Attribute store aus. Fügen Sie einen Mapping Eintrag hinzu:
   1. LDAP Attribute: User-Principal-Name
   2. Outgoing Claim Type: UPN
6. 
   
7. 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:

• Enable JWT Authentication: ja
• Optional JWT Authentication: ja (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: Alternativ zur Option „JWK JSON“ können Sie die Option „JWK URI“ verwenden, um eine File-URI anzugeben, die auf eine JWK-Datei im Dateisystem der Appliance zeigt, z.B. file:///data/jwks-cognito.json oder /data/jwks-cognito.json. Erstellen Sie dazu im Management Center (MMC) in „File Manager“, „Local Filesystem“ die JSON-Datei (z.B. /data/jwks-cognito.json) und fügen Sie den Inhalt des JWK JSON ein.
  Hinweis: Änderungen in der konfigurierten „JWK JSON“ Datei sind sofort wirksam; ein Neustart des Client Service ist also nicht notwendig.
• Konfigurieren Sie Required Claims Patterns (+ Add Property)
  • Required Claims Patterns[1]
    • Claim Name: aud
    • Claim Pattern: microsoft:identityserver:<client-id> (ersetzen Sie <client-id> z.B. microsoft:identityserver:6f28992d-cdf7-4311-b4f2-fa67241257fd)
  • Required Claims Patterns[2]
    • Claim Name: iss
    • Claim Pattern: http://<adfs-server>/adfs/services/trust (ersetzen Sie <adfs-server> mit dem FQHN des AD FS Servers)
• 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' in Entwicklung von Insight Apps.

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.