Ajouter l’authentification tierce à votre extension de message

  • Article

Importante

Les exemples de code de cette section sont basés sur la version 4.6 et les versions ultérieures du Kit de développement logiciel (SDK) Bot Framework. Si vous recherchez de la documentation pour les versions antérieures, consultez la section Extensions de message - Kit de développement logiciel (SDK) v3 dans le dossier Ressources de la documentation.

Remarque

Après avoir ajouté l’authentification à l’extension de message, vous devez ajouter « token.botframework.com » à la section « validDomains » du manifeste.

Identifier l’utilisateur

Chaque demande adressée à vos services inclut l’ID d’utilisateur, le nom d’affichage de l’utilisateur et Microsoft Entra’ID d’objet.

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

Les valeurs id et aadObjectId sont garanties pour l’utilisateur Teams authentifié. Elles sont utilisées comme clés pour rechercher les informations d’identification ou tout état mis en cache dans votre service. En outre, chaque requête contient l’ID de locataire Microsoft Entra, qui est utilisé pour identifier les organization de l’utilisateur. Le cas échéant, la requête contient également l’ID d’équipe et l’ID de canal d’où provient la demande.

Authentification

Si votre service requiert l’authentification de l’utilisateur, les utilisateurs doivent se connecter avant d’utiliser l’extension de message. Les étapes d’authentification sont similaires à celles d’un bot ou d’un onglet. La séquence est la suivante :

  1. L’utilisateur émet une requête ou la requête par défaut est automatiquement envoyée à votre service.
  2. Votre service vérifie si l’utilisateur est authentifié en inspectant l’ID d’utilisateur Teams.
  3. Si l’utilisateur n’est pas authentifié, renvoyez une réponse auth avec une action suggérée openUrl, y compris l’URL d’authentification.
  4. Le client Microsoft Teams lance une boîte de dialogue hébergeant votre page web à l’aide de l’URL d’authentification donnée.
  5. Une fois que l’utilisateur s’est connecté, vous devez fermer votre fenêtre et envoyer un code d’authentification au client Teams.
  6. Le client Teams publie ensuite la requête à sur votre service, qui inclut le code d’authentification passé à l’étape 5.

Votre service doit vérifier que le code d’authentification reçu à l’étape 6 correspond à l’étape 5. Les étapes garantissent qu’un utilisateur malveillant n’essaie pas d’usurper ou de compromettre le flux de connexion. Le flux « ferme effectivement la boucle » pour terminer la séquence d’authentification sécurisée.

Répondre avec une action de connexion

Pour inviter un utilisateur non authentifié à se connecter, répondez avec une action suggérée de type openUrl qui inclut l’URL d’authentification.

Exemple de réponse pour une action de connexion

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

Remarque

  • 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 de vos applications’ de domaines valides. Pour plus d’informations, consultez validDomains dans le schéma du manifeste.
  • La taille de la fenêtre contextuelle d’authentification peut être définie en incluant des paramètres de chaîne de requête de largeur et de hauteur, Value = $"{_siteUrl}/searchSettings.html?height=600&width=600".

Démarrer le flux de connexion

Votre expérience de connexion doit être réactive et tenir dans une fenêtre contextuelle. Il doit s’intégrer à la bibliothèque de client JavaScript Microsoft Teams, qui utilise le passage de messages.

Comme pour les autres expériences incorporées s’exécutant dans Microsoft Teams, votre code à l’intérieur de la fenêtre doit d’abord appeler app.initialize(). Si votre code exécute un flux OAuth, vous pouvez passer l’ID utilisateur Teams dans votre fenêtre, qui le transmet ensuite à l’URL de connexion OAuth.

Terminer le flux de connexion

Une fois la requête de connexion terminée et redirigée vers votre page, elle doit effectuer les étapes suivantes :

  1. Générez un code de sécurité, un nombre aléatoire. Vous devez mettre en cache ce code sur votre service, avec les informations d’identification obtenues via le flux de connexion, telles que les jetons OAuth 2.0.
  2. Appelez authentication.notifySuccess et transmettez le code de sécurité.

À ce stade, la fenêtre se ferme et le contrôle est passé au client Teams. Le client publie à nouveau la requête utilisateur d’origine, ainsi que le code de sécurité dans la propriété state . Votre code peut utiliser le code de sécurité pour rechercher les informations d’identification stockées précédemment afin de terminer la séquence d’authentification, puis la requête de l’utilisateur.

Exemple de nouvelle publication de requête

{
    "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"
}

Exemple de code

Exemple de nom Description .NET Node.js Manifeste
Extensions de message - authentification et configuration Extension de message qui a une page de configuration, accepte les demandes de recherche et retourne les résultats une fois que l’utilisateur s’est connecté. View View View

Voir aussi

Activer l’authentification unique pour votre application d’extension de bot et de message