Ajouter l’authentification à votre extension de messagerieAdd authentication to your messaging extension

Important

Les exemples de code de cette section sont basés sur 4,6 et les versions ultérieures du kit de développement logiciel (SDK) de l’infrastructure bot.The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. Si vous recherchez de la documentation pour les versions antérieures, reportez-vous à la section extensions de messagerie-v3 SDK dans le dossier Resources de la documentation.If you're looking for documentation for earlier versions, see the Messaging Extensions - v3 SDK section in the Resources folder of the documentation.

Identifier l’utilisateurIdentify the user

Chaque demande adressée à vos services comprend l’ID brouillé de l’utilisateur qui a exécuté la demande, ainsi que le nom d’affichage et l’ID d’objet Azure Active Directory de l’utilisateur.Every request to your services includes the obfuscated ID of the user that performed the request, as well as the user's display name and Azure Active Directory object ID.

"from": {
  "id": "29:1C7dbRrC_5yzN1RGtZIrcWT0xz88KPGP9sxdpVpV8sODlgPHeQE9RqQ02hnpuKzy6zZ-AaZx6swUOMj_Dsdse3TQ4sIaeebbFBF-VgjJy_nY",
  "name": "Larry Jin",
  "aadObjectId": "cd723fa0-0591-416a-9290-e93ecf3a9b92"
},

Les id valeurs aadObjectId et sont garanties comme celles de l’utilisateur de teams authentifié.The id and aadObjectId values are guaranteed to be that of the authenticated Teams user. Elles peuvent être utilisées en tant que clés pour rechercher des informations d’identification ou un État mis en cache dans votre service.They can be used as keys to look up credentials or any cached state in your service. En outre, chaque requête contient l’ID de client Azure Active Directory de l’utilisateur, qui peut être utilisé pour identifier l’organisation de l’utilisateur.In addition, each request contains the Azure Active Directory tenant ID of the user, which can be used to identify the user’s organization. Le cas échéant, la demande contient également les ID d’équipe et de canal à l’origine de la demande.If applicable, the request also contains the team and channel IDs from which the request originated.

AuthentificationAuthentication

Si votre service requiert l’authentification de l’utilisateur, vous devez vous connecter à l’utilisateur avant de pouvoir utiliser l’extension de messagerie.If your service requires user authentication, you need to sign in the user before he or she can use the messaging extension. Si vous avez écrit un bot ou un onglet qui se connecte à l’utilisateur, cette section doit être familière.If you have written a bot or a tab that signs in the user, this section should be familiar.

La séquence est la suivante :The sequence is as follows:

  1. Un utilisateur émet une requête ou la requête par défaut est automatiquement envoyée à votre service.User issues a query, or the default query is automatically sent to your service.
  2. Votre service vérifie si l’utilisateur a d’abord été authentifié en inspectant l’ID utilisateur Teams.Your service checks whether the user has first authenticated by inspecting the Teams user ID.
  3. Si l’utilisateur n’est pas authentifié, renvoyez une auth réponse avec une openUrl action suggérée, y compris l’URL d’authentification.If the user has not authenticated, send back an auth response with an openUrl suggested action including the authentication URL.
  4. Le client Microsoft teams lance une fenêtre contextuelle hébergeant votre page Web à l’aide de l’URL d’authentification donnée.The Microsoft Teams client launches a pop-up window hosting your webpage using the given authentication URL.
  5. Une fois que l’utilisateur se connecte, vous devez fermer votre fenêtre et envoyer un « code d’authentification » au client Teams.After the user signs in, you should close your window and send an "authentication code" to the Teams client.
  6. Le client teams réémet ensuite la requête à votre service, ce qui inclut le code d’authentification passé à l’étape 5.The Teams client then reissues the query to your service, which includes the authentication code passed in step 5.

Votre service doit vérifier que le code d’authentification reçu à l’étape 6 correspond à celui de l’étape 5.Your service should verify that the authentication code received in step 6 matches the one from step 5. Cela permet de s’assurer qu’un utilisateur malveillant n’essaie pas d’usurper ou de compromettre le flux de connexion.This ensures that a malicious user does not try to spoof or compromise the sign-in flow. Cela « ferme la boucle » de manière efficace pour terminer la séquence d’authentification sécurisée.This effectively "closes the loop" to finish the secure authentication sequence.

Répondre à l’aide d’une action de connexionRespond with a sign-in action

Pour inviter un utilisateur non authentifié à se connecter, répondez avec une action suggérée de openUrl type qui inclut l’URL d’authentification.To prompt an unauthenticated user to sign in, respond with a suggested action of type openUrl that includes the authentication URL.

