Verwenden des Azure bot-Diensts für die Authentifizierung in Microsoft TeamsUsing Azure Bot Service for Authentication in Teams

Wichtig

Die Artikel in diesem Abschnitt basieren auf dem V3 bot Framework SDK.The articles in this section are based on the v3 Bot Framework SDK. Wenn Sie nach der aktuellen Dokumentation (Version 4,6 oder höher des SDK) suchen, lesen Sie den Abschnitt conversational Bots .If you're looking for current documentation (version 4.6 or later of the SDK) see the Conversational Bots section.

Ohne den OAuthCard des Azure bot-Diensts ist es kompliziert, die Authentifizierung in einem bot zu implementieren.Without the Azure Bot Service’s OAuthCard it is complicated to implement authentication in a bot. Es handelt sich um eine Full-Stack-Herausforderung, die das Erstellen einer Weberfahrung, die Integration mit externen OAuth-Anbietern, die Tokenverwaltung und das Behandeln der richtigen Server-zu-Server-API-Aufrufe zum Sicherstellen des vollständigen Authentifizierungs Flusses umfasst.It is a full-stack challenge that involving building a web experience, integrating with external OAuth providers, token management, and handling the right server-to-server API calls to complete authentication flow securely. Dies kann zu klobigen Erfahrungen führen, die die Eingabe von "Magic Numbers" erfordern.This can result in clunky experiences requiring the entry of “magic numbers”.

Mit dem OAuthCard des Azure bot-Diensts ist es für Ihre Teams einfacher, sich bei ihren Benutzern anzumelden und auf externe Datenanbieter zuzugreifen.With Azure Bot Service’s OAuthCard, it is easier for your Teams bot to sign in your users and access external data providers. Unabhängig davon, ob Sie die Authentifizierung bereits implementiert haben und auf eine einfachere Funktion umstellen möchten, oder wenn Sie das erste Mal die Authentifizierung zu Ihrem bot-Dienst hinzufügen möchten, können Sie das OAuthCard vereinfachen.Whether you’ve already implemented auth and you want to switch over to something simpler, or if you are looking to add authentication to your bot service for the first time, the OAuthCard can make it easier.

In anderen Themen in der Authentifizierung wird die Authentifizierung ohne Verwendung des OAuthCard beschrieben, wenn Sie also die Authentifizierung in Microsoft Teams genauer verstehen möchten oder eine Situation haben, in der Sie die OAuthCard nicht verwenden können, können Sie sich trotzdem auf diese Themen berufen.Other topics in Authentication describe authentication without using the OAuthCard, so if you want to understand authentication in Teams more deeply, or have a situation where you can not use the OAuthCard, you can still refer to those topics.

Unterstützung für die OAuthCardSupport for the OAuthCard

Es gibt derzeit einige Einschränkungen, wo Sie die OAuthCard verwenden können.There are currently some restrictions to where you can use the OAuthCard. Zu diesen zählen:These include:

Wie hilft mir der Azure bot-Dienst bei der Authentifizierung?How does the Azure Bot Service help me do authentication?

Eine vollständige Dokumentation mit OAuthCard steht im Thema: Add Authentication to your bot via Azure bot Servicezur Verfügung.Full documentation using the OAuthCard is available in the topic: Add authentication to your bot via Azure Bot Service. Beachten Sie, dass dieses Thema in der Azure bot Framework-Dokumentationsgruppe liegt und nicht für Teams spezifisch ist.Note that this topic is in the Azure Bot Framework documentation set, and is not specific to Teams.

In den folgenden Abschnitten erfahren Sie, wie Sie das OAuthCard in Microsoft Teams verwenden.The following sections tell how to use the OAuthCard in Teams.

Hauptvorteile für Entwickler von TeamsMain benefits for Teams developers

Das OAuthCard hilft bei der Authentifizierung auf folgende Weise:The OAuthCard helps with authentication in the following ways:

  • Stellt einen Out-of-Box-webbasierten Authentifizierungs Fluss bereit: Sie müssen keine Webseite mehr schreiben und hosten, um an externe Anmeldeinformationen zu verweisen oder eine Umleitung bereitzustellen.Provides an out-of-box web-based authentication flow: you no longer have to write and host a web page to direct to external login experiences or provide a redirect.
  • Ist nahtlos für Endbenutzer: führen Sie das vollständige anmeldeerlebnis direkt in Microsoft Teams aus.Is seamless for end users: complete the full sign in experience right within Teams.
  • Enthält einfache Tokenverwaltung: Sie müssen kein Tokenspeicher mehr implementieren – stattdessen übernimmt der bot-Dienst die Token-Zwischenspeicherung und stellt einen sicheren Mechanismus zum Abrufen dieser Token bereit.Includes easy token management: you no longer have to implement a token storage system – instead, the Bot Service takes care of token caching and provides a secure mechanism for fetching those tokens.
  • Wird von Complete SDKs unterstützt: einfach zu integrieren und von Ihrem bot-Dienst zu nutzen.Is supported by complete SDKs: easy to integrate and consume from your bot service.
  • Verfügt über eine Out-of-Box-Unterstützung für viele beliebte OAuth-Anbieter wie Azure AD/MSA, Facebook und Google.Has out-of-box support for many popular OAuth providers, such as Azure AD/MSA, Facebook, and Google.

