API-Anbindung über AD FS (api-User)

Diese Anleitung beschreibt den technischen, serverseitigen API-Zugang ("api-User") für Business GPT über AD FS. Ein solcher Zugang wird verwendet, wenn ein Dienst oder System die Business-GPT-API programmatisch ansprechen soll – ohne interaktive Benutzeranmeldung im Browser. Hierzu wird eine bestehende Application Group um eine Server Application (vertraulicher Client mit Client Secret) erweitert, die über den client_credentials-Flow ein Token abruft. Diesem Zugang wird die Rolle roles = api ausgestellt, wodurch er sich von den menschlichen Nutzern (admin / user) abgrenzt.

Entra ID statt AD FS?

Wird der API-Zugang stattdessen über Entra ID (OAuth2 Client Credentials) eingerichtet, ist die Anleitung API-Anbindung über Entra ID einschlägig.

Voraussetzung: Die Application Group (z. B. Business GPT) wurde bereits gemäß der Dokumentation AD FS Anbindung für die interaktive Benutzeranmeldung angelegt. Während dort ein öffentlicher Client (Native Application) für die Nutzeranmeldung eingerichtet wird, wird hier ein vertraulicher Client (Server Application mit Client Secret) ergänzt.

Erweiterung einer bestehenden Application Group um eine Server Application (AD FS, UI-basiert)

Diese Dokumentation beschreibt Schritt für Schritt, wie eine bereits vorhandene Application Group in der grafischen Benutzeroberfläche der AD FS-Verwaltung (AD FS Management Console) um eine Server Application (vertraulicher Client) erweitert wird.

Notwendige Daten

Für die Konfiguration der Server Application müssen folgende Daten vorliegen:

• BGPT_APICLIENT_IDENTIFIER
• der Client Identifier, unter dem die neue Server App in der bestehenden Application Group angelegt wird (durch ADFS generiert oder manuell zu vergeben)
• BGPT_APICLIENT_SECRET (Ergebnis dieser Anleitung)
• das in Schritt 5 erzeugte Shared Secret muss sicher an das Team der Server-App übergeben werden
• 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 der Business GPT-Applikation, zu welcher der ADFS den Nutzer nach erfolgreicher Authentifizierung des serverseitigen Flows umleitet
• wird vom Business GPT-Team bereitgestellt

Voraussetzungen

Bevor Sie mit der Erweiterung 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.
• Die zu erweiternde Application Group (z. B. Business GPT) ist bereits vorhanden.
• Ihnen liegen die unter Notwendige Daten genannten Informationen vor.

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: Eigenschaften der bestehenden Application Group öffnen

1. Erweitern Sie im linken Navigationsbereich den Knoten AD FS.
2. Wählen Sie den Knoten Application Groups aus.

1. Doppelklicken Sie in der Liste auf die bestehende Application Group (z. B. Business GPT), um deren Eigenschaften zu öffnen.

Schritt 3: Neue Anwendung hinzufügen (Server application)

Im Eigenschaftenfenster der Application Group:

1. Klicken Sie im Bereich Applications auf Add application….

1. Wählen Sie im Assistenten unter Template die Vorlage:
2. Server application – vertraulicher Client mit Client Secret
3. Klicken Sie auf Next.

Schritt 4: Server Application konfigurieren (Client ID & Redirect URI)

Auf der Seite Server application:

1. Vergeben Sie unter Name einen sprechenden Namen (z. B. Business GPT - Server Application).
2. Der Assistent zeigt einen Client Identifier (Client ID). Dieser kann bleiben wie initial befüllt und wird im weiteren Verlauf der Dokumentation als BGPT_APICLIENT_IDENTIFIER bezeichnet. Bitte übernehmen Sie den Identifier in Ihre Unterlagen / technisches Konfigurationsmanagement.
3. Tragen Sie unter Redirect URI die bereitgestellte BGPT_REDIRECT_URI ein und klicken Sie auf Add, um die Übernahme in die darunter dargestellte Liste zu veranlassen. Die hier eingetragene Url wird an der Stelle nicht wirklich benötigt, der ADFS verlangt an dieser Stelle jedoch nach einer verpflichtenden Eingabe.
4. Klicken Sie auf Add um die Übernahme in die darunter dargestellte Liste zu veranlassen.
5. Klicken Sie auf Next.

Schritt 5: Client Secret konfigurieren

Auf der Seite Configure Application Credentials:

1. Aktivieren Sie die Option Generate a shared secret.
2. Der Assistent erzeugt ein Secret. Kopieren und speichern Sie diesen Wert sofort sicher ab – er wird später nicht mehr angezeigt. Dieser Wert ist das BGPT_APICLIENT_SECRET und muss an das Team der Server-App übergeben werden.
3. Klicken Sie auf Next.

Wichtig: Das Secret kann nachträglich nicht erneut ausgelesen werden. Bei Verlust muss ein neues Secret erzeugt werden.

Schritt 6: Zusammenfassung prüfen (Summary)

Auf der Seite Summary:

1. Prüfen Sie alle vorgenommenen Einstellungen (Name, Identifier, Redirect URI).
2. Bei Korrekturbedarf navigieren Sie mit Previous zurück.
3. Klicken Sie auf Next, um die Server Application zu erstellen.

Schritt 7: Anlage abschließen

Auf der Seite Complete:

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

1. Die neue Server Application erscheint nun im Bereich Applications der Application Group.

Schritt 8: Server Application in der vorhandenen Web API berechtigen (Application Permissions)

Die soeben angelegte Server Application ist zunächst kein berechtigter Client der bestehenden Web API. Damit die Server Application Tokens für die Web API anfordern darf, muss sie in den Client Permissions der vorhandenen Web API freigeschaltet werden.

1. Wählen Sie im Eigenschaftenfenster der Application Group im Bereich Applications die vorhandene Web API aus (z. B. Business GPT - Web API) und klicken Sie auf Edit….
2. Wechseln Sie im Eigenschaftenfenster der Web API auf die Registerkarte Client Permissions.
3. Klicken Sie unterhalb der Liste Client application (caller) auf Add….
4. Aktivieren Sie in der nun angezeigten Liste Add Clients die zuvor angelegte Business GPT - Server Application und bestätigen Sie mit Add….
5. Aktivieren Sie unter Permitted scopes die folgenden, notwendigen Scopes:
   • openid
6. Klicken Sie auf Apply und anschließend auf OK, um die Eigenschaften der Web API zu schließen.

1. Klicken Sie auf OK, um die Eigenschaften der Application Group zu schließen.

Schritt 9: Neue Access Control Policy anlegen und in Web API konfigurieren

Für den serverseitigen Zugriff der Server Application wird i. d. R. eine eigene Access Control Policy benötigt, die sowohl auf die Gruppen- zugehörigkeit der Benutzer als auch auf bestimmte Claims im Request abstellt.

Hinweis: Die mitgelieferten (Built-in) Access Control Policies sind nicht veränderbar. Sie müssen daher eine neue Richtlinie anlegen und diese anschließend in der Web API konfigurieren.

9.1 Neue Access Control Policy anlegen

1. Wählen Sie im linken Navigationsbereich der AD FS-Verwaltung den Knoten AD FS → Access Control Policies.
2. Klicken Sie im rechten Aktionen-Bereich auf Add Access Control Policy….
3. Vergeben Sie unter Name einen sprechenden Namen (z. B. Permit Business GPT - Application Access) und optional eine Description.
4. Fügen Sie im Bereich Permit über Add die benötigten Regeln hinzu:
5. Permit users from specific group – klicken Sie im Regel-Editor auf den Link . Wählen Sie im daraufhin angezeigten Dialog die Option Parameter specified when the access control policy is assigned und bestätigen Sie mit OK. Die konkrete Gruppe wird damit nicht bereits bei der Anlage der Richtlinie festgelegt, sondern erst bei deren Zuweisung in der Web API (siehe Schritt 9.2).
6. Permit users with specific claims in the request – klicken Sie auf den Link und wählen Sie ebenfalls die Option Parameter specified when the access control policy is assigned. Der konkrete Claim (z. B. der Name ID-Claim mit dem Wert von BGPT_APICLIENT_IDENTIFIER) wird ebenfalls erst bei der Zuweisung festgelegt.
7. Bestätigen Sie die Regeln und klicken Sie auf OK, um die Access Control Policy zu speichern.

Hinweis: Durch die Verwendung von Parameter specified when the access control policy is assigned bleibt die Richtlinie wiederverwendbar. Die konkreten Werte (Gruppe bzw. Claim) werden erst bei der Zuweisung an die jeweilige Web API abgefragt.

9.2 Access Control Policy in der Web API konfigurieren