Exemple de réponse pour une action de connexionResponse example for a sign-in action

{
  "composeExtension":{
    "type":"auth",
    "suggestedActions":{
      "actions":[
        {
          "type": "openUrl",
          "value": "https://example.com/auth",
          "title": "Sign in to this app"
        }
      ]
    }
  }
}

Notes

Pour que l’expérience de connexion soit hébergée dans une fenêtre contextuelle Teams, la partie domaine de l’URL doit figurer dans la liste des domaines valides de votre application.For the sign-in experience to be hosted in a Teams pop-up, the domain portion of the URL must be in your app’s list of valid domains. (Voir validDomains dans le schéma de manifeste.)(See validDomains in the manifest schema.)

Démarrer le flux de connexionStart the sign-in flow

Votre expérience de connexion doit être réactive et s’ajuster dans une fenêtre contextuelle.Your sign-in experience should be responsive and fit within a popup window. Il doit s’intégrer avec le Kit de développement logiciel (SDK) JavaScript de Microsoft teams, qui utilise le passage des messages.It should integrate with the Microsoft Teams JavaScript client SDK, which uses message passing.

Comme pour les autres expériences incorporées s’exécutant dans Microsoft Teams, votre code à l’intérieur microsoftTeams.initialize()de la fenêtre doit commencer par appeler.As with other embedded experiences running inside Microsoft Teams, your code inside the window needs to first call microsoftTeams.initialize(). Si votre code effectue un flux OAuth, vous pouvez transmettre l’ID d’utilisateur teams dans votre fenêtre, qui peut ensuite la transmettre à l’URL de connexion OAuth.If your code performs an OAuth flow, you can pass the Teams user ID into your window, which then can pass it to the OAuth sign-in URL.

Terminer le flux de connexionComplete the sign-in flow

Lorsque la demande de connexion se termine et redirige vers votre page, elle doit effectuer les étapes suivantes :When the sign-in request completes and redirects back to your page, it should perform the following steps:

  1. Générez un code de sécurité.Generate a security code. (Il peut s’agir d’un nombre aléatoire.) Vous devez mettre en cache ce code sur votre service, ainsi que les informations d’identification obtenues via le flux de connexion (par exemple, les jetons OAuth 2,0).(This can be a random number.) You need to cache this code on your service, along with the credentials obtained through the sign-in flow (such as OAuth 2.0 tokens).
  2. Appelez microsoftTeams.authentication.notifySuccess et transférez le code de sécurité.Call microsoftTeams.authentication.notifySuccess and pass the security code.

À ce stade, la fenêtre se ferme et le contrôle est transmis au client Teams.At this point, the window closes and control is passed to the Teams client. Le client peut désormais réexécuter la requête de l’utilisateur d’origine, ainsi que le code state de sécurité dans la propriété.The client now can reissue the original user query, along with the security code in the state property. Votre code peut utiliser le code de sécurité pour rechercher les informations d’identification stockées précédemment pour terminer la séquence d’authentification, puis terminer la demande de l’utilisateur.Your code can use the security code to look up the credentials stored earlier to complete the authentication sequence and then complete the user request.

Exemple de requête reémiseReissued request example

{
    "name": "composeExtension/query",
    "value": {
        "commandId": "insertWiki",
        "parameters": [{
            "name": "searchKeyword",
            "value": "lakers"
        }],
        "state": "12345",
        "queryOptions": {
            "skip": 0,
            "count": 25
        }
    },
    "type": "invoke",
    "timestamp": "2017-04-26T05:18:25.629Z",
    "localTimestamp": "2017-04-25T22:18:25.629-07:00",
    "entities": [{
        "locale": "en-US",
        "country": "US",
        "platform": "Web",
        "type": "clientInfo"
    }],
    "text": "",
    "attachments": [],
    "address": {
        "id": "f:7638210432489287768",
        "channelId": "msteams",
        "user": {
            "id": "29:1A5TJWHkbOwSyu_L9Ktk9QFI1d_kBOEPeNEeO1INscpKHzHTvWfiau5AX_6y3SuiOby-r73dzHJ17HipUWqGPgw",
            "aadObjectId": "fc8ca1c0-d043-4af6-b09f-141536207403"
        },
        "conversation": {
            "id": "19:7705841b240044b297123ad7f9c99217@thread.skype"
        },
        "bot": {
            "id": "28:c073afa8-7e77-4f92-b3e7-aa589e952a3e",
            "name": "maotestbot2"
        },
        "serviceUrl": "https://smba.trafficmanager.net/amer-client-ss.msg/",
        "useAuth": true
    },
    "source": "msteams"
}