Authentification avec le connecteur bot API

Votre robot communique avec le service Bot Connector en utilisant le protocole HTTP sur un canal sécurisé (SSL/TLS). Lorsque votre robot envoie une requête au service du connecteur, il doit inclure des informations lui permettant de vérifier son identité. De même, lorsque le service du connecteur envoie une requête à votre robot, il doit inclure des informations lui permettant vérifier son identité. Cet article décrit les technologies d’authentification et les exigences en matière d’authentification au niveau du service entre un robot et le service Bot Connector. Si vous créez votre propre code d'authentification, vous devez appliquer les procédures de sécurité décrites dans cet article pour que votre robot puisse échanger des messages avec le service de connecteur bot.

Important

Si vous créez votre propre code d'authentification, il est essentiel que vous appliquiez correctement toutes les procédures de sécurité. En appliquant toutes les étapes de cet article, vous pouvez réduire le risque qu’un pirate puisse lire les messages envoyés à votre robot, envoyer des messages qui usurpent l’identité de votre robot et voler des clés secrètes.

Si vous utilisez le kit de développement logiciel (SDK) Bot Framework, vous n'avez pas besoin de mettre en œuvre les procédures de sécurité décrites dans cet article, car le kit de développement logiciel (SDK) le fait automatiquement pour vous. Il vous suffit de configurer votre projet avec l’identifiant de l’application et le mot de passe obtenus pour votre robot lors de l’enregistrement. Le kit de développement logiciel s’occupe du reste.

Technologies d'authentification

Quatre technologies d’authentification sont utilisées pour assurer la fiabilité entre un robot et Bot Connector :

Technology	Description
SSL/TLS	La technologie SSL/TLS est utilisée pour toutes les connexions de service à service. Les certificats X.509v3 permettent de déterminer l’identité de tous les services HTTPS. Les clients doivent toujours vérifier les certificats de service pour s’assurer de leur fiabilité et de leur validité. (Ce programme N’utilise PAS de certificats de clients.)
OAuth 2.0	OAuth 2.0 utilise le service de connexion au compte Microsoft Entra ID pour générer un jeton sécurisé qu'un bot peut utiliser pour envoyer des messages. Il s’agit d’un jeton de service à service ; aucune connexion utilisateur n’est nécessaire.
JSON Web Token (JWT)	Les JWT permettent d’encoder les jetons qui sont envoyés vers et depuis le robot. Les clients doivent vérifier tous les jetons JWT qu’ils reçoivent, conformément aux exigences décrites dans cet article.
Métadonnées OpenID	Le service Bot Connector publie une liste des jetons valides qu’il utilise pour signer ses propres jetons JWT sur les métadonnées OpenID à un point de terminaison statique bien défini.

Cet article décrit comment utiliser ces technologies à l’aide des standards HTTPS et JSON. Aucun kit de développement logiciel (SDK) spécial n'est requis, bien que vous puissiez trouver de l'utilité aux aides pour OpenID, etc.

Authentifier les requêtes de votre robot auprès du service de connecteur bot

Pour communiquer avec le service Bot Connector, vous devez indiquer un jeton d’accès dans l’en-tête Authorization de chaque requête API, au format suivant :

Authorization: Bearer ACCESS_TOKEN

Pour obtenir et utiliser un jeton JWT pour votre bot :

1. Votre bot envoie une demande HTTP GET au service de connexion MSA.
2. La réponse du service contient le jeton JWT à utiliser.
3. Votre bot inclut ce jeton JWT dans l'en-tête d'autorisation dans les demandes adressées au service de connecteur bot

Étape 1 : demandez un jeton d'accès auprès du service de connexion du compte Microsoft Entra ID

Important

Si vous ne l'avez pas déjà terminé, vous devez enregistrer votre bot auprès de Bot Framework pour obtenir son identifiant d'application et son mot de passe. Pour demander un jeton d’accès, vous avez besoin de l’identifiant d’application et du mot de passe du bot.

L'identité de votre bot peut être gérée dans Azure de différentes manières.

• S'il s'agit d'une identité managée affectée par l'utilisateur, vous n'avez pas besoin de gérer vous-même les informations d'identification du bot.
• S'il s'agit d'une application à locataire unique.
• En tant qu'application multilocataire.

Demandez un jeton d'accès en fonction du type d'application de votre bot.

Multilocataire

Pour demander un jeton d'accès au service de connexion, envoyez la requête suivante en remplaçant MICROSOFT-APP-ID et MICROSOFT-APP-PASSWORD par l'identifiant d'application et le mot de passe du bot que vous avez obtenus lorsque vous avez enregistré votre bot avec le service bot.

