Utilisation du service Microsoft Azure bot pour l’authentification dans teamsUsing Azure Bot Service for Authentication in Teams

Important

Les Articles de cette section sont basés sur le kit de développement logiciel (SDK) de l’infrastructure de robots v3.The articles in this section are based on the v3 Bot Framework SDK. Si vous recherchez de la documentation actuelle (version 4,6 ou ultérieure du kit de développement logiciel (SDK)), reportez-vous à la section robots de conversation .If you're looking for current documentation (version 4.6 or later of the SDK) see the Conversational Bots section.

Sans le OAuthCard du service Azure bot, il est compliqué d’implémenter l’authentification dans un bot.Without the Azure Bot Service’s OAuthCard it is complicated to implement authentication in a bot. Il s’agit d’un défi de pile complète qui implique la création d’une expérience Web, l’intégration avec des fournisseurs OAuth externes, la gestion des jetons et la gestion des appels d’API de serveur à serveur adéquats pour effectuer un flux d’authentification sécurisé.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. Cela peut entraîner des expériences dépendantes qui nécessitent l’entrée de « nombres magiques ».This can result in clunky experiences requiring the entry of “magic numbers”.

Avec le OAuthCard du service Azure bot, il est plus facile pour votre robot de se connecter à vos utilisateurs et d’accéder aux fournisseurs de données externes.With Azure Bot Service’s OAuthCard, it is easier for your Teams bot to sign in your users and access external data providers. Que vous ayez déjà implémenté l’authentification et que vous souhaitiez passer à un autre résultat plus simple ou si vous souhaitez ajouter une authentification à votre service bot pour la première fois, le OAuthCard peut faciliter la tâche.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.

Les autres rubriques de l’authentification décrivent l’authentification sans utiliser l’OAuthCard, donc si vous voulez comprendre l’authentification dans teams plus profondément ou si vous ne pouvez pas utiliser le OAuthCard, vous pouvez toujours consulter ces rubriques.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.

Prise en charge du OAuthCardSupport for the OAuthCard

Il existe actuellement des restrictions quant à l’emplacement où vous pouvez utiliser le OAuthCard.There are currently some restrictions to where you can use the OAuthCard. Cela inclut ce qui suit :These include:

Comment le service Azure bot m’aide-t-il à m’authentifier ?How does the Azure Bot Service help me do authentication?

Une documentation complète à l’aide de l’OAuthCard est disponible dans la rubrique : Add Authentication to your bot by Azure bot service.Full documentation using the OAuthCard is available in the topic: Add authentication to your bot via Azure Bot Service. Notez que cette rubrique se trouve dans l’ensemble de la documentation de l’infrastructure Azure bot et n’est pas propre à Teams.Note that this topic is in the Azure Bot Framework documentation set, and is not specific to Teams.

Les sections suivantes indiquent comment utiliser le OAuthCard dans Teams.The following sections tell how to use the OAuthCard in Teams.

Principaux avantages pour les développeurs de teamsMain benefits for Teams developers

L’OAuthCard aide à l’authentification des manières suivantes :The OAuthCard helps with authentication in the following ways:

  • Fournit un flux d’authentification Web out-of-Box : vous n’avez plus à écrire et à héberger une page Web pour diriger vers des expériences de connexion externes ou fournir une redirection.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.
  • Est transparent pour les utilisateurs finals : effectuez l’expérience de connexion complète directement dans Teams.Is seamless for end users: complete the full sign in experience right within Teams.
  • Inclut une gestion des jetons simplifiée : vous n’avez plus besoin d’implémenter un système de stockage des jetons : le service bot prend en charge la mise en cache des jetons et fournit un mécanisme sécurisé pour l’extraction de ces jetons.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.
  • Est pris en charge par les kits de développement logiciel complets : facile à intégrer et à consommer à partir de votre service bot.Is supported by complete SDKs: easy to integrate and consume from your bot service.
  • Dispose de la prise en charge de nombreux fournisseurs OAuth populaires, comme Azure AD/MSA, Facebook et Google.Has out-of-box support for many popular OAuth providers, such as Azure AD/MSA, Facebook, and Google.

Quand dois-je implémenter ma propre solution ?When should I implement my own solution?

