Freigeben über

Aktivieren des einmaligen Anmeldens für API-basierte Nachrichtenerweiterungen

  • Artikel

Die Authentifizierungsmethode für einmaliges Anmelden (Single Sign-On, SSO) für die API-basierte Nachrichtenerweiterung verwendet die Teams-Identität eines App-Benutzers, um ihnen Zugriff auf Ihre App zu gewähren. Ein Benutzer, der sich bei Teams angemeldet hat, muss sich innerhalb der Teams-Umgebung nicht erneut bei Ihrer App anmelden. Microsoft Entra SSO ermöglicht es der App, im Hintergrund ein Benutzertoken abzurufen, das von Microsoft Entra für ihre Ressource ausgegeben wird. Die App kann dieses Token dann authentifizieren und die Benutzerprofilinformationen ohne Zustimmung des Benutzers abrufen.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie über Folgendes verfügen:

  • Ein Azure-Konto mit einem aktiven Abonnement.
  • Grundlegende Kenntnisse in der entwicklung von Microsoft Entra ID und Teams-Apps.

Die folgende Abbildung zeigt, wie einmaliges Anmelden funktioniert, wenn ein Teams-App-Benutzer versucht, auf eine API-basierte Nachrichtenerweiterungs-App zuzugreifen:

Screenshot, der zeigt, wie Microsoft Entra SSO-Autorisierung funktioniert, um die API-basierte Nachrichtenerweiterung zu authentifizieren.

  • Der Benutzer ruft die API-basierte Nachrichtenerweiterungs-App in Teams auf und ruft einen Befehl auf, der eine Authentifizierung erfordert.
  • Die App sendet eine Anforderung mit der App-ID und dem erforderlichen Bereich (access_as_user) an den Teams-Back-End-Dienst.
  • Der Teams-Back-End-Dienst überprüft, ob der Benutzer der App und dem Bereich zugestimmt hat. Andernfalls wird dem Benutzer ein Zustimmungsbildschirm angezeigt.
  • Wenn der Benutzer zustimmt, generiert Microsoft Entra ein Zugriffstoken für den Benutzer und die App und sendet es an die App im Autorisierungsheader der Anforderung.
  • Die App überprüft das Token und extrahiert die Benutzerinformationen aus dem Token, z. B. den Namen, die E-Mail-Adresse und die Objekt-ID.
  • Nach erfolgreicher Authentifizierung erhält der Benutzer Zugriff auf die API-basierte Nachrichtenerweiterung.

Führen Sie die folgenden Schritte aus, um die SSO-Authentifizierung für die API-basierte Nachrichtenerweiterung zu aktivieren:

