Authentification avec l’API Bot Connector

Votre bot communique avec le service Bot Connector à l’aide de HTTP via un canal sécurisé (SSL/TLS). Lorsque votre bot envoie une demande au service Connecteur, il doit inclure des informations que le service connecteur peut utiliser pour vérifier son identité. De même, lorsque le service Connector envoie une demande à votre bot, il doit inclure des informations que le bot peut utiliser pour vérifier son identité. Cet article décrit les technologies d’authentification et les exigences relatives à l’authentification au niveau du service qui se déroule entre un bot et le service Bot Connector. Si vous écrivez votre propre code d’authentification, vous devez implémenter les procédures de sécurité décrites dans cet article pour permettre à votre bot d’échanger des messages avec le service Bot Connector.

Si vous utilisez le Kit de développement logiciel (SDK) Bot Framework, vous n’avez pas besoin d’implémenter les procédures de sécurité décrites dans cet article, car le Kit de développement logiciel (SDK) le fait automatiquement pour vous. Configurez simplement votre projet avec l’ID d’application et le mot de passe que vous avez obtenus pour votre bot lors de l’inscription et le Kit de développement logiciel (SDK) gère le reste.

Technologies d’authentification

Quatre technologies d’authentification sont utilisées pour établir l’approbation entre un bot et bot Connector :

Cet article explique comment utiliser ces technologies via HTTPS et JSON standard. Aucun SDK spécial n’est nécessaire, bien que vous trouviez peut-être que les helpers pour OpenID et d’autres sont utiles.

Authentifier les demandes de votre bot auprès du service Bot Connector

Pour communiquer avec le service Bot Connector, vous devez spécifier un jeton d’accès dans l’en-tête de chaque requête d’API, à l’aide Authorization de ce format :

Authorization: Bearer ACCESS_TOKEN

Pour obtenir et utiliser un jeton JWT pour votre bot :

1. Votre bot envoie une requête 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 Bot Connector.

Étape 1 : Demander un jeton d’accès à partir du service de connexion de compte Microsoft Entra ID

Votre identité de bot peut être gérée de Azure de plusieurs façons différentes.

• En tant qu’identité managée affectée par l’utilisateur, vous n’avez donc pas besoin de gérer vous-même les informations d’identification du bot.
• En tant qu'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 de compte Microsoft Entra ID

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

Lors de l’ajout du jeton à l’en-tête Authorization d’une requête, vous devez utiliser la valeur exacte spécifiée dans cette réponse : n’échappez pas ou n’encodez pas la valeur du jeton. Le jeton d’accès est valide jusqu’à son expiration. Pour empêcher l’expiration du jeton d’impacter les performances de votre bot, vous pouvez choisir de mettre en cache et d’actualiser de manière proactive le jeton.

Cet exemple montre une réponse du service de connexion de 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 : Spécifier le jeton JWT dans l’en-tête d’autorisation des demandes

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

Authorization: Bearer ACCESS_TOKEN

Toutes les demandes 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 de compte Microsoft Entra ID, le service Bot Connector autorise la requête. Des vérifications supplémentaires sont effectuées pour s’assurer que le jeton appartient au bot qui a envoyé la demande.

L’exemple suivant montre comment spécifier 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)

Bot to Connector : exemples 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
}

Authentifier les demandes du service Bot Connector à votre bot

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

Pour authentifier les appels à partir du service Bot Connector :

1. Votre bot obtient le jeton JWT à partir de l’en-tête d’autorisation dans les demandes envoyées par le service Bot Connector.
2. Votre bot obtient le document de métadonnées OpenID pour le service Bot Connector.
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 : Obtenir le document de métadonnées OpenID

Le document de métadonnées OpenID spécifie l’emplacement d’un deuxième document qui répertorie les clés de signature valides du service Bot Connector. Pour obtenir le document de métadonnées OpenID, émettez cette requête via HTTPS :

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

L’exemple suivant montre un document de métadonnées OpenID retourné en réponse à la GET demande. La jwks_uri propriété spécifie 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 : Obtenir la liste des clés de signature valides

Pour obtenir la liste des clés de signature valides, émettez une GET demande via HTTPS vers l’URL spécifiée par la jwks_uri propriété 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 spécifie le document au format JWK , mais inclut également une propriété supplémentaire pour chaque clé : endorsements.

La endorsements propriété dans chaque clé contient une ou plusieurs chaînes d’approbation que vous pouvez utiliser pour vérifier que l’ID de canal spécifié dans la propriété dans l’objet channelIdActivité de la requête entrante est authentique. La liste des ID de canal qui nécessitent des approbations est configurable dans chaque bot. Par défaut, il s’agit de la liste de tous les ID de canal publiés, bien que les développeurs de bots puissent remplacer les valeurs d’ID de canal sélectionnées de manière ou d’une autre.

É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 demande, analyser le jeton, vérifier son contenu et vérifier sa signature.

Les bibliothèques d’analyse JWT sont disponibles pour de nombreuses plateformes et implémentent l’analyse sécurisée et fiable pour les jetons JWT, même si vous devez généralement configurer ces bibliothèques pour exiger que certaines caractéristiques du jeton (son émetteur, son audience, et ainsi de suite) contiennent des valeurs correctes. Lors de l’analyse du jeton, vous devez configurer la bibliothèque d’analyse ou écrire votre propre validation pour vous assurer que le jeton répond à ces exigences :

