Prise en charge de l' sign-on unique (SSO) pour les bots

L’authentification unique dans Azure Active Directory (AAD) réduit le nombre de fois que les utilisateurs doivent entrer leurs informations d’identification de connexion en actualisation silencieuse du jeton d’authentification. Si les utilisateurs acceptent d’utiliser votre application, ils n’ont plus besoin d’accord pour un autre appareil et peuvent se connecter automatiquement. Le flux est similaire à celui de la prise en charge de l’oD SSOde l’onglet Microsoft Teams, toutefois, la différence est dans le protocole pour la façon dont un bot demande des jetons et reçoit des réponses.

Notes

OAuth 2.0 est une norme ouverte d’authentification et d’autorisation utilisée par AAD et de nombreux autres fournisseurs d’identité. Une compréhension de base d’OAuth 2.0 est une condition préalable à l’utilisation de l’authentification dans Teams.

SO du bot lors de l’runtime

Bot SSO lors de l’runtime diagram

Pour obtenir l’authentification et les jetons d’application bot, complétez les étapes suivantes :

  1. Le robot envoie un message avec une carte OAuth qui contient la propriété tokenExchangeResource. Il indique Teams obtenir un jeton d’authentification pour l’application bot. L’utilisateur reçoit des messages sur tous les points de terminaison d’utilisateur actifs.

    Notes

    • Un utilisateur peut avoir plusieurs points de terminaison actifs à la fois.
    • Le jeton bot est reçu de chaque point de terminaison d’utilisateur actif.
    • L’application doit être installée dans l’étendue personnelle pour la prise en charge de l’authentification unique.
  2. Si l’utilisateur actuel utilise votre application bot pour la première fois, une invite de demande s’affiche pour demander à l’utilisateur de faire l’une des choses suivantes :

    • Fournir le consentement, si nécessaire.
    • Gérer l’authentification étape par étape, telle que l’authentification à deux facteurs.
  3. Teams demande le jeton d’application bot au point AAD de l’utilisateur actuel.

  4. AAD envoie le jeton d’application bot à l’Teams application.

  5. Teams envoie le jeton au bot dans le cadre de l’objet de valeur renvoyé par l’activité d’appel avec le nom sign-in/tokenExchange.

  6. Le jeton analysée dans l’application bot fournit les informations requises, telles que l’adresse de l’utilisateur.

Développer un bot d’Teams sso

Pour développer un robot DSO, Teams les étapes suivantes :

  1. Inscrivez votre application via le portail AAD.
  2. Mettez à jour Teams manifeste d’application pour votre bot.
  3. Ajoutez le code pour demander et recevoir un jeton de bot.

Inscrire votre application via le portail AAD client

Les étapes d’inscription de votre application via le portail AAD sont similaires au flux d' utilisateur unique de l’onglet. Pour inscrire votre application, complétez les étapes suivantes :

  1. Inscrivez une nouvelle application dans le portail Azure Active Directory – Inscriptions des applications.

  2. Sélectionnez Nouvelle inscription. La page Inscrire une application s’affiche.

  3. Dans la page Inscrire une application, entrez les valeurs suivantes :

    1. Entrez un nom pour votre application.

    2. Choisissez les types de comptes pris en charge, sélectionnez le type de compte client unique ou multi-locataire.

      Notes

      Les utilisateurs ne sont pas invités à donner leur consentement et se voir accorder des jetons d’accès immédiatement, si l’application AAD est inscrite dans le même client qu’il fait une demande d’authentification dans Teams. Toutefois, les utilisateurs doivent donner leur consentement aux autorisations, si l’application AAD est inscrite dans un autre client.

    3. Choisissez Inscrire.

  4. Dans la page vue d’ensemble, copiez et enregistrez l’ID de l’application (client). Vous en aurez besoin ultérieurement lors de la mise à jour Teams manifeste de l’application.

  5. Sélectionnez Exposer une API sous Gérer.

    Important

    • Si vous construisez un bot autonome, entrez l’URI d’ID d’application sous le nom api://botid-{YourBotId} . Ici, YourBotId est votre ID AAD’application.
    • Si vous construisez une application avec un bot et un onglet, entrez l’URI d’ID d’application sous le nom api://fully-qualified-domain-name.com/botid-{YourBotId} .
  6. Sélectionnez les autorisations dont votre application a besoin pour AAD point de terminaison et, éventuellement, pour Microsoft Graph.

  7. Accorder des autorisations pour Teams applications de bureau, web et mobiles.

  8. Sélectionnez Ajouter une étendue.

  9. Dans le panneau qui s’ouvre, ajoutez une application cliente en entrant access_as_user le nom de l’étendue.

    Notes

    L’étendue « access_as_user » utilisée pour ajouter une application cliente est pour « Administrateurs et utilisateurs ».

    Vous devez connaître les restrictions importantes suivantes :

    • Seules les autorisations de l’API microsoft Graph de niveau utilisateur, telles que la messagerie, le profil, offline_access et OpenId, sont pris en charge. Si vous avez besoin d’accéder à d’autres Graph microsoft, telles que ou , voir Obtenir un jeton d’accès User.Read Mail.Read avec Graph autorisations.
    • Le nom de domaine de votre application doit être identique au nom de domaine que vous avez inscrit pour AAD application.
    • Plusieurs domaines par application ne sont actuellement pas pris en charge.
    • Les applications qui utilisent le domaine ne sont pas pris en charge azurewebsites.net car elles sont courantes et peuvent être un risque pour la sécurité.