POST https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=MICROSOFT-APP-ID&client_secret=MICROSOFT-APP-PASSWORD&scope=https%3A%2F%2Fapi.botframework.com%2F.default

Locataire unique

Pour demander un jeton d'accès au service de connexion, envoyez la requête suivante en remplaçant MICROSOFT-APP-ID, MICROSOFT-APP-PASSWORD et MICROSOFT-TENANT-ID par l'identifiant d'application, le mot de passe du bot et l'identifiant du locataire que vous avez obtenus lorsque vous avez enregistré votre bot avec le service bot.

POST https://login.microsoftonline.com/MICROSOFT-TENANT-ID/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=MICROSOFT-APP-ID&client_secret=MICROSOFT-APP-PASSWORD&scope=https%3A%2F%2Fapi.botframework.com%2F.default

Identité managée affectée par l’utilisateur

App Service et Azure Functions fournissent un point de terminaison REST accessible en interne pour la récupération des jetons. Pour demander un jeton d'accès à partir du point de terminaison MSI/token, envoyez une requête GET au point de terminaison. Utilisez les paramètres de requête resource et client_id. Définissez resource sur https://api.botframework.com et client_id sur l'ID d'application d'identité managée du bot. La requête ne nécessite aucun paramètre de requête.

• Pour plus d'informations sur le point de terminaison de jeton, consultez Connecter aux services Azure dans le code de l'application.
• Pour plus d'informations sur les identifiants d'application bot, consultez Créer une ressource Azure Bot

Étape 2 : obtenir le jeton JWT à partir de la réponse du service de connexion du compte Microsoft Entra ID

Si votre application est autorisée par le service de connexion, le corps de la réponse JSON indique votre jeton d’accès, son type et son délai d’expiration (en secondes).

Lorsque vous ajoutez le jeton à l'en-tête Authorization d'une requête, vous devez utiliser la valeur exacte qui est spécifiée dans cette réponse (n'échappez pas et n'encodez pas la valeur du jeton). Le jeton d’accès est valide jusqu’à son expiration. Pour éviter que l’expiration des jetons n’ait une incidence sur le fonctionnement de votre robot, vous pouvez choisir de les mettre en cache et de les actualiser de façon proactive.

Cet exemple indique une réponse du service d'ouverture de session du compte Microsoft Entra ID :

HTTP/1.1 200 OK
... (other headers)

{
    "token_type":"Bearer",
    "expires_in":3600,
    "ext_expires_in":3600,
    "access_token":"eyJhbGciOiJIUzI1Ni..."
}

Étape 3 : Indiquer le jeton JWT dans l’en-tête d’autorisation des requêtes

Lorsque vous envoyez une requête API au service Bot Connector, indiquez le jeton d’accès dans l’en-tête Authorization de la requête, au format suivant :

Authorization: Bearer ACCESS_TOKEN

Toutes les requêtes que vous envoyez au service Bot Connector doivent inclure le jeton d’accès dans l’en-tête Authorization. Si le jeton est correctement formé, n'a pas expiré et a été généré par le service de connexion au compte Microsoft Entra ID, le service de connecteur Bot autorisera la demande. Des vérifications supplémentaires sont effectuées pour s’assurer que le jeton appartient au robot qui a envoyé la requête.

L’exemple suivant montre comment indiquer le jeton d’accès dans l’en-tête Authorization de la requête.

POST https://smba.trafficmanager.net/teams/v3/conversations/12345/activities
Authorization: Bearer eyJhbGciOiJIUzI1Ni...

(JSON-serialized Activity message goes here)

Important

Indiquez le jeton JWT uniquement dans l’en-tête Authorization des requêtes que vous envoyez au service Bot Connector. N’envoyez PAS le jeton sur des canaux non sécurisés et NE l’incluez PAS dans les requêtes HTTP que vous envoyez à d’autres services. Le jeton JWT que vous obtenez du service de connexion au compte Microsoft Entra ID est comme un mot de passe et doit être manipulé avec beaucoup de précautions. Toutes les personnes qui disposent du jeton peuvent s’en servir pour effectuer des opérations au nom de votre robot.

Robot vers connecteur : exemple de composants JWT

header:
{
  typ: "JWT",
  alg: "RS256",
  x5t: "<SIGNING KEY ID>",
  kid: "<SIGNING KEY ID>"
},
payload:
{
  aud: "https://api.botframework.com",
  iss: "https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/",
  nbf: 1481049243,
  exp: 1481053143,
  appid: "<YOUR MICROSOFT APP ID>",
  ... other fields follow
}

