AD FS Anbindung

Diese Dokumentation beschreibt das Erstellen einer Application Group in AD FS für die interaktive Benutzeranmeldung (Native Application, Browser-Login). Nach Abschluss können sich Benutzer über AD FS an Business GPT anmelden.

Technischer API-Zugang (api-User)

Soll zusätzlich ein technischer, serverseitiger API-Zugang ("api-User") für den programmatischen Zugriff über den client_credentials-Flow eingerichtet werden, ist dies in einer separaten Anleitung beschrieben: API-Anbindung über AD FS (api-User).

Anlage einer Application Group in AD FS (UI-basiert)

Im Folgenden ist beschrieben, wie über die grafische Benutzeroberfläche der AD FS-Verwaltung (AD FS Management Console) eine neue Application Group angelegt wird.

Notwendige Daten

Für die Konfiguration der Anbindung zwischen Ihrer Business GPT-Applikation und Ihrem ADFS müssen folgende Daten vorliegen:

• BGPT_CLIENT_IDENTIFIER
• i.d.R. ein Wert welcher der Url zu Ihrer Business GPT-Applikation entspricht - wird vom Business GPT-Team bereitgestellt
• BGPT_REDIRECT_URI
• i.d.R. die Url Ihrer Business GPT-Applikation zu welcher der ADFS den Nutzer nach erfolgreicher Authentifizierung umleitet

Voraussetzungen

Bevor Sie mit der Anlage beginnen, stellen Sie sicher, dass folgende Bedingungen erfüllt sind:

• Sie sind mit einem Konto angemeldet, das über administrative Rechte auf dem AD FS-Server verfügt (Mitglied der lokalen Administratorengruppe bzw. entsprechende Delegation).
• Die Rolle "Active Directory Federation Services" ist installiert und konfiguriert.
• Ihnen liegen folgende Informationen der zu integrierenden Anwendung vor:
• Client-Typ (vertraulich / öffentlich – z. B. Server-Anwendung vs. SPA/native App)
• Client Identifier (Client ID)
• Redirect URI(s) (Antwort-URLs der Anwendung)
• ggf. Relying Party Identifier und benötigte Claims

Schritt 1: AD FS-Verwaltung öffnen

Öffnen Sie den Server-Manager und wählen Sie Tools → AD FS-Verwaltung (bzw. AD FS Management).

Alternativ können Sie die Konsole direkt über Microsoft.IdentityServer.msc starten (Ausführen-Dialog mit Win + R).

Schritt 2: Assistenten für neue Application Group starten

1. Erweitern Sie im linken Navigationsbereich den Knoten AD FS.
2. Wählen Sie den Knoten Application Groups aus.
3. Klicken Sie im rechten Aktionen-Bereich auf Add Application Group… (bzw. Anwendungsgruppe hinzufügen…).

Alternativ: Rechtsklick auf Application Groups → Add Application Group….

Schritt 3: Name und Vorlage (Template) auswählen

Im Assistenten Add Application Group Wizard auf der Seite Welcome:

1. Vergeben Sie unter Name einen sprechenden Namen für die Application Group (z. B. Business GPT).
2. Optional: Tragen Sie unter Description eine Beschreibung ein (z. B. Business GPT Application).
3. Wählen Sie unter Template die folgende Vorlage als Basis-Setup für Business GPT aus:
4. Native application accessing a web API – native/mobile App, öffentlicher Client
5. Klicken Sie auf Next.

Schritt 4: Native/Server-Anwendung konfigurieren (Client ID & Redirect URI)

Auf der Seite Native application:

1. Der Assistent generiert automatisch einen Client Identifier (Client ID). Diesen Wert ersetzen Sie bitte mit dem bereitgestellten BGPT_CLIENT_IDENTIFIER.
2. Tragen Sie unter Redirect URI die Antwort-URL der Anwendung ein, die bereitgestellte BGPT_REDIRECT_URI
3. Klicken Sie auf Add um die Übernahme in die darunter dargestellte Liste zu veranlassen.
4. Optional: Tragen Sie unter Description eine Beschreibung ein (z. B. Business GPT - Native Application).
5. Klicken Sie auf Next.

Schritt 5: Web API konfigurieren (Relying Party Identifier)

Auf der Seite Configure Web API:

1. Tragen Sie unter Identifier den BGPT_CLIENT_IDENTIFIER von Business GPT ein und klicken Sie auf Add.
2. Optional: Tragen Sie unter Description eine Beschreibung ein (z. B. Business GPT - Web API).
3. Klicken Sie auf Next.

Schritt 6: Zugriffssteuerungsrichtlinie (Access Control Policy) festlegen

Auf der Seite Choose Access Control Policy:

1. Wählen Sie die gewünschte Richtlinie, z. B.:
2. Permit everyone – Zugriff für alle authentifizierten Benutzer
3. Permit specific group – Zugriff nur für bestimmte Gruppe(n)
4. Passen Sie ggf. die Parameter der Richtlinie an (z.B. die betreffende Gruppe, wenn Permit specific group verwendet werden soll).
5. Klicken Sie auf Next.

Hinweis: An dieser Stelle kann es je nach Unternehmenspolicy Unterschiede im Hinblick auf die Anforderungen im Autorisierungskontext geben. Ggf. muss daher vorab eine eigene Richtlinie erstellt oder angepasst werden, falls keine der vorhandenen die Anforderungen erfüllt.

Schritt 7: Berechtigungen / Scopes konfigurieren (Application Permissions)

Auf der Seite Configure Application Permissions:

1. Wählen Sie als Client die Business GPT - Native Application aus (falls mehrere vorhanden).
2. Aktivieren Sie unter Permitted scopes die folgenden, notwendigen Scopes:
   • openid
3. Klicken Sie auf Next.

Schritt 8: Zusammenfassung prüfen (Summary)

Auf der Seite Summary:

1. Prüfen Sie alle vorgenommenen Einstellungen (Name, Client ID, Redirect URIs, Access Control Policy).
2. Bei Korrekturbedarf navigieren Sie mit Previous zurück.
3. Klicken Sie auf Next, um die Application Group zu erstellen.

Schritt 9: Anlage abschließen

Auf der Seite Complete:

1. Die Meldung bestätigt die erfolgreiche Anlage der Application Group.
2. Klicken Sie auf Close, um den Assistenten zu beenden.

Schritt 10: Ergebnis überprüfen

Die neue Application Group erscheint nun in der Liste unter dem Knoten Application Groups.

Schritt 11: CORS Trusted Origins setzen (Set-AdfsResponseHeaders)

Damit die Business GPT-Applikation im Browser Cross-Origin-Requests gegen den AD FS (z. B. den Token-/Authorize-Endpoint) durchführen darf, muss CORS im AD FS aktiviert und die Origin der Business GPT-Applikation als vertrauenswürdig hinterlegt werden. Dies erfolgt nicht über die UI, sondern per PowerShell-Cmdlet Set-AdfsResponseHeaders.

Hinweis: Die folgenden Cmdlets müssen in einer PowerShell-Sitzung mit administrativen Rechten direkt auf dem AD FS-Server (bzw. dem primären Knoten einer AD FS-Farm) ausgeführt werden.

1. Öffnen Sie Windows PowerShell als Administrator.
2. Aktivieren Sie CORS im AD FS:

Set-AdfsResponseHeaders -EnableCORS $true