Mettre à jour le portail Azure avec la connexion OAuth

Pour mettre à jour le portail Azure avec la connexion OAuth, effectuer les étapes suivantes :

  1. Dans le portail Azure, go to App registrations.

  2. Go to API Permissions. Sélectionnez Ajouter une autorisation Microsoft > Graph > autorisations déléguées, puis ajoutez les autorisations suivantes à partir de l’API Microsoft Graph :

    • User.Read (activé par défaut)
    • email
    • offline_access
    • OpenId
    • profil
  3. Dans le portail Azure, allez à AzureBot

  4. Sélectionnez Configuration dans le volet gauche.

  5. Sélectionnez Ajouter une connexion OAuth Paramètres.

    Affichage SSOBotHandle2

  6. Pour remplir le formulaire Nouveau paramètre de connexion, effectuez les étapes suivantes :

    Notes

    L’octroi implicite peut être requis dans l AAD application.

    1. Entrez un nom dans la page Nouveau paramètre de connexion. Il s’agit du nom qui est référent dans les paramètres de votre code de service de bot à l’étape 5 de l' sso du bot lors de l’utilisation.
    2. Dans la drop-down Fournisseur de services, sélectionnez Azure Active Directory v2.
    3. Entrez les informations d’identification du client, telles que l’ID client et la secret client pour l’application AAD client.
    4. Pour l’URL Exchange jeton, utilisez la valeur d’étendue définie dans Mettre à jour Teams manifeste d’application pour votre bot. L’URL Exchange de jeton indique au SDK que cette application AAD est configurée pour l' sso.
    5. Dans la zone ID client, entrez commun.
    6. Ajoutez toutes les étendues configurées lors de la spécification d’autorisations pour les API en aval pour AAD application. Avec l’ID client et la secret client fournis, le magasin de jetons échange le jeton contre un jeton graphique avec des autorisations définies.
    7. Sélectionnez Enregistrer.

    Affichage des paramètres VuSSOBotConnection

Mettre à jour Teams manifeste d’application pour votre bot

Si l’application contient un bot autonome, utilisez le code suivant pour ajouter de nouvelles propriétés au manifeste Teams’application :

    "webApplicationInfo": 
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "resource": "api://botid-00000000-0000-0000-0000-000000000000"
        }

Si l’application contient un bot et un onglet, utilisez le code suivant pour ajouter de nouvelles propriétés au manifeste Teams’application :

    "webApplicationInfo": 
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "resource": "api://subdomain.example.com/botid-00000000-0000-0000-0000-000000000000"
        }

webApplicationInfo est le parent des éléments suivants :

  • id : ID client de l’application. Il s’agit de l’ID d’application que vous avez obtenu dans le cadre de l’inscription de l’application auprès AAD. Ne partagez pas cet ID d’application avec plusieurs Teams applications. Créez une application AAD pour chaque manifeste d’application qui utilise webApplicationInfo .
  • ressource : domaine et sous-domaine de votre application. Il s’agit du même URI, y compris le protocole que vous avez inscrit lors de la création de votre application dans Enregistrer votre application api:// scope via le portail AAD. Vous ne devez pas inclure le access_as_user chemin d’accès dans votre ressource. La partie domaine de cet URI doit correspondre au domaine et aux sous-domaines utilisés dans les URL de votre manifeste Teams’application.

Ajouter le code pour demander et recevoir un jeton de bot

Demander un jeton de bot

La demande d’obtenir le jeton est une demande de message POST normale à l’aide du schéma de message existant. Il est inclus dans les pièces jointes d’un OAuthCard. Le schéma de la classe OAuthCard est défini dans Microsoft Bot Schema 4.0 et est similaire à une carte de signature. Teams traite cette demande comme une acquisition de jeton silencieuse si la propriété TokenExchangeResource est remplie sur la carte. Pour le Teams, seule la propriété, qui identifie de manière unique une demande de Id jeton, est honorée.

Notes

Le Microsoft Bot Framework OAuthPrompt ou est pris en charge pour MultiProviderAuthDialog l’authentification sso.

Si l’utilisateur utilise l’application pour la première fois et que le consentement de l’utilisateur est requis, la boîte de dialogue suivante s’affiche pour poursuivre l’expérience de consentement :

Boîte de dialogue de consentement

