Einmaliges Anmelden hinzufügen

  • 6 Minuten

In dieser Lerneinheit erfahren Sie, wie Sie mithilfe von Microsoft Entra einer Nachrichtenerweiterung einmaliges Anmelden hinzufügen.

Konfigurieren der Teams-App mit einmaligem Anmelden

Die Microsoft Teams-App unterstützt einmaliges Anmelden (Single Sign-On, SSO) mit Microsoft Entra. SSO ermöglicht Benutzern, sich einmal anzumelden und auf mehrere Anwendungen zuzugreifen, ohne sich erneut anmelden zu müssen.

Zum Konfigurieren des einmaligen Anmeldens konfigurieren Sie die Microsoft Entra-App-Registrierung der Azure Bot-Ressource so, dass Anforderungen im Namen des Benutzers gesendet werden.

Screenshot der Seite

Bei der Registrierung der Microsoft Entra-App konfigurieren Sie die folgenden Einstellungen:

  • Anwendungs-ID-URI, ein eindeutiger Bezeichner für die App-Registrierung, der verwendet wird, um die Ressource zu identifizieren, die der Client beim Initiieren eines SSO-Flows in der App verwenden soll.
  • Bereiche: die Berechtigung, die Ihrem Bot für den Zugriff auf Benutzerdaten gewährt wird.
  • Autorisierte Clientanwendungen, die Clientanwendungen, die Token von der App-Registrierung anfordern dürfen.

Im App-Manifest wird das webApplicationInfo-Objekt mit der ID des Bots und dem Anwendungs-ID-URI konfiguriert. Sie bestimmen die Ressource, die der Client beim Initiieren eines SSO-Flows in der App verwenden soll.

Der folgende Codeausschnitt zeigt, wie das webApplicationInfo-Objekt in der App-Manifestdatei konfiguriert wird:

"webApplicationInfo": {
    "id": "dbeb8ea7-8ac3-4bb2-bcba-b210b087a73a",
    "resource": "api://grttxrk0-5130.uks1.devtunnels.ms/botid-dbeb8ea7-8ac3-4bb2-bcba-b210b087a73a"
}

Konfigurieren einer OAuth-Verbindung

Die Azure Bot-Ressource bietet Zugriff auf den Bot Framework-Tokendienst. Der Tokendienst wird verwendet, um mithilfe der von Ihnen konfigurierten OAuth-Verbindungseinstellungen ein Zugriffstoken für den Benutzer abzurufen. Token werden sicher im Dienst gespeichert und bei Bedarf im Botcode abgerufen.

Screenshot einer OAuth-Verbindungseinstellung im Azure-Portal.

Um eine Verbindungseinstellung zu erstellen, konfigurieren Sie die folgenden Einstellungen:

  • Name : Der Name der Verbindungseinstellung.
  • Dienstanbieter : Der Identitätsanbieter, der von der Verbindung zum Authentifizieren von Benutzern verwendet wird. Verbindungseinstellungen unterstützen mehrere Identitätsanbieter, einschließlich Microsoft Entra.
  • Client-ID : Die Client-ID aus einer Microsoft Entra-App-Registrierung, die mit den erforderlichen Berechtigungen für den Zugriff auf Benutzerdaten konfiguriert ist.
  • Geheimer Clientschlüssel : Der geheime Clientschlüssel aus einer Microsoft Entra-App-Registrierung, die mit den erforderlichen Berechtigungen für den Zugriff auf Benutzerdaten konfiguriert ist.
  • Tokenaustausch-URL : Die URL, die der Client beim Initiieren eines SSO-Flows in der App verwenden sollte.
  • Mandanten-ID : Die Mandanten-ID, in der sich die Microsoft Entra-App-Registrierung befindet.
  • Bereiche: Die Berechtigung, die Ihrem Bot für den Zugriff auf Benutzerdaten gewährt wird.

Der folgende Codeausschnitt zeigt, wie Sie eine OAuth-Verbindungseinstellung in einer Bicep-Datei konfigurieren:

resource botServiceProductsAPIConnection 'Microsoft.BotService/botServices/connections@2022-09-15' = {
    parent: botService
    name: 'Products API'
    location: 'global'
    properties: {
        serviceProviderDisplayName: 'Azure Active Directory v2'
        serviceProviderId: '30dd229c-58e3-4a48-bdfd-91ec48eb906c'
        clientId: productsApiEntraAppClientId
        clientSecret: productsApiEntraAppClientSecret
        scopes: 'api://${backendApiEntraAppClientId}/Product.Read'
        parameters: [
            {
                key: 'tenantID'
                value: 'common'
            }
            {
                key: 'tokenExchangeUrl'
                value: 'api://${botAppDomain}/botid-${botEntraAppClientId}'
            }
        ]
    }
}

Tipp

Es wird empfohlen, neue Microsoft Entra-App-Registrierungen für die Benutzer-zu-Dienst-Authentifizierung zu erstellen. Die mit dem Azure Bot-Dienst verwendete App-Registrierung sollte getrennt bleiben und für die Dienst-zu-Dienst-Authentifizierung zwischen dem Webdienst und dem Botdienst verwendet werden.

Die Microsoft Entra-App-Registrierung, die mit der Verbindungseinstellung verwendet wird, muss so konfiguriert werden, dass der Umleitungs-URI https://token.botframework.com/.auth/web/redirect verwendet wird, um erfolgreich ein Zugriffstoken vom Bot Framework-Tokendienst abzurufen. Der Umleitungs-URI wird verwendet, um das Zugriffstoken nach der Benutzerauthentifizierung an den Tokendienst zurückzugeben.

Da der Umleitungs-URI des Tokendiensts in einer externen Domäne gehostet wird, muss er in der App-Manifestdatei enthalten sein. Das validDomains-Array teilt dem Client mit, welche Domänen von der App verwendet werden sollen. Dadurch wird sichergestellt, dass der Client der Domäne vertrauen kann, wenn er einen SSO-Flow initiiert.

Der folgende Codeausschnitt zeigt, wie Die Domäne der App-Manifestdatei hinzugefügt wird:

"validDomains": [
    "token.botframework.com"
]

Benutzerabfragen authentifizieren

Zum Authentifizieren von Benutzerabfragen in einer Nachrichtenerweiterung verwenden Sie das Bot Framework SDK, um ein Zugriffstoken für den Benutzer vom Bot Framework Token Service abzurufen. Das Zugriffstoken kann dann für den Zugriff auf Daten von einem externen Dienst verwendet werden.

Zunächst überprüfen Sie, ob ein Token für den Benutzer im Tokendienst vorhanden ist.

Der folgende Codeausschnitt zeigt, wie Sie das UserTokenClient abrufen und die GetUserTokenAsync-Methode verwenden, um mithilfe einer benannten OAuth-Verbindungseinstellung ein Zugriffstoken für den Benutzer zurückzugeben:

var userTokenClient = turnContext.TurnState.Get<UserTokenClient>();

var tokenResponse = await userTokenClient.GetUserTokenAsync(userId, connectionName, channelId, magicCode, cancellationToken);

Wenn kein Token zurückgegeben wird, müssen Sie den Benutzer auffordern, sich anzumelden. Erstellen Sie eine Antwort, die einen Link auf der Benutzeroberfläche rendert, dem der Benutzer folgen kann, um den Anmeldeflow zu starten.

Der folgende Codeausschnitt zeigt, wie die GetSignInResourceAsync-Methode verwendet wird, um einen Anmeldelink vom Tokendienst zurückzugeben und in die Antwort der Nachrichtenerweiterung aufzunehmen:

var resource = await userTokenClient.GetSignInResourceAsync(connectionName, activity, null, cancellationToken);

return new MessagingExtensionResponse
{
    ComposeExtension = new MessagingExtensionResult
    {
        Type = "auth",
        SuggestedActions = new MessagingExtensionSuggestedAction
        {
            Actions = [
                new() {
                    Type = ActionTypes.OpenUrl,
                    Value = resource.SignInLink,
                    Title = "Sign In",
                },
            ],
        },
    },
};

Wenn der Benutzer dem Anmeldelink folgt, stimmt er den berechtigungen zu, die im Feld Bereiche für die OAuth-Verbindungseinstellung angefordert werden. Nachdem der Benutzer den Berechtigungen zugestimmt hat, ruft der Tokendienst ein Zugriffstoken ab und speichert es sicher im Dienst.

Wenn der Benutzer das nächste Mal eine Suche in der Nachrichtenerweiterung initiiert, wird im Tokendienst ein Zugriffstoken gefunden. Das zurückgegebene Zugriffstoken kann für den Zugriff auf Daten von einem externen Dienst verwendet werden.