Registrieren einer neuen App in Microsoft Entra ID

  1. Öffnen Sie das Azure-Portal in Ihrem Webbrowser.

  2. Wählen Sie das Symbol App-Registrierungen aus.

    Screenshot: Seite

    Die Seite App-Registrierungen wird angezeigt.

  3. Wählen Sie das Symbol + Neue Registrierung aus.

    Screenshot: Neue Registrierungsseite auf Microsoft Entra Admin Center

    Die Seite Anwendung registrieren wird angezeigt.

  4. Geben Sie den Namen Ihrer App ein, die dem App-Benutzer angezeigt werden soll. Sie können den Namen zu einem späteren Zeitpunkt ändern, wenn Sie möchten.

    Screenshot: Seite

  5. Wählen Sie den Typ des Benutzerkontos aus, das auf Ihre App zugreifen kann. Sie können aus einzel- oder mehrinstanzenfähigen Optionen in Organisationsverzeichnissen auswählen oder den Zugriff nur auf persönliche Microsoft-Konten beschränken.

    Optionen für unterstützte Kontotypen
    Option Wählen Sie dies aus, um...
    Nur Konten in diesem Organisationsverzeichnis (nur Microsoft – einzelner Mandant) Erstellen Sie eine Anwendung, die nur von Benutzern (oder Gästen) in Ihrem Mandanten verwendet werden kann.
    Diese App wird häufig als benutzerdefinierte App bezeichnet, die für Ihre Organisation (LOB-App) erstellt wurde. Diese App ist eine Einzelmandantenanwendung im Microsoft Identity Platform.
    Konten in einem beliebigen Organisationsverzeichnis (beliebiger Microsoft Entra ID Mandanten – mehrinstanzenfähig) Ermöglichen Sie Benutzern in einem beliebigen Microsoft Entra Mandanten, Ihre Anwendung zu verwenden. Diese Option ist z. B. geeignet, wenn Sie eine SaaS-Anwendung erstellen und diese für mehrere Organisationen verfügbar machen möchten.
    Dieser App-Typ wird im Microsoft Identity Platform als mehrinstanzenfähige Anwendung bezeichnet.
    Konten in einem beliebigen Organisationsverzeichnis (beliebiger Microsoft Entra ID Mandanten – mehrinstanzenfähig) und persönliche Microsoft-Konten (z. B. Skype, Xbox) Sprechen Sie die breiteste Kundengruppe an.
    Wenn Sie diese Option auswählen, registrieren Sie eine mehrinstanzenfähige Anwendung, die auch App-Benutzer unterstützen kann, die über persönliche Microsoft-Konten verfügen.
    Nur persönliche Microsoft-Konten Erstellen Sie eine Anwendung nur für Benutzer, die über persönliche Microsoft-Konten verfügen.

    Hinweis

    Sie müssen keinen Umleitungs-URI eingeben, um einmaliges Anmelden für eine API-basierte Nachrichtenerweiterungs-App zu aktivieren.

  6. Wählen Sie Registrieren aus. Im Browser wird eine Nachricht angezeigt, die besagt, dass die App erstellt wurde.

    Screenshot: Beispiel für die Benachrichtigung nach erfolgreicher App-Registrierung auf Azure-Portal

    Die Seite mit der App-ID und anderen App-Details wird angezeigt.

    Screenshot: Seite mit App-Details in Azure-Portal

  7. Notieren Und speichern Sie die App-ID aus der Anwendungs-ID (Client-ID), um das App-Manifest später zu aktualisieren.

    Ihre App ist in Microsoft Entra ID registriert. Sie verfügen jetzt über die App-ID für Ihre API-basierte Nachrichtenerweiterungs-App.

Konfigurieren des Bereichs für das Zugriffstoken

Nachdem Sie eine neue App-Registrierung erstellt haben, konfigurieren Sie Bereichsoptionen (Berechtigungsoptionen) zum Senden von Zugriffstoken an den Teams-Client und Autorisieren vertrauenswürdiger Clientanwendungen zum Aktivieren des einmaligen Anmeldens.

Um den Bereich zu konfigurieren und vertrauenswürdige Clientanwendungen zu autorisieren, müssen Sie:

  • App-ID-URI hinzufügen: Konfigurieren Sie Bereichsoptionen (Berechtigungsoptionen) für Ihre App. Machen Sie eine Web-API verfügbar, und konfigurieren Sie den App-ID-URI.
  • API-Bereich konfigurieren: Definieren Sie den Bereich für die API und die Benutzer, die für einen Bereich zustimmen können. Sie können festlegen, dass nur Admins die Zustimmung für höher privilegierte Berechtigungen erteilen.
  • Konfigurieren einer autorisierten Clientanwendung: Erstellen Sie autorisierte Client-IDs für Anwendungen, die Sie vorab authentifizieren möchten. Dadurch kann der App-Benutzer auf die von Ihnen konfigurierten App-Bereiche (Berechtigungen) zugreifen, ohne dass eine weitere Zustimmung erforderlich ist. Authentifizieren Sie nur die Clientanwendungen, denen Sie vertrauen, da Ihre App-Benutzer nicht die Möglichkeit haben, die Zustimmung abzulehnen.