1. Le jeton a été envoyé dans l’en-tête HTTP Authorization selon le schéma « Bearer ».
2. Le jeton est un JSON valide qui est conforme à la norme JWT.
3. Le jeton contient une revendication « émetteur » avec la valeur https://api.botframework.com.
4. Le jeton contient une revendication « audience » avec une valeur égale à l'ID d'application Microsoft du bot.
5. Le jeton est dans sa période de validité. Le décalage d’horloge conforme à la norme du secteur est de 5 minutes.
6. Le jeton a une signature de chiffrement valide, avec une clé répertoriée dans le document des clés OpenID récupérée à l’étape 3, à l’aide de l’algorithme de signature spécifié dans la id_token_signing_alg_values_supported propriété du document de métadonnées Open ID récupéré à l’étape 2.
7. Le jeton contient une revendication « serviceUrl » avec une valeur qui correspond à la propriété serviceUrl à la racine de l’objet Activity de la requête entrante.

Si l’approbation d’un ID de canal est requise :

• Vous devez exiger que tout Activity objet envoyé à votre bot avec cet ID de canal soit accompagné d’un jeton JWT signé avec une approbation pour ce canal.
• Si l’approbation n’est pas présente, votre bot doit rejeter la requête en retournant un code d’état HTTP 403 (Interdit).

Les implémenteurs ne doivent pas exposer un moyen de désactiver la validation du jeton JWT envoyé au bot.

Connecteur à Bot : exemples 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 demandes de l’émulateur Bot Framework à votre bot

Bot Framework Emulator est un outil de bureau que vous pouvez utiliser pour tester les fonctionnalités de votre bot. Bien que l’émulateur Bot Framework utilise les mêmes technologies d’authentification que celles décrites ci-dessus, il n’est pas en mesure d’emprunter l’identité du service Bot Connector réel. Au lieu de cela, il utilise l’ID d’application Microsoft et Microsoft mot de passe de l’application que vous spécifiez lorsque vous connectez l’émulateur à votre bot pour créer des jetons identiques à ceux créés par le bot. Lorsque l’émulateur envoie une requête à votre bot, il spécifie le jeton JWT dans l’en-tête Authorization de la requête, en essence, en utilisant les propres informations d’identification du bot pour authentifier la demande.

Si vous implémentez une bibliothèque d’authentification et que vous souhaitez accepter des demandes de l’émulateur Bot Framework, vous devez ajouter ce chemin de vérification supplémentaire. Le chemin d’accès est structurellement similaire au chemin de vérification du connecteur -> Bot , mais il utilise le document OpenID de MSA au lieu du document OpenID de Bot Connector.

Pour authentifier les appels à partir de l’émulateur Bot Framework :

1. Votre bot obtient le jeton JWT à partir de l’en-tête d’autorisation dans les demandes envoyées à partir de l’émulateur Bot Framework.
2. Votre bot obtient le document de métadonnées OpenID pour le service Bot Connector.
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 : Obtenir le document de métadonnées OPENID MSA

Le document de métadonnées OpenID spécifie l’emplacement d’un deuxième document qui répertorie les clés de signature valides. Pour obtenir le document de métadonnées MSA OpenID, émettez cette requête 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 retourné en réponse à la GET demande. La jwks_uri propriété spécifie 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 : Obtenir la liste des clés de signature valides

Pour obtenir la liste des clés de signature valides, émettez une GET demande via HTTPS vers l’URL spécifiée par la jwks_uri propriété 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 spécifie 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 demande, analyser le jeton, vérifier son contenu et vérifier sa signature.

Les bibliothèques d’analyse JWT sont disponibles pour de nombreuses plateformes et implémentent l’analyse sécurisée et fiable pour les jetons JWT, même si vous devez généralement configurer ces bibliothèques pour exiger que certaines caractéristiques du jeton (son émetteur, son audience, et ainsi de suite) contiennent des valeurs correctes. Lors de l’analyse du jeton, vous devez configurer la bibliothèque d’analyse ou écrire votre propre validation pour vous assurer que le jeton répond à ces exigences :

1. Le jeton a été envoyé dans l’en-tête HTTP Authorization selon le schéma « Bearer ».
2. Le jeton est un JSON valide qui est conforme à la norme JWT.
3. Le jeton contient une revendication d’émetteur pour le protocole de sécurité applicable. Pour l’implémentation actuelle, consultez Microsoft. Agents.Connector.
4. Le jeton contient une revendication « audience » avec une valeur égale à l'ID d'application Microsoft du bot.
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 est dans sa période de validité. Le décalage d’horloge conforme à la norme du secteur est de 5 minutes.
7. Le jeton a une signature de chiffrement valide avec une clé répertoriée dans le document de clés OpenID récupéré à l’étape 3.

Si le jeton ne répond pas à toutes ces exigences, votre bot doit terminer la requête en retournant un code d’état HTTP 403 (Interdit).

Émulateur vers bot : exemples 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 bot auprès du connecteur

URL de connexion OAuth

Étendue OAuth

Connecteur à l’authentification bot

Document de métadonnées OpenID

Émetteur JWT

Authentification de l’émulateur auprès du bot

URL de connexion OAuth

Étendue OAuth

JWT Audience

Émetteur JWT

Pour l’implémentation actuelle, consultez Microsoft. Agents.Connector.

Document de métadonnées OpenID

Ressources additionnelles

• Résoudre les problèmes d’authentification de Bot Framework
• Spécification du protocole d’activité
• Informations de référence sur l’API RestConnectorClient
• JSON Web Token (JWT) draft-jones-json-web-token-07
• JSON Web Signature (JWS) draft-jones-json-web-signature-04
• Clé web JSON (JWK) RFC 7517