Remarque

En pratique, les champs réels peuvent être différents. Créez et validez tous les jetons JWT comme indiqué ci-dessus.

Pour authentifier les requêtes du service de connecteur Bot auprès de votre bot

Lorsque le service Bot Connector envoie une requête à votre robot, il indique un jeton JWT signé dans l’en-tête Authorization de la requête. Votre robot peut authentifier les appels du service Bot Connector en vérifiant l’authenticité du jeton JWT signé.

Pour authentifier les appels provenant du service de connecteur bot :

1. Votre bot obtient le jeton JWT à partir de l'en-tête d'autorisation dans les demandes envoyées par le service de connecteur bot.
2. Votre bot obtient le document de métadonnées OpenID pour le service de connecteur Bot
3. Votre bot obtient la liste des clés de signature valides à partir du document.
4. Votre bot vérifie l'authenticité du jeton JWT.

Étape 2 : récupérer le document de métadonnées OpenID

Le document de métadonnées OpenID indique l’emplacement d’un second document qui énumère les clés de signature valides du service Bot Connector. Pour récupérer le document de métadonnées OpenID, envoyez la requête suivante via HTTPS :

GET https://login.botframework.com/v1/.well-known/openidconfiguration

Conseil

Il s’agit d’une URL statique que vous pouvez coder en dur dans votre application.

L’exemple suivant montre un document de métadonnées OpenID qui est renvoyé en réponse à la requête GET. La propriété jwks_uri indique l’emplacement du document qui contient les clés de signature valides du service Bot Connector.

{
    "issuer": "https://api.botframework.com",
    "authorization_endpoint": "https://invalid.botframework.com",
    "jwks_uri": "https://login.botframework.com/v1/.well-known/keys",
    "id_token_signing_alg_values_supported": [
      "RS256"
    ],
    "token_endpoint_auth_methods_supported": [
      "private_key_jwt"
    ]
}

Étape 3 : récupérer la liste des clés de signature valides

Pour obtenir la liste des clés de signature valides, envoyez une requête GET via HTTPS à l’URL indiquée par la propriété jwks_uri dans le document de métadonnées OpenID. Par exemple :

GET https://login.botframework.com/v1/.well-known/keys

Le corps de la réponse indique le document au format JWK. Il inclut également une propriété supplémentaire pour chaque clé : endorsements.

Conseil

La liste des clés est stable et peut être mise en cache, mais de nouvelles clés peuvent être ajoutées à tout moment. Pour vous assurer que votre bot dispose d'une copie à jour du document avant que ces clés ne soient utilisées, toutes les instances de bot doivent actualiser leur cache local du document au moins une fois toutes les 24 heures.

La propriété endorsements de chaque clé contient une ou plusieurs chaînes d'approbation que vous pouvez utiliser pour vérifier l'authenticité de l'identifiant de canal indiqué dans la propriété channelId dans l'objet Activité de la requête entrante. La liste des identifiants de canal nécessitant une approbation est configurable dans chaque robot. Par défaut, la liste contient tous les identifiants des canaux publiés. Les développeurs de robots peuvent néanmoins remplacer les valeurs des identifiants des canaux sélectionnés.

Étape 4 : Vérifier le jeton JWT

Pour vérifier l’authenticité du jeton envoyé par le service Bot Connector, vous devez extraire le jeton de l’en-tête Authorization de la requête, l’analyser, vérifier son contenu et vérifier sa signature.

Des bibliothèques d'analyse JWT sont disponibles pour de nombreuses plateformes et la plupart d'entre elles mettent en œuvre une analyse sécurisée et fiable des jetons JWT, bien que vous deviez généralement configurer ces bibliothèques pour exiger que certaines caractéristiques du jeton (son émetteur, son public, etc.) contiennent des valeurs correctes. Lorsque vous analysez le jeton, vous devez configurer la bibliothèque d’analyse ou inscrire votre propre validation pour vous assurer qu’il respecte ces exigences :

1. Le jeton a été envoyé dans l’en-tête HTTP Authorization avec le schéma « porteur ».
2. Le jeton est un JSON valide conforme à la norme JWT .
3. Le jeton contient une revendication « émetteur » ayant une valeur de https://api.botframework.com.
4. Le jeton contient une revendication « public » ayant une valeur égale à l’identifiant de l’application Microsoft du robot.
5. Le jeton se trouve dans sa période de validité. La durée standard dans le secteur est de 5 minutes.
6. La signature chiffrée du jeton est valide et la clé est répertoriée dans le document des clés OpenID récupéré à l’étape 3 à l’aide de l’algorithme de signature indiqué dans la propriété id_token_signing_alg_values_supported du document Open ID Metadata récupéré à l’étape 2.
7. Le jeton contient une revendication « serviceUrl » dont la valeur correspond à la propriété serviceUrl à la racine de l’objet Activité de la requête entrante.