Wann sollte ich eine eigene Lösung implementieren?When should I implement my own solution?

Da es sich bei Zugriffstoken um vertrauliche Informationen handelt, möchten Sie möglicherweise nicht, dass Sie in einem externen Dienst gespeichert werden.Because access tokens are sensitive information, you may not wish to have them stored in an external service. In diesem Fall können Sie sich entscheiden, weiterhin Ihr eigenes Token-Verwaltungssystem und ihre Anmelde Erfahrung in Microsoft Teams zu implementieren, wie in den restlichen Teams- Authentifizierungs Themen beschrieben.In this case, you may choose to still implement your own token management system and login experience within Teams, as described in the rest of the Teams Authentication topics.

Erste Schritte mit OAuthCard in Microsoft TeamsGetting started with OAuthCard in Teams

Hinweis

In diesem Leitfaden wird das bot Framework V3 SDK verwendet.This guide is using the Bot Framework v3 SDK. Sie können die V4-Implementierung hierfinden.You can find the v4 implementation here. Sie müssen dennoch ein Manifest erstellen und Token.botframework.com in den validDomains Abschnitt einbeziehen, da andernfalls die Schaltfläche Anmelden das Authentifizierungsfenster nicht öffnet.You will still need to create a manifest and include token.botframework.com in the validDomains section, because otherwise the Sign in button will not open the authentication window. Verwenden Sie das App Studio , um Ihr Manifest zu generieren.Use the App Studio to generate your manifest.

Zunächst müssen Sie Ihren Azure bot-Dienst konfigurieren, um externe Authentifizierungsanbieter einzurichten.You’ll first need to configure your Azure bot service to set up external authentication providers. Lesen Sie Konfigurieren von Identitätsanbietern für detaillierte Schritte.Read Configuring identity providers for detailed steps.

Um die Authentifizierung mit dem Azure bot-Dienst zu aktivieren, müssen Sie diese Ergänzungen an Ihrem Code vornehmen:To enable authentication using the Azure Bot Service, you need to make these additions to your code:

  1. Schließen Sie Token.botframework.com in validDomains den Abschnitt des App-Manifests ein, da Microsoft Teams die Anmeldeseite des bot-Diensts einbetten wird.Include token.botframework.com in the validDomains section of your app manifest because Teams will embed the Bot Service’s login page.
  2. Holen Sie das Token aus dem bot-Dienst, wenn Ihr bot Zugriff auf authentifizierte Ressourcen benötigt.Fetch the token from the Bot Service whenever your bot needs to access authenticated resources. Wenn kein Token verfügbar ist, senden Sie eine Nachricht mit einem OAuthCard an den Benutzer, der Sie anfordert, sich beim externen Dienst anzumelden.If no token is available, send a message with an OAuthCard to the user requesting them to log into the external service.
  3. Behandeln Sie die Anmelde Abschlussaktivität.Handle the login completion activity. Dadurch wird sichergestellt, dass die Authentifizierungsanforderung und das Token dem Benutzer zugeordnet sind, der derzeit mit Ihrem bot interagiert.This ensures that the authentication request and the token are associated with the user currently interacting with your bot.
  4. Rufen Sie das Token ab, wenn Ihr bot authentifizierte Aktionen durchführen muss, beispielsweise das Aufrufen externer Rest-APIs.Retrieve the token whenever your bot needs to perform authenticated actions, such as calling external REST APIs.