1. Öffnen Sie die Eigenschaften der Application Group (z. B. Business GPT) und wählen Sie im Bereich Applications die Web API aus (z. B. Business GPT - Web API). Klicken Sie auf Edit….
2. Wechseln Sie im Eigenschaftenfenster der Web API auf die Registerkarte Access Control Policy.
3. Wählen Sie die soeben angelegte Richtlinie (z. B. Permit Business GPT - Application Access) aus.
4. Da die Richtlinie mit Parameter specified when the access control policy is assigned angelegt wurde, fordert AD FS Sie nun auf, die konkreten Parameter zu hinterlegen. Klicken Sie hierzu auf die eingeblendeten Parameter-Links und tragen Sie die tatsächlichen Werte ein:
5. Gruppe – die betreffende Gruppe der berechtigten Benutzer.
6. Claim – der geforderte Claim im Request (z. B. der Application Identifier-Claim mit dem Wert des Identifiers der Server App - BGPT_APICLIENT_IDENTIFIER).
7. Klicken Sie auf Apply und anschließend auf OK.

Schritt 10: Zusätzliche Issuance Transform Rule für die Server Application für Api-Rolle

Damit die Server Application beim serverseitigen Zugriff eine passende Rolle erhält, wird eine zusätzliche benutzerdefinierte Ausstellungsregel (Custom Rule) hinterlegt. Diese stellt anhand der App-ID der Server Application (BGPT_APICLIENT_IDENTIFIER) einen roles-Claim mit dem Wert api aus.

1. Öffnen Sie die Eigenschaften der Web API (z. B. Business GPT - Web API) und wechseln Sie auf die Registerkarte Issuance Transform Rules.
2. Klicken Sie auf Add Rule….
3. Wählen Sie unter Claim rule template den Eintrag Send Claims Using a Custom Rule und klicken Sie auf Next.
4. Konfigurieren Sie die Regel wie folgt:
5. Claim rule name: z. B. issue api role for server application

6. Custom rule: Tragen Sie die folgende Claim-Regel ein und ersetzen Sie <BGPT_APICLIENT_IDENTIFIER> durch die App-ID der Server Application:

   c:[Type == "http://schemas.microsoft.com/2014/01/clientcontext/claims/appid", Value == "<BGPT_APICLIENT_IDENTIFIER>"]
    => issue(Type = "roles", Value = "api");
   

7. Klicken Sie auf Finish.

8. Fügen Sie anschließend auf die gleiche Weise eine weitere Regel mit Add Rule… hinzu:

9. Claim rule template: Send Claims Using a Custom Rule
10. Claim rule name: z. B. issue idsub claim for server application

11. Custom rule: Tragen Sie die folgende Claim-Regel ein und ersetzen Sie <BGPT_APICLIENT_IDENTIFIER> durch die App-ID der Server Application:

    c:[Type == "http://schemas.microsoft.com/2014/01/clientcontext/claims/appid", Value == "<BGPT_APICLIENT_IDENTIFIER>"]
     => issue(Type = "idsub", Value = "<BGPT_APICLIENT_IDENTIFIER>");
    

    7. Klicken Sie auf Finish.

12. Klicken Sie auf Apply und anschließend auf OK, um die Eigenschaften der Web API zu schließen. Schließen Sie mit OK das Eigenschaftenfenster der Application Group.

Schritt 11: Zusätzliche Issuance Transform Rules für die Server Application für Zugriff auf gruppenbeschränkte Entitäten