App-ID-URI

  1. Wählen Sie im linken Bereich Verwalten>Eine API verfügbar machen aus.

    Die Seite API verfügbar machen wird angezeigt.

  2. Wählen Sie Hinzufügen aus, um den App-ID-URI im Format zu api://{AppID}generieren.

    Screenshot: Festlegen des App-ID-URI

    Der Abschnitt zum Festlegen des App-ID-URI wird angezeigt.

  3. Geben Sie den Anwendungs-ID-URI im hier erläuterten Format ein.

    Screenshot: App-ID-URI in Microsoft Entra ID

    • Der Anwendungs-ID-URI ist vorab mit der App-ID (GUID) im Format api://{AppID}ausgefüllt.
    • Das App-ID-URI-Format muss wie folgt sein: api://fully-qualified-domain-name.com/{AppID}.
    • Fügen Sie die fully-qualified-domain-name.com zwischen api:// und {AppID} (d. h. der GUID) ein. Beispiel: api://example.com/{AppID}.

    Wichtig

    • Wenn Sie einen eigenständigen Bot erstellen, geben Sie den App-ID-URI als api://botid-{YourBotId} ein. Hier ist {YourBotId} Ihre Microsoft Entra App-ID.
    • Wenn Sie eine App mit einem Bot, einer Nachrichtenerweiterung und einer Registerkarte erstellen, geben Sie den App-ID-URI als api://fully-qualified-domain-name.com/botid-{YourClientId} ein, wobei {YourClientId} Ihre Bot-App-ID ist.
    • Wenn Sie eine App mit einer Nachrichtenerweiterung oder Registerkartenfunktionen ohne den Bot erstellen, geben Sie den App-ID-URI als api://fully-qualified-domain-name.com/{YourClientId} ein, wobei {YourClientId} Ihre Microsoft Entra App-ID ist.
    • Anwendungs-ID-URI für Eine App mit mehreren Funktionen: Wenn Sie eine API-basierte Nachrichtenerweiterung erstellen, geben Sie den App-ID-URI als api://fully-qualified-domain-name.com/{YourClientId}ein, wobei {YourClientId} Ihre Microsoft Entra App-ID ist.
    • Format für Domänenname: Verwenden Sie nur Kleinbuchstaben für Domänennamen.

  4. Klicken Sie auf Speichern.

    Im Browser wird eine Meldung angezeigt, die besagt, dass der App-ID-URI aktualisiert wurde.

    Screenshot: Meldung der App-ID-URI

    Der App-ID-URI wird auf der Seite angezeigt.

    Screenshot: Aktualisierter App-ID-URI

  5. Notieren und speichern Sie den App-ID-URI, um das App-Manifest später zu aktualisieren.

Konfigurieren des API-Bereichs

Hinweis

  • Die API-basierte Nachrichtenerweiterung unterstützt nur den bereich access_as_user .
  • Die API empfängt ein Microsoft Entra-Zugriffstoken, wobei der Bereich auf access_as_user als im Azure-Portal registriert festgelegt ist. Das Token ist jedoch nicht berechtigt, andere Downstream-APIs wie Microsoft Graph aufzurufen.

  1. Wählen Sie + Bereich hinzufügen im Abschnitt Bereiche, die von dieser API definiert werden aus.

    Screenshot: Option

    Die Seite Einen Bereich hinzufügen wird angezeigt.

  2. Geben Sie die Details zum Konfigurieren des Bereichs ein.

    Der Screenshot zeigt, wie Sie Bereichsdetails in Azure hinzufügen.

    1. Geben Sie den Bereichsnamen ein. Dieses Feld ist obligatorisch.
    2. Wählen Sie den Benutzer aus, der die Zustimmung für diesen Bereich erteilen kann. Die Standardoption ist Nur Administratoren.
    3. Geben Sie den Anzeigename der Administratoreinwilligung ein. Dieses Feld ist obligatorisch.
    4. Geben Sie die Beschreibung für die Administratoreinwilligung ein. Dieses Feld ist obligatorisch.
    5. Geben Sie den Anzeigename der Benutzereinwilligung ein.
    6. Geben Sie die Beschreibung für die Benutzereinwilligung ein.
    7. Wählen Sie die Option Aktiviert für den Status aus.
    8. Klicken Sie auf Bereich hinzufügen.

    Im Browser wird eine Meldung angezeigt, die besagt, dass der Bereich hinzugefügt wurde.

    Screenshot: Meldung zum Hinzufügen des Bereichs

    Der von Ihnen definierte neue Bereich wird auf der Seite angezeigt.

    Screenshot: Beispiel für den Bereich, der der App in Azure-Portal hinzugefügt wurde.

