Zum Inhalt

Business GPT – Entra ID

Die nachfolgende Dokumentation erläutert die erforderlichen Voraussetzungen sowie die Einrichtung von Entra ID für die Nutzung von Business GPT.

1 Beistellungen für die Integration des Entra IDs

Folgende Informationen werden für das Einrichten von Entra ID seitens der Deutschen Telekom MMS (MMS) benötigt:

  • Directory (tenant) ID
  • Application (client) ID

Für den Erhalt der Daten ist es notwendig, dass zunächst eine App Registration angelegt wird.

2 Anlegen einer App Registration

2.1 Setup App Registration

Folgende Schritte sind im Folgenden auszuführen:

  1. Melden Sie sich beim Microsoft Entra Admin Center an.
  2. Klicken Sie auf Microsoft Entra ID im linken Menü und wählen Sie App registrations aus.
  3. Klicken Sie auf New registration.
  4. Geben Sie einen Namen für Ihre Anwendung ein.
  5. Wählen Sie
    Accounts in this organizational directory only (KUNDE only - Single tenant).
    Hinweis: KUNDE ist an dieser Stelle ein Platzhalter und kann frei benannt werden.
  6. Geben Sie eine Single-page application (SPA) ein (wird vom Business GPT Support geliefert). Dies ist die URL, auf die Benutzer nach der Anmeldung umgeleitet werden.
    Entra ID
  7. Klicken Sie auf Register.

2.2 Anpassung des Manifests

Für eine verbesserte Nutzung der API Funktionalitäten und um den Sicherheitsstandard in der Übertragung von Datenverkehr zu erhöhen, ist im Manifest die verwendete Tokenversion anzupassen. Dafür sind die folgenden Schritte durchzuführen:

  1. Wählen Sie die zuvor erstelle App Registration aus
  2. Unter dem Reiter Manage klicken Sie auf Manifest
  3. Ändern Sie die requestedAccessTokenVersion innerhalb des Manifests auf den Wert 2 und speichern Sie die Änderung

Entra ID

2.3 (Nachträgliches) Hinzufügen einer Redirect-URI

Um eine Redirect-URI für eine Single-Page-Application (SPA) in Azure Entra ID nachträglich hinzuzufügen, sind die folgenden Schritte durchzuführen:

  1. Wählen Sie die App Registration aus, für die Sie die Redirect-URI hinzufügen möchten.
  2. Klicken Sie auf Authentication im linken Menü.
  3. Klicken Sie auf Add URI im Feld Single-page application.
  4. Geben Sie die URL der Redirect-URI in das Feld ein.
  5. Klicken Sie auf Save.
    Entra ID

2.4 Anpassung der Einstellungen in der Enterprise Application

Für das Anpassen von Einstellungen wählen Sie folgende Menüpunkte aus:

  1. Navigieren Sie zu App registrations und klicken Sie im Anschluss auf Overview.
  2. Wählen Sie die Managed application (Enterprise Application) aus.
    Entra ID
  3. Wechseln Sie zu Properties.
  4. Selektieren Sie Yes im Feld Assignment required.
  5. Klicken Sie abschließend auf Save.
    Entra ID

2.4.1 Anlegen von Usern, Rollen und zuweisen von Gruppen

Die User, die Zugriff auf Business GPT erhalten, müssen der App Registration zugewiesen werden. Hierfür müssen zwei Rollen bzw. Gruppen (user und admin) angelegt werden. Dafür folgen Sie den nachstehenden Anweisungen:

  1. Wählen Sie innerhalb der Enterprise Application den Punkt App roles aus.
    Entra ID
  2. Innerhalb von App roles klicken Sie auf Create app role.
    Entra ID

Admin-Rolle anlegen

  1. Legen Sie die admin role an.
    Hierbei ist es wichtig, dass das Feld Value den Wert admin enthält.
    Entra ID

User-Rolle anlegen

  1. Legen Sie die user role an.
    Hierbei ist es wichtig, dass das Feld Value den Wert user enthält.
    Entra ID

Optional: API-Rolle anlegen

  1. Legen Sie (optional) die api role an, sofern Sie die BGPT API ansprechen möchten. Hierbei ist es wichtig, dass das Feld Value den Wert apienthält Entra ID

User/Gruppen der Applikation zuweisen

  1. Wechseln Sie wieder in die Enterprise Application und wählen Sie Users and groups aus.
    Entra ID
  2. Fügen Sie neue User- und Gruppen/Rollen-Beziehungen hinzu.
    Entra ID
  3. Wählen Sie die entsprechenden User über None selected aus.
    Entra ID Entra ID
  4. Weisen Sie eine Rolle für die zuvor ausgewählten User über None selected zu.

