Unterstützung für einmaliges Anmelden (SSO) für BotsSingle sign-on (SSO) support for bots

Authentifizierung mit einmaligem Anmelden in Azure Active Directory (Azure AD) minimiert, wie oft Benutzer ihre Anmeldeinformationen eingeben müssen, indem Sie das Authentifizierungstoken automatisch aktualisieren.Single sign-on authentication in Azure Active Directory (Azure AD) minimizes the number of times users need to enter their login credentials by silently refreshing the authentication token. Wenn Benutzer einwilligen, Ihre APP zu verwenden, müssen Sie nicht erneut auf einem anderen Gerät zustimmen und werden automatisch angemeldet.If users agrees to use your app, they will not have to consent again on another device and will be signed in automatically. Der Fluss ähnelt der SSO-Unterstützung der Teams-Registerkarte.The flow is very similar to the Teams tab SSO support. Der Unterschied ist das Protokoll dafür, wie ein bot Token anfordert und Antworten erhält.The difference is the protocol for how a bot requests tokens and receives responses.

OAuth 2.0 ist ein offener Standard für Authentifizierung und Autorisierung, der von Azure Active Directory (Azure AD) und vielen anderen Identitätsanbietern verwendet wird.OAuth 2.0 is an open standard for authentication and authorization used by Azure Active Directory (Azure AD) and many other identity providers. Ein grundlegendes Verständnis von OAuth 2,0 ist eine Voraussetzung für die Verwendung von Authentifizierung in Microsoft Teams.A basic understanding of OAuth 2.0 is a prerequisite for working with authentication in Teams.

Bot-SSO zur LaufzeitBot SSO at runtime

Bot-SSO im laufzeitdiagramm

  1. Der bot sendet eine Nachricht mit einem OAuthCard, das die tokenExchangeResource Eigenschaft enthält.The bot sends a message with an OAuthCard that contains the tokenExchangeResource property. Es weist Microsoft Teams an, ein Authentifizierungstoken für die bot-Anwendung zu erhalten.It tells Teams to obtain an authentication token for the bot application. Der Benutzer empfängt Nachrichten an allen aktiven Endpunkten des Benutzers.The user receives messages at all the active endpoints of the user.

Hinweis

  • Ein Benutzer kann gleichzeitig mehr als einen aktiven Endpunkt aufweisen.A user can have more than one active endpoint at a time.
  • Das bot-Token wird von jedem aktiven Endpunkt des Benutzers empfangen.The bot token is received from every active endpoint of the user.
  • Die Unterstützung für einmaliges Anmelden erfordert derzeit, dass die APP im persönlichen Bereich installiert wird.Single sign-on support currently requires the app to be installed in personal scope.
  1. Wenn der aktuelle Benutzer ihre bot-Anwendung zum ersten Mal verwendet hat, wird eine Anforderungs Aufforderung zur Zustimmung (sofern Zustimmung erforderlich ist) oder zur Behandlung der Step-up-Authentifizierung (beispielsweise zweistufige Authentifizierung) angezeigt.If it is the first time the current user has used your bot application, there will be a request prompt to consent (if consent is required) or to handle step-up authentication (such as two-factor authentication).

  2. Microsoft Teams fordert das bot-Anwendungs Token vom Azure AD-Endpunkt für den aktuellen Benutzer an.Microsoft Teams requests the bot application token from the Azure AD endpoint for the current user.

  3. Azure AD sendet das bot-Anwendungs Token an die Teams-Anwendung.Azure AD sends the bot application token to the Teams application.

  4. Microsoft Teams sendet das Token an den bot als Teil des Value-Objekts, das von der Invoke-Aktivität mit dem Namen Sign-in/tokenExchange zurückgegeben wird.Microsoft Teams sends the token to the bot as part of the value object returned by the invoke activity with the name sign-in/tokenExchange.

  5. Das Token wird in der bot-Anwendung analysiert, um die erforderlichen Informationen zu extrahieren, beispielsweise die e-Mail-Adresse des Benutzers.The token will be parsed in the bot application to extract the needed information, such as the user's email address.

Entwickeln eines Single Sign-on Microsoft Teams-botDevelop a Single sign-on Microsoft Teams bot

Die folgenden Schritte sind erforderlich, um einen SSO-Microsoft Teams-bot zu entwickeln:The following steps: are required to develop an SSO Microsoft Teams bot:

  1. Erstellen eines freien Azure-KontosCreate an Azure free account
  2. Aktualisieren des Teams-App-ManifestsUpdate your Teams app manifest
  3. Hinzufügen des Codes zum Anfordern und empfangen des bot-TokensAdd the code to request and receive the bot token