Konfigurieren einer autorisierten Clientanwendung

  1. Navigieren Sie zur Seite Api verfügbar machen zum Abschnitt Autorisierte Clientanwendung , und wählen Sie + Clientanwendung hinzufügen aus.

    Screenshot: Autorisierte Clientanwendung

    Die Seite Ein Clientanwendung hinzufügen wird angezeigt.

  2. Geben Sie die entsprechende Microsoft 365-Client-ID für die Anwendungen ein, die Sie für die Webanwendung Ihrer App autorisieren möchten.

    Screenshot: Option

    Hinweis

    Die Microsoft 365-Client-IDs für mobile Apps, Desktop- und Web-Apps für Teams sind die tatsächlichen IDs, die Sie hinzufügen müssen.

    1. Wählen Sie eine der folgenden Client-IDs aus:

      Client-ID verwenden Zum Autorisieren...
      1fec8e78-bce4-4aaf-ab1b-5451cc387264 Mobile Teams- oder Desktop-App
      5e3ce6c0-2b1f-4285-8d4b-75ee78787346 Microsoft Teams-Web-App

    2. Wählen Sie den App-ID-URI aus, den Sie für Ihre App in Autorisierte Bereiche erstellt haben, um den Bereich der Web-API hinzuzufügen, die Sie verfügbar gemacht haben.

    3. Wählen Sie Anwendung hinzufügen aus.

      Im Browser wird eine Meldung angezeigt, die besagt, dass die autorisierte Client-App hinzugefügt wurde.

      Screenshot: Meldung

      Die Client-ID der autorisierten App wird auf der Seite angezeigt.

      Screenshot: Hinzugefügte Client-App

Hinweis

Sie können mehr als eine Clientanwendung autorisieren. Wiederholen Sie die Schritte dieses Verfahrens zum Konfigurieren einer anderen autorisierten Clientanwendung.

Sie haben app-Bereich, Berechtigungen und Clientanwendungen erfolgreich konfiguriert. Achten Sie darauf, dass Sie den App-ID-URI notieren und speichern. Als Nächstes konfigurieren Sie die Zugriffstokenversion.

Token authentifizieren

Wenn die Nachrichtenerweiterung die API während der Authentifizierung aufruft, empfängt sie eine Anforderung mit dem Zugriffstoken des Benutzers. Die Nachrichtenerweiterung fügt dann das Token im Autorisierungsheader der ausgehenden HTTP-Anforderung hinzu. Das Headerformat ist Authorization: Bearer <token_value>. Beispielsweise, wenn eine Nachrichtenerweiterung einen API-Aufruf an einen Dienst sendet, der eine Authentifizierung erfordert. Die Erweiterung erstellt eine HTTP-Anforderung wie folgt:

GET /api/resource HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Nachdem die API-basierte Nachrichtenerweiterung einen Anforderungsheader mit Token abgerufen hat, führen Sie die folgenden Schritte aus:

  • Authentifizieren: Überprüfen Sie das Token für die Ansprüche "Zielgruppe", "Bereich", "Aussteller" und "Signatur", um zu überprüfen, ob das Token für Ihre App gilt. Weitere Ansprüche finden Sie unter ID-Tokenansprüche.

    Das folgende Beispiel zeigt das JSON-Webtoken (JWT) mit einem Header und einer Antwort:

    {
"typ": "JWT",
"rh": "0.AhoAv4j5cvGGr0GRqy180BHbR6Rnn7s7iddIqxdA7UZsDxYaABY.",
"alg": "RS256",
"kid": "q-23falevZhhD3hm9CQbkP5MQyU"
}.{
  "aud": "00000002-0000-0000-c000-000000000000",
  "iss": "https://login.microsoftonline.com/72f988bf-86f1-41af-91ab-2d7cd011db47/v2.0",
  "iat": 1712509315,
  "nbf": 1712509315,
  "exp": 1712513961,
  "aio": "Y2NgYEjJqF0stqv73u41a6ZmxPEvBgA=",
  "azp": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
  "azpacr": "0",
  "name": "John Doe",
  "oid": "00000000-0000-0000-0000-000000000000",
  "preferred_username": "john.doe@contoso.com",
  "rh": "I",
  "scp": "access_as_user",
  "sub": "e4uM7JgAEm08GBuasSltQjvPuMX1fR5TqxopJpqZJB8",
  "tid": "12345678-aaaa-bbbb-cccc-9876543210ab",
  "uti": "h7DMQwSPAEeiEe62JJUGAA",
  "ver": "2.0"
  }

  • Verwenden Sie das Token: Extrahieren Sie die Benutzerinformationen aus dem Token, z. B. Name, E-Mail-Adresse und Objekt-ID, und verwenden Sie das Token, um die eigene API der Nachrichtenerweiterungs-App aufzurufen. Weitere Informationen zur Anspruchsreferenz mit Details zu den in Zugriffstoken enthaltenen Ansprüchen finden Sie unter Zugriffstokenansprüche.

Aktualisieren des App-Manifests

Aktualisieren Sie die folgenden Eigenschaften in der App-Manifestdatei:

  • webApplicationInfo: Die webApplicationInfo -Eigenschaft wird verwendet, um SSO für Ihre App zu aktivieren, damit App-Benutzer nahtlos auf Ihre API-basierte Nachrichtenerweiterungs-App zugreifen können. Der App-ID-URI, den Sie in Microsoft Entra ID registriert haben, ist mit dem Bereich der API konfiguriert, die Sie verfügbar gemacht haben. Weitere Informationen finden Sie unter webApplicationInfo.

       Screenshot: Konfiguration des App-Manifests

  • microsoftEntraConfiguration: Aktiviert die SSO-Authentifizierung für Ihre App. Konfigurieren Sie die supportsSingleSignOn -Eigenschaft auf, um true einmaliges Anmelden zu unterstützen und den Bedarf an mehreren Authentifizierungen zu reduzieren. Wenn die Eigenschaft auf false festgelegt ist oder leer bleibt, kann der Benutzer die App nicht in Teams hochladen, und die App kann nicht überprüft werden.

So konfigurieren Sie das App-Manifest:

  1. Öffnen Sie die API-basierte Nachrichtenerweiterungs-App.

  2. Öffnen Sie den App-Manifestordner.

    Hinweis

  3. die Datei manifest.json öffnen.

  4. Fügen Sie dem Abschnitt Ihrer App-Manifestdatei den webApplicationInfo folgenden Codeausschnitt hinzu:

    "webApplicationInfo":
{
"id": "{Microsoft Entra AppId}",
"resource": "api://subdomain.example.com/{Microsoft Entra AppId}"
}

    Dabei gilt Folgendes:

    • {Microsoft Entra AppId}ist die App-ID, die Sie erstellt haben, als Sie Ihre App in Microsoft Entra ID registriert haben. Es ist die GUID.
    • api://subdomain.example.com/{Microsoft Entra AppId}ist der App-ID-URI, den Sie beim Erstellen des Bereichs in Microsoft Entra ID registriert haben.

  5. Fügen Sie dem Abschnitt Ihrer App-Manifestdatei den composeExtensions folgenden Codeausschnitt hinzu:

    "authorization": {
  "authType": "microsoftEntra",
  “microsoftEntraConfiguration”: {
    “supportsSingleSignOn”: true
  }
},

  6. Speichern Sie die App-Manifestdatei.

Herzlichen Glückwunsch! Sie haben einmaliges Anmelden für Ihre API-basierten Nachrichtenerweiterungen aktiviert.

Siehe auch