Sofern mindestens eine P1 Lizenz (Entra ID) vorliegt, können an dieser Stelle für den entsprechenden User ebenfalls Gruppen, die der App Registration zugewiesen sind, ausgewählt werden.
Entra ID

  1. Wählen Sie user oder admin für die User aus.
    Entra ID
  2. Bestätigen Sie die getroffene Auswahl über Assign.
    Entra ID
  3. Nach Erstellung ist der User mit den entsprechenden Credentials (Rolle/Gruppe) sichtbar.
    Entra ID

2.5 Einrichten von Group Claiming

Durch das Groups Claiming wird gesteuert, welche Gruppen via Token beim Zugriff auf Business GPT übermittelt werden. Diese werden genutzt, um den Zugriff auf Container (ab Paket L) zu administrieren. Gehen Sie wie folgt vor:

  1. Wählen Sie innerhalb der zuvor erstellten App Registration unter dem Reiter Manage den Punkt Token configuration aus und klicken Sie auf Add groups claim.
    Entra ID

  2. Die Auswahl der group types ist abhängig von der in Ihrem Unternehmen vorliegenden Entra ID Struktur und der Lizenz.

Standardmäßig wählen Sie bei einem lizensierten Entra ID folgenden group type aus und klicken abschließend auf Add
(das Groups Claiming kann jederzeit gelöscht und neu erstellt werden, um mit den Einstellungen zu testen):

  • Groups assigned to the application (recommended for large enterprise companies …)

    • Diese Option hat den Vorteil, dass nur der Enterprise-Applikation zugewiesene Gruppen im Anmeldetoken übertragen werden
      (sinnvoll für Gruppenzuordnung in BPT).
      Entra ID

  • All Groups ggf. verwenden, wenn keine Entra-ID Lizenzierung vorhanden ist (Free Version).

  • In einer nicht lizensierten Version können der Enterprise-Applikation keine Gruppen direkt zugeordnet werden.

  • Directory roles können ggf. auch weggelassen werden.

Entra ID

  1. Nach der Erstellung des entsprechenden Group Claims wird dieser in der Übersicht gelistet.

Entra ID

2.6 Informationen zu Directory (tenant) ID und Application (client) ID ermitteln

Die nach dem Anlegen der App Registration erzeugten Informationen zu Directory (tenant) ID sowie Application (client) ID sind unter Overview innerhalb der App Registration zu finden:

Entra ID

Diese Informationen werden an die MMS übermittelt.

3 Die App berechtigen

Der Admin des Entra IDs muss sich zuerst innerhalb von Business GPT anmelden.

Im Anschluss wird folgendes Pop-up-Fenster angezeigt:

  1. Setzen Sie den Haken bei Zustimmen im Namen Ihrer Organisation.
  2. Bestätigen Sie mit Akzeptieren.

Entra ID

Damit sind die erforderlichen Berechtigungen für die App erteilt.

4 (Optional) Anlegen API-User

Möchten Sie einen API-User anlegen, gehen Sie bitte folgendermaßen vor. Bei Bedarf nutzen Sie bitte die detaillierte Beschreibung der nötigen Schritte hier: API-Anbindung

4.1 Notwendige Informationen für das Anlegen des API-Users

Die nachfolgenden Informationen sind für die Nutzung des API-Users erforderlich.
Um diese Informationen zu erhalten, müssen die Schritte, beschrieben ab Kapitel App Registration, durchlaufen werden.

API-User App Registration (Parameter):

  • Application (client) ID
  • Client secret Value
  • Directory (tenant) ID
  • Backend URL

4.2 Anlegen der App Registration für die Nutzung des API-Users

In diesem Schritt wird eine weitere App Registration angelegt, die einen geringeren Berechtigungsumfang aufweist als die zuvor eingerichtete.

Damit können die Rechte des API-Users administriert und Fehlbedienungen vermieden werden.

Gehen Sie wie folgt vor:

  1. Geben Sie im Feld Name eine von Ihnen frei gewählte Bezeichnung ein.
  2. Unter Supported account types ist zwingend die Option
    Accounts in this organizational directory only (KUNDE only – Single tenant) auszuwählen.
  3. Klicken Sie danach auf Register.

Entra ID

4.3 Hinzufügen von Berechtigung (API permission)

Im nächsten Schritt wird die Berechtigung für den Zugriff auf die zuvor erstellte App Registration erteilt.

  1. Klicken Sie im Menü der erstellten App Registration auf API permissions und wählen dort Add a permission aus.
    Entra ID
  2. Selektieren Sie die App Registration, für welche die API berechtigt werden soll, und klicken Sie diese an.
    Entra ID
  3. Klicken Sie auf Application permissions und wählen Sie die Option api aus.
  4. Klicken Sie abschließend auf Add permissions.
    Entra ID

Zum Schluss muss die Berechtigung freigeschaltet werden.

  1. Wählen Sie in der für den API-User erstellten App Registration unter dem Reiter Security die Maske Permissions aus.
  2. Klicken Sie im Anschluss auf Grant admin consent für KUNDE.
    Entra ID

In der Übersicht der zugewiesenen Berechtigungen sehen Sie anschließend die freigeschalteten Permissions.

Entra ID