Étant donné que les jetons d’accès sont des informations sensibles, il est possible que vous ne souhaitiez pas les stocker dans un service externe.Because access tokens are sensitive information, you may not wish to have them stored in an external service. Dans ce cas, vous pouvez toujours implémenter votre propre système de gestion des jetons et l’expérience de connexion dans Teams, comme décrit dans les autres rubriques relatives à l' authentification Teams.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.

Prise en main de OAuthCard dans teamsGetting started with OAuthCard in Teams

Notes

Ce guide utilise le kit de développement logiciel (SDK) de robot v3.This guide is using the Bot Framework v3 SDK. Vous pouvez trouver l’implémentation v4 ici.You can find the v4 implementation here. Vous devrez tout de même créer un manifeste et inclure token.botframework.com dans la validDomains section, car dans le cas contraire, le bouton de connexion n’ouvrira pas la fenêtre d’authentification.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. Utilisez l' application Studio pour générer votre manifeste.Use the App Studio to generate your manifest.

Vous devez tout d’abord configurer votre service Azure bot pour configurer des fournisseurs d’authentification externes.You’ll first need to configure your Azure bot service to set up external authentication providers. Pour plus d’informations, consultez la procédure de Configuration des fournisseurs d’identité .Read Configuring identity providers for detailed steps.

Pour activer l’authentification à l’aide du service Azure bot, vous devez effectuer ces ajouts à votre code :To enable authentication using the Azure Bot Service, you need to make these additions to your code:

  1. Incluez token.botframework.com dans validDomains la section du manifeste de votre application car teams intégrera la page de connexion du service bot.Include token.botframework.com in the validDomains section of your app manifest because Teams will embed the Bot Service’s login page.
  2. Récupérez le jeton du service bot chaque fois que votre bot a besoin d’accéder à des ressources authentifiées.Fetch the token from the Bot Service whenever your bot needs to access authenticated resources. Si aucun jeton n’est disponible, envoyez un message avec un OAuthCard à l’utilisateur pour lui demander de se connecter au service externe.If no token is available, send a message with an OAuthCard to the user requesting them to log into the external service.
  3. Gérer l’activité de fin de connexion.Handle the login completion activity. Cela garantit que la demande d’authentification et le jeton sont associés à l’utilisateur qui interagit actuellement avec votre bot.This ensures that the authentication request and the token are associated with the user currently interacting with your bot.
  4. Récupérez le jeton chaque fois que votre bot doit effectuer des actions authentifiées, telles que l’appel d’API REST externes.Retrieve the token whenever your bot needs to perform authenticated actions, such as calling external REST APIs.

Dans votre code de boîte de dialogue, vous devez ajouter cet extrait de code (C#), qui recherche un jeton d’accès existant :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);
}

S’il n’existe pas de jeton d’accès, votre code enverra un message avec un OAuthCard à l’utilisateur :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);
}

Pour gérer l’activité de connexion terminée, vous devez traiter cet appel :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);
}

Dans votre code de boîte de dialogue, vous pouvez ensuite récupérer le jeton à partir du service d’authentification du robot :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;
}

Utilisation de OAuthCard avec les extensions de messagerieUsing OAuthCard with messaging extensions

Vous pouvez également utiliser le service de robot Azure pour connecter des fournisseurs tiers à votre extension de messagerie.You can also use Azure Bot Service to connect third-party providers to your messaging extension. Le flux est le même qu’avec un bot, sauf au lieu de renvoyer un OAuthCard, votre service renverra une invite de connexion.The flow is the same as with a bot, except instead of returning an OAuthCard, your service will return a login prompt.

L’extrait de code suivant (C#) illustre comment concevoir la réponse de connexion :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;
}

Notez que dans l’exemple ci-dessus, vous devez passer l' GetSignInLinkAsync appel directement par client.OAuthApi rapport à la propriété.Note that in the example above you need to make the call to GetSignInLinkAsync directly against the client.OAuthApi property.

Lorsque l’utilisateur réussit la séquence de connexion, votre service reçoit une autre demande d’appel contenant la requête de l’utilisateur d’origine, ainsi qu’une chaîne de paramètres d’état contenant le « code magique ».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”. Vous pouvez maintenant extraire le jeton à l’aide de cette chaîne, ainsi que l’ID d’utilisateur et le nom de connexion.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.

}