Lorsque l’utilisateur sélectionne Continuer, ces événements se produisent :

  • Si le bot définit un bouton de sign-in, le flux de se connectant pour les bots est déclenché de la même façon que le flux de la signature à partir d’un bouton de carte OAuth dans un flux de message. Le développeur doit décider des autorisations qui nécessitent le consentement de l’utilisateur. Cette approche est recommandée si vous avez besoin d’un jeton avec des autorisations openId au-delà. Par exemple, si vous souhaitez échanger le jeton pour les ressources graphiques.

  • Si le bot ne fournit pas de bouton de sign-in sur la carte OAuth, le consentement de l’utilisateur est requis pour un ensemble minimal d’autorisations. Ce jeton est utile pour l’authentification de base et pour obtenir l’adresse e-mail de l’utilisateur.

C# demande de jeton sans bouton de sign-in
    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);

Recevoir le jeton du bot

La réponse avec le jeton est envoyée par le biais d’une activité d’appel avec le même schéma que les autres activités d’appel que les bots reçoivent aujourd’hui. La seule différence est le nom de l’appel, la sign-in/tokenExchange et le champ valeur. Le champ de valeur contient l’ID, une chaîne de la demande initiale pour obtenir le jeton et le champ de jeton, une valeur de chaîne incluant le jeton.

Notes

Vous pouvez recevoir plusieurs réponses pour une demande donnée si l’utilisateur a plusieurs points de terminaison actifs. Vous devez déduplicer les réponses avec le jeton.

C# code pour gérer l’activité d’appel
    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();
                }
            }

Il turnContext.activity.value est de type TokenExchangeInvokeRequest et contient le jeton qui peut être utilisé par votre bot. Vous devez stocker les jetons pour des raisons de performances et les actualiser.

Échec de l’échange de jetons

En cas d’échec de l’échange de jetons, utilisez le code suivant :

{ 
    "status": "<response code>", 
    "body": 
    { 
        "id":"<unique Id>", 
        "connectionName": "<connection Name on the bot (from the OAuth card)>", 
        "failureDetail": "<failure reason if status code is not 200, null otherwise>" 
    } 
}

Pour comprendre ce que fait le bot lorsque l’échange de jetons ne parvient pas à déclencher une invite de consentement, consultez les étapes suivantes :

Notes

Aucune action de l’utilisateur n’est requise car le bot prend les mesures en cas d’échec de l’échange de jetons.

  1. Le client démarre une conversation avec le bot déclenchant un scénario OAuth.

  2. Le bot renvoie une carte OAuth au client.

  3. Le client intercepte la carte OAuth avant de l’afficher à l’utilisateur et vérifie si elle contient une TokenExchangeResource propriété.

  4. Si la propriété existe, le client envoie un TokenExchangeInvokeRequest message au bot. Le client doit avoir un jeton échangeable pour l’utilisateur, qui doit être un jeton Azure AD v2 et dont l’audience doit être identique à la TokenExchangeResource.Uri propriété. Le client envoie une activité d’appel au bot avec le code suivant :

    {
        "type": "Invoke",
        "name": "signin/tokenExchange",
        "value": 
        {
            "id": "<any unique Id>",
            "connectionName": "<connection Name on the skill bot (from the OAuth card)>",
            "token": "<exchangeable token>"
        }
    }
    
  5. Le bot traite le TokenExchangeInvokeRequest client et renvoie un retour au TokenExchangeInvokeResponse client. Le client doit attendre qu’il reçoit le TokenExchangeInvokeResponse .

    {
        "status": "<response code>",
        "body": 
        {
            "id":"<unique Id>",
            "connectionName": "<connection Name on the skill bot (from the OAuth card)>",
            "failureDetail": "<failure reason if status code is not 200, null otherwise>"
        }
    }
    
  6. TokenExchangeInvokeResponseS’il en possède status 200 une, le client n’affiche pas la carte OAuth. Voir l’image de flux normal. Pour toute autre carte ou si elle n’est pas reçue, le client affiche la carte status TokenExchangeInvokeResponse OAuth à l’utilisateur. Voir l’image de flux de retour. Cela garantit que le flux DSO revient au flux OAuthCard normal en cas d’erreurs ou de dépendances non satisfaits telles que le consentement de l’utilisateur.

Mettre à jour l’exemple d’th

Ouvrez Teams exemple d’th, puis complétez les étapes suivantes pour le mettre à jour :

  1. Mettez à jour TeamsBot pour gérer le déduping de la demande entrante en incluant le code suivant :

        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);
            }
    
  2. Mise à jour pour inclure le mot de passe, et le nom de connexion défini dans Mettre à jour le portail Azure avec appsettings.json botId la connexion OAuth.

  3. Mettez à jour le manifeste et token.botframework.com assurez-vous qu’il figure dans la liste des domaines valides. Pour plus d’informations, voir Teams exemple d’th.

  4. Zip the manifest with the profile images and install it in Teams.

Exemple de code

Exemple de nom Description .NET
Bot framework SDK Exemple d’utilisation du SDK Bot Framework. View