Si l’identifiant du canal nécessite une approbation :

• Vous devez exiger que tous les objets Activity envoyés à votre bot avec cet identifiant de canal soient accompagnés d’un jeton JWT signé avec une approbation de ce canal.
• S'il manque l'approbation, votre bot doit rejeter la requête en renvoyant un code d'état HTTP 403 (interdit).

Important

Toutes ces exigences sont importantes, notamment les exigences 4 et 6. Si vous n’appliquez pas TOUTES ces exigences de vérification, le robot sera exposé à des attaques susceptibles d’entraîner la divulgation de son jeton JWT.

Les implémenteurs doivent éviter que la validation du jeton JWT envoyé au bot puisse être désactivée.

Connecteur vers Robot : exemple de composants JWT

header:
{
  typ: "JWT",
  alg: "RS256",
  x5t: "<SIGNING KEY ID>",
  kid: "<SIGNING KEY ID>"
},
payload:
{
  aud: "<YOU MICROSOFT APP ID>",
  iss: "https://api.botframework.com",
  nbf: 1481049243,
  exp: 1481053143,
  ... other fields follow
}

Remarque

En pratique, les champs réels peuvent être différents. Créez et validez tous les jetons JWT comme indiqué ci-dessus.

Authentifier les requêtes de Bot Framework Emulator auprès de votre bot

L’émulateur de Bot Framework est un outil de bureau dont vous pouvez vous servir pour tester les fonctionnalités de votre robot. Bien que Bot Framework Emulator utilise les mêmes technologies d'authentification que celles décrites ci-dessus, il ne peut usurper l'identité du véritable service de connecteur bot. À la place, il utilise l'ID d'ID d'application Microsoft et du mot de passe de Microsoft App que vous indiquez lorsque vous connectez l'émulateur à votre robot pour créer des jetons identiques à ceux créés par le bot. Lorsque l'émulateur envoie une requête à votre robot, il indique le jeton JWT dans l'en-tête Authorization de la requête. En fait, il utilise ses propres identifiants pour authentifier la requête.

Pour accepter les requêtes de Bot Framework Emulator en implémentant une bibliothèque d'authentification, vous devez ajouter ce chemin d'accès de vérification supplémentaire. La structure du chemin d'accès est similaire à celle du chemin de vérification connecteur -> bot. Par contre, il fait appel au document OpenID de MSA au lieu du document OpenID du connecteur de bot.

Pour authentifier les appels provenant de Bot Framework Emulator :

1. Votre bot obtient le jeton JWT à partir de l'en-tête d'autorisation dans les demandes envoyées à partir de Bot Framework Emulator.
2. Votre bot obtient le document de métadonnées OpenID pour le service de connecteur Bot
3. Votre bot obtient la liste des clés de signature valides à partir du document.
4. Votre bot vérifie l'authenticité du jeton JWT.

---

Étape 2 : Récupérer le document de métadonnées OpenID de MSA

Le document de métadonnées OpenID indique l’emplacement d’un second document qui énumère les clés de signature valides. Pour récupérer le document de métadonnées OpenID de MSA, envoyez la requête suivante via HTTPS :

GET https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

L’exemple suivant montre un document de métadonnées OpenID qui est renvoyé en réponse à la requête GET. La propriété jwks_uri indique l’emplacement du document qui contient les clés de signature valides.

{
    "authorization_endpoint":"https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
    "token_endpoint":"https://login.microsoftonline.com/common/oauth2/v2.0/token",
    "token_endpoint_auth_methods_supported":["client_secret_post","private_key_jwt"],
    "jwks_uri":"https://login.microsoftonline.com/common/discovery/v2.0/keys",
    ...
}

Étape 3 : récupérer la liste des clés de signature valides

Pour obtenir la liste des clés de signature valides, envoyez une requête GET via HTTPS à l’URL indiquée par la propriété jwks_uri dans le document de métadonnées OpenID. Par exemple :

GET https://login.microsoftonline.com/common/discovery/v2.0/keys
Host: login.microsoftonline.com

Le corps de la réponse indique le document au format JWK .

Étape 4 : Vérifier le jeton JWT

Pour vérifier l'authenticité du jeton envoyé par l'émulateur, vous devez extraire le jeton de l'en-tête Authorization de la requête, l'analyser, vérifier son contenu et vérifier sa signature.