1. Tragen Sie die Origin der Business GPT-Applikation als vertrauenswürdig ein. Verwenden Sie hierfür die BGPT_REDIRECT_URI reduziert auf das Schema und den Host (ohne Pfad, z. B. https://demo.businessgpt.telekom.net):

Set-AdfsResponseHeaders -CORSTrustedOrigins "https://demo.businessgpt.telekom.net"

Sollen mehrere Origins zugelassen werden, geben Sie diese als Liste an:

Set-AdfsResponseHeaders -CORSTrustedOrigins @("https://demo.businessgpt.telekom.net", "https://anotherapp.example.com")

Wichtig: Set-AdfsResponseHeaders -CORSTrustedOrigins überschreibt die bestehende Liste vollständig. Übergeben Sie daher immer alle gewünschten Origins in einem Aufruf. Die Origin muss exakt mit Schema, Host und (falls abweichend von 443) Port übereinstimmen – ohne abschließenden Schrägstrich.

1. Überprüfen Sie die vorgenommene Konfiguration:

Get-AdfsResponseHeaders | Select-Object -ExpandProperty CORSTrustedOrigins

Die zuvor gesetzte(n) Origin(s) sollten in der Ausgabe erscheinen.

Zwischenstand: Was mit den Schritten 1–11 erreicht wurde

Mit dem Abschluss von Schritt 11 ist die grundlegende Anbindung von Business GPT an AD FS abgeschlossen und funktionsfähig. Konkret wurde Folgendes umgesetzt:

• Eine Application Group mit einer Native Application (öffentlicher Client mit BGPT_CLIENT_IDENTIFIER und BGPT_REDIRECT_URI) und einer Web API (Relying Party mit BGPT_CLIENT_IDENTIFIER) wurde angelegt.
• Über die Access Control Policy und die freigeschalteten Scopes (openid) ist geregelt, wer sich anmelden darf.
• Durch die Freigabe der CORS Trusted Origins kann die Business GPT-Applikation die AD FS-Endpunkte aus dem Browser heraus ansprechen.

Bedeutung für die Anmeldung: Ab diesem Punkt können sich berechtigte Benutzer bereits erfolgreich über AD FS an Business GPT authentifizieren. Das ausgestellte Token bestätigt die Identität des Benutzers. Es enthält jedoch noch keine zusätzlichen Berechtigungsinformationen wie Rollen (admin/user) oder Zugriffsrechte. Da Business GPT bei fehlendem roles-Claim implizit die Rolle user annimmt, meldet sich ein angemeldeter Benutzer zu diesem Zeitpunkt als normaler Benutzer ohne Administrationsrechte an.

Schritt 12: Eigenschaften der Web API öffnen

Was die folgenden Schritte 12–17 bewirken: In den nächsten Schritten wird das von AD FS ausgestellte Token gezielt um zusätzliche Claims angereichert. Während die Schritte 1–11 geregelt haben, ob sich ein Benutzer anmelden kann, bestimmen die Schritte 12–17, mit welchen Berechtigungen er in Business GPT arbeitet. Über sogenannte Issuance Transform Rules werden dabei insbesondere übertragen:

• die Rollen des Benutzers (admin bzw. user), die grundsätzlich über die Berechtigungsstufe innerhalb von Business GPT entscheiden,
• die Gruppenmitgliedschaften des Benutzers (groups-Claims) und
• der Anzeigename des Benutzers (name-Claim).

Wichtig – Bedeutung der Gruppen-Claims: Die übermittelten Gruppenmitgliedschaften sind nicht nur für Dokumenten-Container relevant. Business GPT bildet jedweden ressourcenbezogenen Nutzungszugriff über Gruppenmitgliedschaften ab – z. B. den Zugriff auf Dokumenten-Container, Assistenten und weitere gemanagte Ressourcen. Nur die Ressourcen, deren zugehörige Gruppe im groups-Claim des Tokens enthalten ist, werden dem Benutzer in Business GPT zugänglich gemacht. Fehlt die entsprechende Gruppenmitgliedschaft im Token, hat der Benutzer keinen Zugriff auf die jeweilige Ressource. Die in Schritt 15 gezeigte Konfiguration für Dokumenten-Container ist daher exemplarisch und gilt sinngemäß für alle über Gruppen gesteuerten Nutzungszugriffe.

Die Schritte 12 und 13 sind dabei die vorbereitenden Schritte, um die Registerkarte Issuance Transform Rules zu öffnen; in den Schritten 14 bis 16 werden die eigentlichen Regeln angelegt und in Schritt 17 gespeichert.

Damit die zusätzlichen Claims (insbesondere die Rollen admin/user sowie die Gruppenmitgliedschaften) im Token an Business GPT übermittelt werden, müssen in der Web API der Application Group entsprechende Issuance Transform Rules hinterlegt werden.

1. Doppelklicken Sie in der Liste unter Application Groups auf die zuvor angelegte Application Group (z. B. Business GPT), um deren Eigenschaften zu öffnen.
2. Wählen Sie im Bereich Applications die Web API aus (z. B. Business GPT - Web API).
3. Klicken Sie auf Edit…, um die Eigenschaften der Web API zu öffnen.

Schritt 13: Registerkarte "Issuance Transform Rules" öffnen

Im Eigenschaftenfenster der Web API:

1. Wechseln Sie auf die Registerkarte Issuance Transform Rules.
2. Klicken Sie auf Add Rule…, um den Assistenten für eine neue Ausstellungsregel (Add Transform Claim Rule Wizard) zu starten.

Schritt 14: Regel "Send Group Membership as a Claim" anlegen

Im Add Transform Claim Rule Wizard auf der Seite Choose Rule Type:

1. Wählen Sie unter Claim rule template den Eintrag Send Group Membership as a Claim.
2. Klicken Sie auf Next.

Auf der Seite Configure Claim Rule:

1. Vergeben Sie unter Claim rule name einen sprechenden Namen (z. B. admin membership as roles claim).
2. Wählen Sie unter User's group die betreffende Gruppe der administrativen BGPT-User aus.
3. Geben Sie als Outgoing claim type den folgenden Wert an: roles (direkt reinschreiben, nicht in der Vorauswahl enthalten)
4. Geben Sie als Outgoing claim value den folgenden Wert an: admin
5. Klicken Sie auf Finish.

1. Fügen Sie anschließend auf die gleiche Weise eine weitere Regel mit Add Rule… hinzu:
2. Claim rule template => Send Group Membership as a Claim
3. Claim rule name => user membership as roles claim
4. User's group => betreffende Gruppe der nicht-administrativen BGPT-User auswählen
5. Outgoing claim type => roles
6. Outgoing claim value => user

Schritt 15: Gruppenberechtigungen für Nutzungszugriffe als Claims über eine benutzerdefinierte Regel ausstellen

Gruppenberechtigungen

Nutzungszugriffe für Container, Assistenten und weitere Inhalte werden in Business GPT über Gruppen geregelt. Soll dieser Zugriff unterstützt werden, müssen Gruppenberechtigungen im Active Directory abgebildet, per ADFS-Claim-Konfiguration ermittelt und ausgegeben werden, um diese per Claims im Token zu übergeben.

Hinweis: Die hier gezeigte Konfiguration bezieht sich beispielhaft auf Dokumenten-Container, gilt aber sinngemäß für sämtliche über Gruppen gesteuerten Nutzungszugriffe in Business GPT (z. B. auch Assistenten). Grundlage ist immer die Ausstellung der relevanten Gruppenmitgliedschaften als groups-Claim: Business GPT gewährt einem Benutzer den Zugriff auf eine Ressource nur dann, wenn die zugehörige Gruppe im Token enthalten ist. Passen Sie das nachfolgend gezeigte Filtermuster (z. B. grp-bgpt-docstore) daher an Ihre jeweilige Namenskonvention und die abzubildenden Ressourcentypen an.

1. Klicken Sie auf der Registerkarte Issuance Transform Rules erneut auf Add Rule….
2. Wählen Sie unter Claim rule template den Eintrag Send Claims Using a Custom Rule und klicken Sie auf Next.

1. Konfigurieren Sie die Regel wie folgt:
2. Claim rule name: z. B. fetch all groupmemberships of the user

3. Custom rule: Tragen Sie die folgende Claim-Regel ein:

   c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
    => add(store = "Active Directory", types = ("groups"), query = ";tokenGroups;{0}", param = c.Value);
   

   4. Klicken Sie auf Finish.

1. Fügen Sie anschließend auf die gleiche Weise eine weitere Regel mit Add Rule… hinzu:
2. Claim rule template => Send Claims Using a Custom Rule
3. Claim rule name => filter for groups starting with grp-bgpt-docstore

4. Custom rule: Tragen Sie die folgende Claim-Regel ein:

   c:[Type == "groups", Value =~ "(?i)grp-bgpt-docstore"]
    => issue(claim = c);
   

Schritt 16: Anzeigename des Benutzers als Claim ausstellen (name)

Damit Business GPT den Anzeigenamen des angemeldeten Benutzers (z. B. zur Darstellung in der Oberfläche) erhält, wird das Active-Directory-Attribut displayName als name-Claim in das Token ausgestellt.

Hinweis: Diese Regel stellt den Anzeigenamen unabhängig vom angeforderten Scope bereit. Sie greift bei jeder interaktiven Benutzeranmeldung, sodass der name-Claim auch dann übermittelt wird, wenn die Anwendung den Scope profile nicht anfordert.

1. Klicken Sie auf der Registerkarte Issuance Transform Rules erneut auf Add Rule….
2. Wählen Sie unter Claim rule template den Eintrag Send Claims Using a Custom Rule und klicken Sie auf Next.
3. Konfigurieren Sie die Regel wie folgt:
4. Claim rule name: z. B. Send Name

5. Custom rule: Tragen Sie die folgende Claim-Regel ein:

   c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
    => issue(store = "Active Directory", types = ("name"), query = ";displayName;{0}", param = c.Value);
   

   4. Klicken Sie auf Finish.

Schritt 17: Regeln übernehmen und speichern

1. Prüfen Sie die angelegten Regeln in der Liste der Issuance Transform Rules.
2. Klicken Sie auf Apply und anschließend auf OK, um die Eigenschaften der Web API zu schließen.
3. Schließen Sie mit OK das Eigenschaftenfenster der Application Group.

Nachbereitung und Hinweise

• BGPT_CLIENT_IDENTIFIER ist in der BGPT-Anwendungskonfiguration hinterlegt.
• BGPT_REDIRECT_URI muss exakt mit der in BGPT konfigurierten URL übereinstimmen (inkl. Groß-/Kleinschreibung und abschließendem /).
• Änderungen an der Application Group sind jederzeit über die Eigenschaften möglich.
• Für die Fehlersuche stehen die AD FS-Ereignisprotokolle (Event Viewer → Applications and Services Logs → AD FS → Admin) zur Verfügung.

---

Technischer API-Zugang (api-User)

Neben der hier beschriebenen interaktiven Benutzeranmeldung kann optional ein technischer, serverseitiger API-Zugang ("api-User") eingerichtet werden, der die Business-GPT-API programmatisch über den client_credentials-Flow anspricht – ohne interaktive Anmeldung im Browser. Hierzu wird die oben angelegte Application Group um eine Server Application erweitert.

Die vollständige Schritt-für-Schritt-Anleitung dazu finden Sie unter API-Anbindung über AD FS (api-User).