Erstellen eines Azure-KontosCreate an Azure account

Dieser Schritt ähnelt dem Registerkarten-SSO-Fluss:This step is similar to the tab SSO flow:

  1. Rufen Sie Ihre Azure AD-Anwendungs-ID für Microsoft Teams-Desktop,-Webdienste oder Mobile Clients ab.Get your Azure AD Application ID for Teams desktop, web, or mobile client.
  2. Geben Sie die Berechtigungen an, die Ihre Anwendung für den Azure AD-Endpunkt und optional für Microsoft Graph benötigt.Specify the permissions that your application needs for the Azure AD endpoint and, optionally, Microsoft Graph.
  3. Erteilen von Berechtigungen für Desktop-, Webanwendungen und Mobile Microsoft Teams-AnwendungenGrant permissions for Teams desktop, web, and mobile applications.
  4. Fügen Sie eine Client-App hinzu, indem Sie die Schaltfläche Bereich hinzufügen auswählen und im geöffneten Bereich access_as_user als Bereichsnamen eingeben.Add a client app by selecting the Add a scope button and in the panel that opens, enter access_as_user as the Scope name.

Hinweis

Der Bereich "access_as_user", der zum Hinzufügen einer Client-App verwendet wird, ist für "Administratoren und Benutzer".The "access_as_user" scope used to add a client app is for "Administrators and users".

Wichtig

  • Wenn Sie einen eigenständigen bot erstellen, legen Sie den Anwendungs-ID-URI auf api://botid-{YourBotId} hier fest, YourBotId verweist auf Ihre Azure AD Anwendungs-ID.If you are building a standalone bot, set the Application ID URI to api://botid-{YourBotId} Here, YourBotId refers to your Azure AD application ID.
  • Wenn Sie eine APP mit einem bot und einer RegisterkarteErstellen, legen Sie den Anwendungs-ID-URI auf fest api://fully-qualified-domain-name.com/botid-{YourBotId} .If you are building an app with a bot and a tab, set the Application ID URI to api://fully-qualified-domain-name.com/botid-{YourBotId}.

Aktualisieren des App-ManifestsUpdate your app manifest

Fügen Sie Ihrem Microsoft Teams-Manifest neue Eigenschaften hinzu:Add new properties to your Microsoft Teams manifest:

WebApplicationInfo -das übergeordnete Element der folgenden Elemente:WebApplicationInfo - The parent of the following elements:

  • ID – die Client-ID der Anwendung.id - The client ID of the application. Dies ist die Anwendungs-ID, die Sie im Rahmen der Registrierung der Anwendung mit Azure AD erhalten haben.This is the application ID that you obtained as part of registering the application with Azure AD.
  • Resource – die Domäne und Unterdomäne Ihrer Anwendung.resource - The domain and subdomain of your application. Hierbei handelt es sich um denselben URI (einschließlich des api:// Protokolls), den Sie bei der Erstellung Ihres scope in Schritt 6 oben registriert haben.This is the same URI (including the api:// protocol) that you registered when creating your scope in step 6 above. Sie sollten den access_as_user Pfad nicht in Ihre Ressource einschließen.You shouldn't include the access_as_user path in your resource. Der Domänenteil dieses URIs sollte der Domäne entsprechen, einschließlich aller Unterdomänen, die in den URLs Ihres Teams-Anwendungsmanifests verwendet werden.The domain part of this URI should match the domain, including any subdomains, used in the URLs of your Teams application manifest.
"webApplicationInfo": {
  "id": "00000000-0000-0000-0000-000000000000",
  "resource": "api://subdomain.example.com/00000000-0000-0000-0000-000000000000"
}

Anfordern eines bot-TokensRequest a bot token

Die Anforderung zum Abrufen des Tokens ist eine normale Post-Nachrichtenanforderung (unter Verwendung des vorhandenen Nachrichtenschemas).The request to get the token is a normal POST message request (using the existing message schema). Sie ist in den Anlagen eines OAuthCard enthalten.It is included in the attachments of an OAuthCard. Das Schema für die OAuthCard-Klasse ist im Microsoft-bot-Schema 4,0 definiert und ähnelt einer Anmeldekarte.The schema for the OAuthCard class is defined in Microsoft Bot Schema 4.0 and it is very similar to a sign-in card. Diese Anforderung wird von Microsoft Teams als automatische Token-Übernahme behandelt, wenn die TokenExchangeResource Eigenschaft auf der Karte aufgefüllt ist.Teams will treat this request as a silent token acquisition if the TokenExchangeResource property is populated on the card. Für den Teams-Kanal honorieren wir nur die Id Eigenschaft, die eine Token-Anforderung eindeutig identifiziert.For the Teams channel we honor only the Id property, which uniquely identifies a token request.

Hinweis

Das bot OAuthPrompt -Framework oder das MultiProviderAuthDialog wird für die SSO-Authentifizierung (Single Sign-on, einmaliges Anmelden) unterstützt.The Bot Framework OAuthPrompt or the MultiProviderAuthDialog is supported for single sign-on (SSO) authentication.

Wenn der Benutzer Ihre Anwendung zum ersten Mal verwendet und die Zustimmung des Benutzers erforderlich ist, wird dem Benutzer ein Dialogfeld angezeigt, in dem die Zustimmungs Erfahrung ähnlich wie unten fortgesetzt werden kann.If this is the first time the user is using your application and the user consent is required, the user will be shown a dialog to continue with the consent experience similar to the one below. Wenn der Benutzer Continue auswählt, treten zwei verschiedene Dinge auf, je nachdem, ob der bot definiert ist oder nicht, und eine Anmeldeschaltfläche auf dem OAuthCard.When the user selects Continue, two different things occur depending on whether the bot is defined or not and a sign-in button on the OAuthCard.

Dialogfeld Zustimmung

Wenn der bot eine Anmeldeschaltfläche definiert, wird der Anmelde Fluss für Bots ähnlich dem Anmelde Fluss von einer kartenschaltfläche in einem Nachrichtendatenstrom ausgelöst.If the bot defines a sign-in button, the sign-in flow for bots will be triggered similarly to the sign-in flow from a card button in a message stream. Es liegt an dem Entwickler, zu entscheiden, welche Berechtigungen für den Benutzer erteilt werden sollen, um ihn zu genehmigen.It is up to the developer to decide which permissions to ask for the user to consent. Dieser Ansatz wird empfohlen, wenn Sie ein Token mit Berechtigungen darüber hinaus benötigen openId , beispielsweise wenn Sie das Token für Graph-Ressourcen austauschen möchten.This approach is recommended if you need a token with permissions beyond openId, for example, if you want to exchange the token for graph resources.

Wenn der bot keine Anmeldeschaltfläche auf der Karte bereitstellt, wird die Benutzer Zustimmung für einen minimalen Satz von Berechtigungen ausgelöst.If the bot is not providing a sign-in button on the card, it triggers user consent for a minimal set of permissions. Dieses Token eignet sich für die Standardauthentifizierung und das erhalten der e-Mail-Adresse des Benutzers.This token is useful for basic authentication and getting the user email address.

C#-Token-Anforderung ohne Anmeldeschaltfläche:C# token request without a sign-in button:

var attachment = new Attachment
            {
                Content = new OAuthCard
                {
                    TokenExchangeResource = new TokenExchangeResource
                    {
                        Id = requestId
                    }
                },
                ContentType = OAuthCard.ContentType,
            };
            var activity = MessageFactory.Attachment(attachment);

            // NOTE: This activity needs to be sent in the 1:1 conversation between the bot and the user. 
            // If the bot supports group and channel scope, this code should be updated to send the request to the 1:1 chat. 

   await turnContext.SendActivityAsync(activity, cancellationToken);

Empfangen des TokensReceiving the token

Die Antwort mit dem Token wird über eine Invoke-Aktivität mit dem gleichen Schema gesendet wie andere Aktivitäten aufrufen, die die Bots heute empfangen.The response with the token is sent through an invoke activity with the same schema as others invoke activities the bots receive today. Der einzige Unterschied besteht darin, dass der Aufruf Name, die Anmelde-tokenExchange und das Wertfeld die ID (eine Zeichenfolge) der anfänglichen Anforderung zum Abrufen des Tokens und des Token -Felds (ein Zeichenfolgenwert einschließlich des Tokens) enthalten wird.The only difference is the invoke name, sign-in/tokenExchange and the value field which will contain the Id (a string) of the initial request to get the token and the token field (a string value including the token). Beachten Sie, dass Sie möglicherweise mehrere Antworten für eine bestimmte Anforderung erhalten, wenn der Benutzer über mehrere aktive Endpunkte verfügt.Please note that you might receive multiple responses for a given request if the user has multiple active endpoints. Es liegt an Ihnen, die Antworten mit dem Token zu deduplizieren.It is up to you to deduplicate the responses with the token.

C#-Code zur Reaktion auf die Behandlung der Invoke-Aktivität:C# code to respond to handle the invoke activity:

protected override async Task<InvokeResponse> OnInvokeActivityAsync
  (ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
        {
            try
            {
                if (turnContext.Activity.Name == SignInConstants.TokenExchangeOperationName && turnContext.Activity.ChannelId == Channels.Msteams)
                {
                    await OnTokenResponseEventAsync(turnContext, cancellationToken);
                    return new InvokeResponse() { Status = 200 };
                }
                else
                {
                    return await base.OnInvokeActivityAsync(turnContext, cancellationToken);
                }
            }
            catch (InvokeResponseException e)
            {
                return e.CreateInvokeResponse();
            }
        }

Die turnContext.activity.value ist vom Typ TokenExchangeInvokeRequest und enthält das Token, das von Ihrem bot weiter verwendet werden kann.The turnContext.activity.value is of type TokenExchangeInvokeRequest and contains the token that can be further used by your bot. Speichern Sie die Token aus Leistungsgründen sicher, und aktualisieren Sie Sie.Store the tokens securely for performance reasons and refresh them.

Aktualisieren des Azure-Portals mit der OAuth-VerbindungUpdate the Azure portal with the OAuth connection

  1. Navigieren Sie im Azure-Portal zurück zur Registrierung für bot-Kanäle.In the Azure Portal, navigate back to the Bot Channels Registration.

  2. Wechseln Sie zum Blade " Einstellungen ", und wählen Sie im Abschnitt OAuth-Verbindungseinstellungen die Option Hinzufügen .Switch to the Settings blade and choose Add Setting under the OAuth Connection Settings section.

SSOBotHandle2-Ansicht

  1. Schließen Sie das Formular für die Verbindungseinstellung ab:Complete the Connection Setting form:
  • Geben Sie einen Namen für die neue Verbindungseinstellung ein.Enter a name for your new Connection Setting. Dies ist der Name, auf den innerhalb der Einstellungen Ihres bot-Dienstcodes in Schritt 5 verwiesen wird.This will be the name that gets referenced inside the settings of your bot service code in step 5.
  • Wählen Sie in der Dropdownliste Dienstanbieter die Option Azure Active Directory v2 aus.In the Service Provider dropdown, select Azure Active Directory V2.
  • Geben Sie die Clientanmeldeinformationen für die Aad-Anwendung ein.Enter the client credentials for the AAD application.

Hinweis

Implizite Zuwendungen sind in der Aad-Anwendung möglicherweise erforderlich.Implicit grant may be required in the AAD application.

  • Verwenden Sie für die Token-Exchange-URL den Bereichswert, der im vorherigen Schritt ihrer Aad-Anwendung definiert wurde.For the Token Exchange URL, use the scope value defined in the previous step of your AAD application. Das vorhanden sein der Token-Exchange-URL zeigt dem SDK an, dass diese Aad-Anwendung für SSO konfiguriert ist.The presence of the Token Exchange URL is indicating to the SDK that this AAD application is configured for SSO.
  • Geben Sie "Common" als Mandanten-ID an.Specify "common" as the Tenant ID.
  • Fügen Sie alle Bereiche hinzu, die beim Angeben von Berechtigungen für Downstream-APIs für Ihre Aad-Anwendung konfiguriert wurden.Add all the scopes configured when specifying permissions to downstream APIs for your AAD application. Wenn die Client-ID und der geheime Client Schlüssel bereitgestellt werden, tauschen Tokenspeicher das Token für ein Diagramm Token mit definierten Berechtigungen für Sie aus.With the client id and client secret provided, token store will exchange the token for a graph token with defined permissions for you.
  • Klicken Sie auf Speichern.Select Save.

VuSSOBotConnection-Einstellungsansicht

Aktualisieren des Authentifizierungs BeispielsUpdate the auth sample

Beginnen Sie mit dem Microsoft Teams-Authentifizierungs Beispiel.Start with the teams auth sample.

  1. Aktualisieren Sie die TeamsBot, um Folgendes einzuschließen.Update the TeamsBot to include the following. Informationen zum Verarbeiten des deduping der eingehenden Anforderung finden Sie weiter unten:To handle the deduping of the incoming request, see below:
 protected override async Task OnSignInInvokeAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
        {
            await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
        }
    protected override async Task OnTokenResponseEventAsync(ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
        {
            await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
        }
  1. Aktualisieren Sie das, appsettings.json um das botId obige, Kennwort und den oben definierten Verbindungsnamen einzubeziehen.Update the appsettings.json to include the botId, password, and the connection name defined above.
  2. Aktualisieren Sie das Manifest, und stellen Sie sicher, dass token.botframework.com es sich im Abschnitt gültige Domänen befindet.Update the manifest and ensure that token.botframework.com is in the valid domains section.
  3. Komprimieren Sie das Manifest mit den Profilbildern, und installieren Sie es in Microsoft Teams.Zip the manifest with the profile images and install it in Teams.

Zusätzliche CodebeispieleAdditional code samples