In Ihrem Dialogfeldcode müssen Sie diesen Codeausschnitt (C#) hinzufügen, der nach einem vorhandenen Zugriffstoken sucht:In your dialog code, you’ll need to add this snippet (C#), which checks for an existing access token:

// First ask Bot Service if it already has a token for this user
var token = await context.GetUserTokenAsync(ConnectionName).ConfigureAwait(false);
if (token != null)
{
    // use the token to do exciting things!
}
else
{
    // If Bot Service does not have a token, send an OAuth card to sign in 
    await SendOAuthCardAsync(context, (Activity)context.Activity);
}

Wenn kein Zugriffstoken vorhanden ist, sendet Ihr Code dann eine Nachricht mit einem OAuthCard an den Benutzer:If an access token doesn’t exist, your code will then send a message with an OAuthCard to the user:

private async Task SendOAuthCardAsync(IDialogContext context, Activity activity)
{
    await context.PostAsync($"To do this, you'll first need to sign in.");

    var reply = await context.Activity.CreateOAuthReplyAsync(_connectionName, _signInMessage, _buttonLabel).ConfigureAwait(false);
    await context.PostAsync(reply);

    context.Wait(WaitForToken);
}

Um die vollständige Anmeldungs Aktivität zu verarbeiten, müssen Sie diesen Aufruf verarbeiten:To handle the login complete activity, you’ll need to process this Invoke:

if (activity.Name == "signin/verifyState")
{
  // We do this so that we can pass handling to the right logic in the dialog. You can
  // set this to be whatever string you want.
  activity.Text = "loginComplete";
  await Conversation.SendAsync(activity, () => new Dialogs.RootDialog());

  return Request.CreateResponse(HttpStatusCode.OK);
}

Im Dialogfeldcode können Sie das Token dann aus dem bot-Authentifizierungsdienst abrufen:In your dialog code, you can then retrieve the token from the Bot authentication service:

if (text.Contains("loginComplete"))
  {
    // Handle login completion event.
    JObject ctx = activity.Value as JObject;

    if (ctx != null)
    {
      string code = ctx["state"].ToString();

      var oauthClient = activity.GetOAuthClient();
      var token = await oauthClient.OAuthApi.GetUserTokenAsync(activity.From.Id, ConnectionName, magicCode: code).ConfigureAwait(false);
      if (token != null)
      {
        // Make whatever API calls here you want
        await context.PostAsync($"Success! You are now signed in.");
      }
    }
  // Need to respond to the Invoke.
  return;
}

Verwenden von OAuthCard mit Messaging ErweiterungenUsing OAuthCard with messaging extensions

Sie können auch den Azure bot-Dienst verwenden, um Drittanbieter mit Ihrer Messaging Erweiterung zu verbinden.You can also use Azure Bot Service to connect third-party providers to your messaging extension. Der Fluss ist identisch mit einem bot, es sei denn, es wird ein OAuthCard zurückgegeben, Ihr Dienst gibt eine Anmeldeaufforderung zurück.The flow is the same as with a bot, except instead of returning an OAuthCard, your service will return a login prompt.

Der folgende Codeausschnitt (C#) veranschaulicht, wie die Anmelde Antwort erstellt wird:The following snippet (C#) illustrates how to craft the login response:

var token = await client.OAuthApi.GetUserTokenAsync(activity.From.Id, ConnectionName).ConfigureAwait(false);

if (token == null)
{
  // Send the login response with the auth link.
  string link = await client.OAuthApi.GetSignInLinkAsync(activity, ConnectionName);

  response = new ComposeExtensionResponse()
  {
    ComposeExtension = new ComposeExtensionResult()
  };
  response.ComposeExtension.Type = "auth";
  response.ComposeExtension.SuggestedActions = new ComposeExtensionSuggestedAction()
  {
    Actions = new List<CardAction>()
      {
        new CardAction(ActionTypes.OpenUrl, title: "Sign into this app", value: link)
      }
    };
  return response;
}

Beachten Sie, dass Sie im obigen Beispiel den Aufruf direkt für GetSignInLinkAsync die client.OAuthApi Eigenschaft vornehmen müssen.Note that in the example above you need to make the call to GetSignInLinkAsync directly against the client.OAuthApi property.

Wenn der Benutzer die Anmeldesequenz erfolgreich abgeschlossen hat, erhält der Dienst eine weitere Invoke-Anforderung, die die ursprüngliche Benutzerabfrage enthält, zusammen mit einer Statusparameter Zeichenfolge, die den "Magic Code" enthält.When the user successfully completes the login sequence, your service will receive another Invoke request containing the original user query, along with a state parameter string containing the “magic code”. Sie können nun das Token mit dieser Zeichenfolge zusammen mit der Benutzer-ID und dem Verbindungsnamen abrufen.You can now fetch the token using this string, along with the user ID and connection name.

var query = activity.GetComposeExtensionQueryData();
JObject data = activity.Value as JObject;

var client = activity.GetOAuthClient();

// Check if the request comes with login state
if (data != null && data["state"] != null)
{
  var token = await client.OAuthApi.GetUserTokenAsync(activity.From.Id, ConnectionName, data["state"].ToString());

  // Do stuff with the token here.

}