Des bibliothèques d'analyse JWT sont disponibles pour de nombreuses plateformes et la plupart d'entre elles mettent en œuvre une analyse sécurisée et fiable des jetons JWT, bien que vous deviez généralement configurer ces bibliothèques pour exiger que certaines caractéristiques du jeton (son émetteur, son public, etc.) contiennent des valeurs correctes. Lorsque vous analysez le jeton, vous devez configurer la bibliothèque d’analyse ou inscrire votre propre validation pour vous assurer qu’il respecte ces exigences :

1. Le jeton a été envoyé dans l’en-tête HTTP Authorization avec le schéma « porteur ».
2. Le jeton est un JSON valide conforme à la norme JWT .
3. Le jeton contient une revendication « émetteur » avec l'une des valeurs mises en exergue pour les cas non gouvernementaux. Le fait de vérifier les deux valeurs d'émetteur permet de s'assurer que les valeurs d'émetteur des protocoles de sécurité v3.1 et v3.2 sont bien vérifiées.
4. Le jeton contient une revendication « public » ayant une valeur égale à l’identifiant de l’application Microsoft du robot.
5. L'émulateur, selon la version, envoie l'AppId via la revendication appid (version 1) ou la revendication de partie autorisée (version 2).
6. Le jeton se trouve dans sa période de validité. La durée standard dans le secteur est de 5 minutes.
7. Le jeton a une signature chiffrée valide avec une clé répertoriée dans le document des clés OpenID récupéré à l’étape 3.

Remarque

L'exigence 5 est spécifique au chemin d'accès de vérification de l'émulateur.

Si le jeton ne remplit pas toutes ces conditions, votre bot doit mettre fin à la demande en renvoyant un code d'état HTTP 403 (interdit).

Important

Toutes ces exigences sont importantes, notamment les exigences 4 et 7. Si vous n’appliquez pas TOUTES ces exigences de vérification, le robot sera exposé à des attaques susceptibles d’entraîner la divulgation de son jeton JWT.

Émulateur vers Robot : exemple de composants JWT

header:
{
  typ: "JWT",
  alg: "RS256",
  x5t: "<SIGNING KEY ID>",
  kid: "<SIGNING KEY ID>"
},
payload:
{
  aud: "<YOUR MICROSOFT APP ID>",
  iss: "https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/",
  nbf: 1481049243,
  exp: 1481053143,
  ... other fields follow
}

Remarque

En pratique, les champs réels peuvent être différents. Créez et validez tous les jetons JWT comme indiqué ci-dessus.

Modifications du protocole de sécurité

Authentification du robot vers le connecteur

URL de connexion OAuth

Version du protocole	Valeur valide
v3.1 et v3.2	https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

Étendue OAuth

Version du protocole	Valeur valide
v3.1 et v3.2	https://api.botframework.com/.default

Authentification du connecteur vers le robot

Document de métadonnées OpenID

Version du protocole	Valeur valide
v3.1 et v3.2	https://login.botframework.com/v1/.well-known/openidconfiguration

Émetteur JWT

Version du protocole	Valeur valide
v3.1 et v3.2	https://api.botframework.com

Authentification de l’émulateur vers le robot

URL de connexion OAuth

Version du protocole	Valeur valide
v3.1 et v3.2	https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

Étendue OAuth

Version du protocole	Valeur valide
v3.1 et v3.2	Identificateur de l'ID d'application Microsoft de votre bot + /.default

Public JWT

Version du protocole	Valeur valide
v3.1 et v3.2	Identificateur de l'ID d'application Microsoft de votre bot

Émetteur JWT

Version du protocole	Valeur valide
v3.1 1.0	https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/
v3.1 2.0	https://login.microsoftonline.com/d6d49420-f39b-4df7-a1dc-d59a935871db/v2.0
v3.2 1.0	https://sts.windows.net/f8cdef31-a31e-4b4a-93e4-5f571e91255a/
v3.2 2.0	https://login.microsoftonline.com/f8cdef31-a31e-4b4a-93e4-5f571e91255a/v2.0

Consultez également les valeurs mises en exergue pour les cas non gouvernementaux.

Document de métadonnées OpenID

Version du protocole	Valeur valide
v3.1 et v3.2	https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

Ressources supplémentaires

• Résoudre les problèmes d’authentification de Bot Framework
• Schéma d’activité Bot Framework
• JSON Web Token (JWT) draft-jones-json-web-token-07
• JSON Web Signature (JWS) draft-jones-json-web-signature-04
• JSON Web Key (JWK) RFC 7517