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.

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 :

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

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.

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

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

É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)

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
}

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

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.

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).

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
}

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.

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).

É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
}

Modifications du protocole de sécurité

Authentification du robot vers le connecteur

URL de connexion OAuth

Étendue OAuth

Authentification du connecteur vers le robot

Document de métadonnées OpenID

Émetteur JWT

Authentification de l’émulateur vers le robot

URL de connexion OAuth

Étendue OAuth

Public JWT

Émetteur JWT

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

Document de métadonnées OpenID

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