Damit der api-Nutzer konsumierend (im Sinne von „Usage", z. B. für das Chatten und den Wissensabruf) auf gruppenbeschränkte Dokumenten-Container zugreifen kann, müssen ggf. ein oder mehrere zusätzliche benutzerdefinierte Ausstellungsregeln (Custom Rule) hinterlegt werden. Diese stellen anhand der App-ID der Server Application (BGPT_APICLIENT_IDENTIFIER) jeweils einen groups-Claim mit dem Namen der betreffenden Gruppe als Wert aus. Der api-Nutzer erhält dadurch Zugriff auf alle Dokumenten-Container (und Assistenten), die dieser Gruppe zugeordnet sind – genau wie ein menschlicher Nutzer, der Mitglied dieser Gruppe ist.

Wann diese Regeln nötig sind – und wann nicht

Die groups-Claims steuern ausschließlich den konsumierenden Zugriff auf gruppenbeschränkte Ressourcen. Dokumenten-Container und Assistenten ohne Gruppenzuordnung sind ohnehin für den api-Nutzer zugänglich und benötigen keine zusätzliche Regel. Ebenso wenig sind diese Regeln für die administrative Nutzung der API erforderlich (z. B. das Verwalten von Bereichen oder das Verwalten von Dokumenten in Containern ohne Bereichszuordnung): Diese Rechte ergeben sich bereits aus der Rolle api und sind nicht gruppenabhängig. Details hierzu finden Sie unter Berechtigungen der API-Rolle.

1. Öffnen Sie die Eigenschaften der Web API (z. B. Business GPT - Web API) und wechseln Sie auf die Registerkarte Issuance Transform Rules.
2. Klicken Sie auf Add Rule….
3. Wählen Sie unter Claim rule template den Eintrag Send Claims Using a Custom Rule und klicken Sie auf Next.
4. Konfigurieren Sie die Regel wie folgt, ersetzen Sie X durch einen eindeutigen Namen der Gruppe (dieser muss dem in Business GPT hinterlegten Gruppennamen entsprechen):
5. Claim rule name: z. B. issue groups claim for group X for server application

6. Custom rule: Tragen Sie die folgende Claim-Regel ein und ersetzen Sie <BGPT_APICLIENT_IDENTIFIER> durch die App-ID der Server Application:

   c:[Type == "http://schemas.microsoft.com/2014/01/clientcontext/claims/appid", Value == "<BGPT_APICLIENT_IDENTIFIER>"]
    => issue(Type = "groups", Value = "X");
   

7. Klicken Sie auf Finish.

8. Anschließend können Sie auf die gleiche Weise Regeln für den Zugriff des api-Nutzers auf weitere Gruppen hinzufügen.

9. Klicken Sie auf Apply und anschließend auf OK, um die Eigenschaften der Web API zu schließen. Schließen Sie mit OK das Eigenschaftenfenster der Application Group.

Nachbereitung und Hinweise

• Das erzeugte BGPT_APICLIENT_SECRET ist sicher an das Team der Server-App zu übergeben (nicht per unverschlüsseltem Kanal).
• BGPT_SERVER_REDIRECT_URI muss exakt mit der in Business GPT konfigurierten URL übereinstimmen (inkl. Groß-/Kleinschreibung und abschließendem /).
• Die zuvor angelegten Issuance Transform Rules der Web API greifen nur im Kontext einer echten Nutzeranmeldung über die Native-App. Die zwei hinzugefügten neuen Rules finden nur Anwendung im Kontext der neuen Server-App.
• Änderungen an der Server Application sind jederzeit über die Eigenschaften der Application Group möglich.
• Weitere Server-Apps können hinzugefügt werden. Es muss dann neben der Anlage der Server-App auch wieder jeweils
• die Server-App auf der Web API berechtigt werden -> Schritt 8
• eine Erweiterung der Access Control Policy um zusätzlichen Name ID Claim -> Schritt 9
• eine Erweiterung der Claim Rules in den Issuance Transform Rules -> Schritt 10
• eine Erweiterung der Claim Rules in den Issuance Transform Rules für den Zugriff auf gruppenbeschränkte Entitäten wie Dokumenten-Container oder Assistenten -> Schritt 11
• Für die Fehlersuche stehen die AD FS-Ereignisprotokolle (Event Viewer → Applications and Services Logs → AD FS → Admin) zur Verfügung.

Beispiel für Token-Abruf

Nach vollzogener Konfiguration kann der Abruf eines gültigen Tokens vom ADFS erfolgen. Dazu ist folgender Request durchzuführen:

• Methode: POST
• Host: https://adfs.hostname.de/adfs/oauth2/token
• Header
  • content-type: application/x-www-form-urlencoded
• Body (Übermittlung Url-encoded für die folgenden Parameter im Body)
  • grant_type: client_credentials
  • client_id: BGPT_APICLIENT_IDENTIFIER
  • client_secret: BGPT_APICLIENT_SECRET
  • scope: openid
  • resource: BGPT_CLIENT_IDENTIFIER

Anschließend erhält man vom ADFS ein 'accessToken', welches dann bei API-Requests gegen die BGPT-API als Bearer Token verwendet werden kann.

Nächster Schritt: API-Referenz

Eine vollständige Übersicht aller verfügbaren Endpunkte samt Parametern sowie Anfrage- und Antwortschemata finden Sie in der API-Dokumentation.