Autenticación con Bot Connector APIAuthentication with the Bot Connector API

El bot se comunica con el servicio Bot Connector con HTTP mediante un canal seguro (SSL/TLS).Your bot communicates with the Bot Connector service using HTTP over a secured channel (SSL/TLS). Cuando el bot envía una solicitud al servicio Connector, debe incluir información que el servicio Connector puede usar para comprobar su identidad.When your bot sends a request to the Connector service, it must include information that the Connector service can use to verify its identity. Del mismo modo, cuando el servicio Connector envía una solicitud al bot, debe incluir información que el bot puede usar para comprobar su identidad.Likewise, when the Connector service sends a request to your bot, it must include information that the bot can use to verify its identity. En este artículo se describen las tecnologías y los requisitos para la autenticación en el nivel de servicio que tiene lugar entre un bot y el servicio Bot Connector.This article describes the authentication technologies and requirements for the service-level authentication that takes place between a bot and the Bot Connector service. Si está escribiendo su propio código de autenticación, debe implementar los procedimientos de seguridad descritos en este artículo para habilitar al bot para el intercambio de mensajes con el servicio Bot Connector.If you are writing your own authentication code, you must implement the security procedures described in this article to enable your bot to exchange messages with the Bot Connector service.

Importante

Si está escribiendo su propio código de autenticación, es fundamental que aplique correctamente todos los procedimientos de seguridad.If you are writing your own authentication code, it is critical that you implement all security procedures correctly. Mediante la implementación de todos los pasos de este artículo, puede mitigar el riesgo de que un atacante pueda leer los mensajes que se envían al bot, enviar mensajes que suplanten al bot y robar las claves secretas.By implementing all steps in this article, you can mitigate the risk of an attacker being able to read messages that are sent to your bot, send messages that impersonate your bot, and steal secret keys.

Si usa Bot Framework SDK para .NET o Bot Framework SDK para Node.js, no es necesario implementar los procedimientos de seguridad descritos en este artículo, que el SDK lo hace automáticamente.If you are using the Bot Framework SDK for .NET or the Bot Framework SDK for Node.js, you do not need to implement the security procedures described in this article, because the SDK automatically does it for you. Basta con configurar el proyecto con el identificador de aplicación y la contraseña que obtuvo para el bot durante el registro y el SDK controlará el resto.Simply configure your project with the App ID and password that you obtained for your bot during registration and the SDK will handle the rest.

Advertencia

En diciembre de 2016, la versión v3.1 del protocolo de seguridad de Bot Framework presentó cambios en varios valores que se usan durante la generación y validación de los tokens.In December 2016, v3.1 of the Bot Framework security protocol introduced changes to several values that are used during token generation and validation. A finales de otoño de 2017, la versión v3.2 del protocolo de seguridad de Bot Framework presenta cambios en los valores que se usan durante la generación y validación de los tokens.In late fall of 2017, v3.2 of the Bot Framework security protocol was introduced which included changes to values that are used during token generation and validation. Para más información, consulte Cambios en el protocolo de seguridad.For more information, see Security protocol changes.

Tecnologías de autenticaciónAuthentication technologies

Se utilizan cuatro tecnologías de autenticación para establecer la confianza entre un bot y Bot Connector:Four authentication technologies are used to establish trust between a bot and the Bot Connector:

TechnologyTechnology DescripciónDescription
SSL/TLSSSL/TLS Se usa SSL/TLS para todas las conexiones de servicio a servicio.SSL/TLS is used for all service-to-service connections. Se utilizan certificadosX.509v3 para establecer la identidad de todos los servicios HTTPS.X.509v3 certificates are used to establish the identity of all HTTPS services. Los clientes siempre deben inspeccionar los certificados del servicio para asegurarse de que son válidos y de confianza.Clients should always inspect service certificates to ensure they are trusted and valid. (No se usan certificados de cliente como parte de este esquema).(Client certificates are NOT used as part of this scheme.)
OAuth 2.0OAuth 2.0 OAuth 2.0 usa el servicio de inicio de sesión de cuenta de Azure Active Directory (Azure AD) v2 para generar un token seguro que un bot puede usar para enviar mensajes.OAuth 2.0 uses the Azure Active Directory (Azure AD) v2 account login service to generate a secure token that a bot can use to send messages. Este token es un token de servicio a servicio, no es necesario ningún inicio de sesión de usuario.This token is a service-to-service token; no user login is required.
JSON Web Token (JWT)JSON Web Token (JWT) Los JSON Web Token se usan para codificar los tokens que se envían hacia y desde el bot.JSON Web Tokens are used to encode tokens that are sent to and from the bot. Los clientes deben comprobar completamente todos los tokens JWT que reciben, según los requisitos descritos en este artículo.Clients should fully verify all JWT tokens that they receive, according to the requirements outlined in this article.
Metadatos de OpenIDOpenID metadata El servicio Bot Connector publica una lista de tokens válidos que usa para firmar sus propios tokens JWT en los metadatos de OpenID en un punto de conexión conocido y estático.The Bot Connector service publishes a list of valid tokens that it uses to sign its own JWT tokens to OpenID metadata at a well-known, static endpoint.

En este artículo se describe cómo usar estas tecnologías mediante HTTPS y JSON estándar.This article describes how to use these technologies via standard HTTPS and JSON. No es necesario ningún SDK especial, aunque es posible que los asistentes para OpenID y otras le sean útiles.No special SDKs are required, although you may find that helpers for OpenID etc. are useful.

Autenticación de las solicitudes del bot al servicio Bot ConnectorAuthenticate requests from your bot to the Bot Connector service

Para comunicarse con el servicio Bot Connector, debe especificar un token de acceso en el encabezado Authorization de cada solicitud de API, con este formato:To communicate with the Bot Connector service, you must specify an access token in the Authorization header of each API request, using this format:

Authorization: Bearer ACCESS_TOKEN

Este diagrama muestra los pasos de la autenticación de bot a Connector:This diagram shows the steps for bot-to-connector authentication:

Autenticación con el servicio de inicio de sesión de MSA y, a continuación, con el bot

Paso 1: Solicitud de un token de acceso al servicio de inicio de sesión de cuenta de Azure AD v2Step 1: Request an access token from the Azure AD v2 account login service

Importante

Si aún no lo ha hecho, deberá registrar el bot con Bot Framework para obtener el identificador de aplicación y la contraseña.If you have not already done so, you must register your bot with the Bot Framework to obtain its AppID and password. Necesita el identificador de la aplicación del bot y la contraseña para solicitar un token de acceso.You need the bot's App ID and password to request an access token.

Para solicitar un token de acceso al servicio de inicio de sesión, emita la siguiente solicitud y reemplace MICROSOFT-APP-ID y MICROSOFT-APP-PASSWORD por el identificador de aplicación del bot y la contraseña que obtuvo cuando registró el bot en Bot Framework.To request an access token from the login service, issue the following request, replacing MICROSOFT-APP-ID and MICROSOFT-APP-PASSWORD with the bot's AppID and password that you obtained when you registered your bot with the Bot Framework.

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

Paso 2: Obtención del token JWT de la respuesta del servicio de inicio de sesión de cuenta de Azure AD v2Step 2: Obtain the JWT token from the the Azure AD v2 account login service response

Si la aplicación es autorizada por el servicio de inicio de sesión, el cuerpo de la respuesta JSON especificará el token de acceso, su tipo y la expiración (en segundos).If your application is authorized by the login service, the JSON response body will specify your access token, its type, and its expiration (in seconds).

Al agregar el token al encabezado Authorization de una solicitud, debe usar el valor exacto especificado en esta respuesta (es decir, sin escape ni codificación del valor del token).When adding the token to the Authorization header of a request, you must use the exact value that is specified in this response (i.e., do not escape or encode the token value). El token de acceso es válido hasta su expiración.The access token is valid until its expiration. Para evitar que expire el token y afecte al rendimiento del bot, puede almacenarlo en caché y actualizar el token de forma proactiva.To prevent token expiration from impacting your bot's performance, you may choose to cache and proactively refresh the token.

En este ejemplo se muestra una respuesta del servicio de inicio de sesión de cuenta de Azure AD v2:This example shows a response from the the Azure AD v2 account login service:

HTTP/1.1 200 OK
... (other headers)
{
    "token_type":"Bearer",
    "expires_in":3600,
    "ext_expires_in":3600,
    "access_token":"eyJhbGciOiJIUzI1Ni..."
}

Paso 3: Especificación del token JWT en el encabezado Authorization de las solicitudesStep 3: Specify the JWT token in the Authorization header of requests

Cuando se envía una solicitud de API al servicio Bot Connector, debe especificar el token de acceso en el encabezado Authorization de la solicitud con este formato:When you send an API request to the Bot Connector service, specify the access token in the Authorization header of the request using this format:

Authorization: Bearer ACCESS_TOKEN

Todas las solicitudes que envíe al servicio Bot Connector deben incluir el token de acceso en el encabezado Authorization.All requests that you send to the Bot Connector service must include the access token in the Authorization header. Si el token tiene un formato correcto, no ha expirado y fue generado por el servicio de inicio de sesión de cuenta de Azure AD v2, el servicio Bot Connector autorizará la solicitud.If the token is correctly formed, is not expired, and was generated by the the Azure AD v2 account login service, the Bot Connector service will authorize the request. Se realizan comprobaciones adicionales para asegurarse de que el token pertenece al bot que envió la solicitud.Additional checks are performed to ensure that the token belongs to the bot that sent the request.

El ejemplo siguiente muestra cómo especificar el token de acceso en el encabezado Authorization de la solicitud.The following example shows how to specify the access token in the Authorization header of the request.

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

(JSON-serialized Activity message goes here)

Importante

Especifique el token JWT solo en el encabezado Authorization de las solicitudes que envíe al servicio Bot Connector.Only specify the JWT token in the Authorization header of requests you send to the Bot Connector service. No envíe el token por canales no seguros y no lo incluya en las solicitudes HTTP que se envían a otros servicios.Do NOT send the token over unsecured channels and do NOT include it in HTTP requests that you send to other services. El token JWT que obtiene del servicio de inicio de sesión de cuenta de Azure AD v2 es como una contraseña y debe utilizarse con mucho cuidado.The JWT token that you obtain from the the Azure AD v2 account login service is like a password and should be handled with great care. Cualquiera que tenga el token puede usarlo para realizar operaciones en nombre del bot.Anyone that possesses the token may use it to perform operations on behalf of your bot.

Bot a Connector: componentes JWT de ejemploBot to Connector: example JWT components

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
}

Nota

Los campos reales pueden variar en la práctica.Actual fields may vary in practice. Debe crear y validar todos los tokens JWT según lo especificado anteriormente.Create and validate all JWT tokens as specified above.

Autenticación de las solicitudes del servicio Bot Connector al botAuthenticate requests from the Bot Connector service to your bot

Cuando el servicio Bot Connector envía una solicitud al bot, especifica un token JWT firmado en el encabezado Authorization de la solicitud.When the Bot Connector service sends a request to your bot, it specifies a signed JWT token in the Authorization header of the request. El bot puede autenticar las llamadas desde el servicio Bot Connector al verificar la autenticidad del token JWT firmado.Your bot can authenticate calls from the Bot Connector service by verifying the authenticity of the signed JWT token.

Este diagrama muestra los pasos de la autenticación de Connector a bot:This diagram shows the steps for connector-to-bot authentication:

Autenticación de las llamadas desde Bot Connector al bot

Paso 2: Obtención del documento de metadatos de OpenIDStep 2: Get the OpenID metadata document

El documento de metadatos de OpenID especifica la ubicación de un segundo documento que enumera las claves de firma válidas del servicio Bot Connector.The OpenID metadata document specifies the location of a second document that lists the Bot Connector service's valid signing keys. Para obtener el documento de metadatos de OpenID, emita esta solicitud mediante HTTPS:To get the OpenID metadata document, issue this request via HTTPS:

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

Sugerencia

Se trata de una dirección URL estática que se puede insertar directamente en la aplicación.This is a static URL that you can hardcode into your application.

El ejemplo siguiente muestra un documento de metadatos de OpenID devuelto en respuesta a la solicitud GET.The following example shows an OpenID metadata document that is returned in response to the GET request. La propiedad jwks_uri especifica la ubicación del documento que contiene las claves de firma válidas del servicio Bot Connector.The jwks_uri property specifies the location of the document that contains the Bot Connector service's valid signing keys.

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

Paso 3: Obtención de la lista de claves de firma válidasStep 3: Get the list of valid signing keys

Para obtener la lista de claves de firma válidas, emita una solicitud GET mediante HTTPS a la dirección URL especificada por la propiedad jwks_uri en el documento de metadatos de OpenID.To get the list of valid signing keys, issue a GET request via HTTPS to the URL specified by the jwks_uri property in the OpenID metadata document. Por ejemplo:For example:

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

El cuerpo de la respuesta especifica el documento en formato JWK, pero también incluye una propiedad adicional para cada clave: endorsements.The response body specifies the document in the JWK format but also includes an additional property for each key: endorsements.

Sugerencia

La lista de claves es estable y se puede almacenar en caché, pero se pueden agregar nuevas claves en cualquier momento.The list of keys is stable and may be cached, but new keys may be added at any time. Para asegurarse de que el bot tiene una copia actualizada del documento antes de usar estas claves, todas las instancias del bot deben actualizar su caché local del documento al menos una vez cada 24 horas.To ensure your bot has an up-to-date copy of the document before these keys are used, all bot instances should refresh their local cache of the document at least once every 24 hours.

La propiedad endorsements dentro de cada clave contiene una o más cadenas de aprobación que puede usar para comprobar que el identificador de canal especificado en la propiedad channelId dentro del objeto Actividad de la solicitud entrante es auténtico.The endorsements property within each key contains one or more endorsement strings which you can use to verify that the channel ID specified in the channelId property within the Activity object of the incoming request is authentic. La lista de identificadores de canal que requieren aprobaciones es configurable en cada bot.The list of channel IDs that require endorsements is configurable within each bot. De forma predeterminada, será la lista de todos los identificadores de canal publicados, aunque los desarrolladores de bots pueden invalidar los valores de identificador de canal seleccionados en cualquier caso.By default, it will be the list of all published channel IDs, although bot developers may override selected channel ID values either way.

Paso 4: Verificación del token JWTStep 4: Verify the JWT token

Para verificar la autenticidad del token enviado por el servicio Bot Connector, debe extraer el token del encabezado Authorization de la solicitud, analizar el token, verificar su contenido y verificar su firma.To verify the authenticity of the token that was sent by the Bot Connector service, you must extract the token from the Authorization header of the request, parse the token, verify its contents, and verify its signature.

Hay disponibles bibliotecas de análisis de JWT para muchas plataformas y la mayoría implementa un análisis de los tokens JWT seguro y confiable, aunque normalmente deberá configurar estas bibliotecas para requerir que determinadas características del token (su emisor, audiencia, etc.) contengan valores correctos.JWT parsing libraries are available for many platforms and most implement secure and reliable parsing for JWT tokens, although you must typically configure these libraries to require that certain characteristics of the token (its issuer, audience, etc.) contain correct values. Al analizar el token, debe configurar la biblioteca de análisis o escribir su propia validación para asegurarse de que el token cumple estos requisitos:When parsing the token, you must configure the parsing library or write your own validation to ensure the token meets these requirements:

  1. El token se ha enviado en el encabezado HTTP Authorization con un esquema "Bearer" (Portador).The token was sent in the HTTP Authorization header with "Bearer" scheme.
  2. El token tiene un formato JSON válido que se ajusta al estándar JWT.The token is valid JSON that conforms to the JWT standard.
  3. El token contiene una notificación "issuer" (emisor) con el valor https://api.botframework.com.The token contains an "issuer" claim with value of https://api.botframework.com.
  4. El token contiene una notificación "audience" (audiencia) con un valor igual al identificador de aplicación de Microsoft del bot.The token contains an "audience" claim with a value equal to the bot's Microsoft App ID.
  5. El token está dentro de su período de validez.The token is within its validity period. El tiempo estándar del sector es de 5 minutos.Industry-standard clock-skew is 5 minutes.
  6. El token tiene una firma criptográfica válida, con una clave enumerada en el documento de claves de OpenID que se recuperó en el Paso 3, utilizando el algoritmo de firma que se especifica en la propiedad id_token_signing_alg_values_supported del documento de metadatos de OpenID que se recuperó en Paso 2.The token has a valid cryptographic signature, with a key listed in the OpenID keys document that was retrieved in Step 3, using the signing algorithm that is specified in the id_token_signing_alg_values_supported property of the Open ID Metadata document that was retrieved in Step 2.
  7. El token contiene una notificación "serviceUrl" (dirección URL de servicio) cuyo valor coincide con la propiedad serviceUrl en la raíz del objeto Actividad de la solicitud entrante.The token contains a "serviceUrl" claim with value that matches the serviceUrl property at the root of the Activity object of the incoming request.

Si se requiere aprobación para un identificador de canal:If endorsement for a channel ID is required:

  • Debe requerir que cualquier objeto Activity enviado al bot con ese identificador de canal venga acompañado de un token JWT firmado con una aprobación para ese canal.You should require that any Activity object sent to your bot with that channel ID is accompanied by a JWT token that is signed with an endorsement for that channel.
  • Si la aprobación no está presente, el bot debe rechazar la solicitud devolviendo un código de estado HTTP 403 (prohibido) .If the endorsement is not present, your bot should reject the request by returning an HTTP 403 (Forbidden) status code.

Importante

Todos estos requisitos son importantes, especialmente los requisitos 4 y 6.All of these requirements are important, particularly requirements 4 and 6. En caso de no implementarse todos estos requisitos de comprobación, se dejaría el bot abierto a ataques que podrían provocar que el bot divulgue su token JWT.Failure to implement ALL of these verification requirements will leave the bot open to attacks which could cause the bot to divulge its JWT token.

Los implementadores no deben exponer una manera de deshabilitar la validación del token JWT que se envía al bot.Implementers should not expose a way to disable validation of the JWT token that is sent to the bot.

Connector a bot: componentes JWT de ejemploConnector to Bot: example JWT components

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
}

Nota

Los campos reales pueden variar en la práctica.Actual fields may vary in practice. Debe crear y validar todos los tokens JWT según lo especificado anteriormente.Create and validate all JWT tokens as specified above.

Autenticación de las solicitudes del emulador de Bot Framework al botAuthenticate requests from the Bot Framework Emulator to your bot

Advertencia

A finales de otoño de 2017, se presenta la versión v3.2 del protocolo de seguridad de Bot Framework.In late fall of 2017, v3.2 of the Bot Framework security protocol was introduced. Esta nueva versión incluye un nuevo valor "issuer" (emisor) dentro de los tokens que se intercambian entre el emulador de Bot Framework y el bot.This new version includes a new "issuer" value within tokens that are exchanged between the Bot Framework Eumaltor and your bot. Para prepararse para este cambio, los pasos siguientes describen cómo comprobar los valores de emisor de las versiones v3.1 y v3.2.To prepare for this change, the below steps outline how to check for both the v3.1 and v3.2 issuer values.

El Emulador de Bot Framework es una herramienta de escritorio que puede usar para probar la funcionalidad del bot.The Bot Framework Emulator is a desktop tool that you can use to test the functionality of your bot. Aunque el emulador de Bot Framework usa las mismas tecnologías de autenticación que se describieron anteriormente, no puede suplantar al servicio Bot Connector real.Although the Bot Framework Emulator uses the same authentication technologies as described above, it is unable to impersonate the real Bot Connector service. En su lugar, usa el identificador de aplicación de Microsoft y la contraseña de aplicación de Microsoft que se especifican al conectar el emulador al bot para crear tokens idénticos a los que crea el bot.Instead, it uses the Microsoft App ID and Microsoft App Password that you specify when you connect the Emulator to your bot to create tokens that are identical to those that the bot creates. Cuando el emulador envía una solicitud al bot, especifica el token JWT en el encabezado de la solicitud, básicamente, mediante las propias credenciales del bot para autenticar Authorization la solicitud.When the Emulator sends a request to your bot, it specifies the JWT token in the Authorization header of the request -- in essence, using the bot's own credentials to authenticate the request.

Si está implementando una biblioteca de autenticación y desea aceptar solicitudes desde el emulador de Bot Framework, debe agregar esta ruta de acceso de comprobación adicional.If you are implementing an authentication library and want to accept requests from the Bot Framework Emulator, you must add this additional verification path. La ruta de acceso es estructuralmente similar a la ruta de verificación del bot Connector ->, pero usa el documento OpenID de MSA en lugar del documento OpenID de Bot Connector.The path is structurally similar to the Connector -> Bot verification path, but it uses MSA's OpenID document instead of the Bot Connector's OpenID document.

En este diagrama se muestran los pasos para la autenticación de emulador a bot:This diagram shows the steps for Emulator-to-bot authentication:

Autenticación de las llamadas del emulador de Bot Framework al bot


Paso 2: Obtención del documento de metadatos de OpenID de MSAStep 2: Get the MSA OpenID metadata document

El documento de metadatos de OpenID especifica la ubicación de un segundo documento que enumera las claves de firma válidas.The OpenID metadata document specifies the location of a second document that lists the valid signing keys. Para obtener el documento de metadatos de OpenID de MSA, emita esta solicitud mediante HTTPS:To get the MSA OpenID metadata document, issue this request via HTTPS:

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

El ejemplo siguiente muestra un documento de metadatos de OpenID devuelto en respuesta a la solicitud GET.The following example shows an OpenID metadata document that is returned in response to the GET request. La propiedad jwks_uri especifica la ubicación del documento que contiene las claves de firma válidas.The jwks_uri property specifies the location of the document that contains the valid signing keys.

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

Paso 3: Obtención de la lista de claves de firma válidasStep 3: Get the list of valid signing keys

Para obtener la lista de claves de firma válidas, emita una solicitud GET mediante HTTPS a la dirección URL especificada por la propiedad jwks_uri en el documento de metadatos de OpenID.To get the list of valid signing keys, issue a GET request via HTTPS to the URL specified by the jwks_uri property in the OpenID metadata document. Por ejemplo:For example:

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

El cuerpo de la respuesta especifica el documento en formato JWK.The response body specifies the document in the JWK format.

Paso 4: Verificación del token JWTStep 4: Verify the JWT token

Para comprobar la autenticidad del token enviado por el emulador, debe extraer el token del encabezado de la solicitud, analizar el token, comprobar su contenido y comprobar su Authorization firma.To verify the authenticity of the token that was sent by the Emulator, you must extract the token from the Authorization header of the request, parse the token, verify its contents, and verify its signature.

Hay disponibles bibliotecas de análisis de JWT para muchas plataformas y la mayoría implementa un análisis de los tokens JWT seguro y confiable, aunque normalmente deberá configurar estas bibliotecas para requerir que determinadas características del token (su emisor, audiencia, etc.) contengan valores correctos.JWT parsing libraries are available for many platforms and most implement secure and reliable parsing for JWT tokens, although you must typically configure these libraries to require that certain characteristics of the token (its issuer, audience, etc.) contain correct values. Al analizar el token, debe configurar la biblioteca de análisis o escribir su propia validación para asegurarse de que el token cumple estos requisitos:When parsing the token, you must configure the parsing library or write your own validation to ensure the token meets these requirements:

  1. El token se ha enviado en el encabezado HTTP Authorization con un esquema "Bearer" (Portador).The token was sent in the HTTP Authorization header with "Bearer" scheme.
  2. El token tiene un formato JSON válido que se ajusta al estándar JWT.The token is valid JSON that conforms to the JWT standard.
  3. El token contiene una notificación de "emisor" con uno de los valores resaltados para los casos no gubernamentales.The token contains an "issuer" claim with one of the highlighted values for non governmental cases. La comprobación de ambos valores de emisor garantizará que está comprobando los valores de emisor del protocolo de seguridad v3.1 y v3.2.Checking for both issuer values will ensure you are checking for both the security protocol v3.1 and v3.2 issuer values.
  4. El token contiene una notificación "audience" (audiencia) con un valor igual al identificador de aplicación de Microsoft del bot.The token contains an "audience" claim with a value equal to the bot's Microsoft App ID.
  5. El emulador, dependiendo de la versión, envía el AppId a través de la notificación appid (versión 1) o la notificación de entidad autorizada (versión 2).The Emulator, depending on the version, sends the AppId via either the appid claim (version 1) or the authorized party claim (version 2).
  6. El token está dentro de su período de validez.The token is within its validity period. El tiempo estándar del sector es de 5 minutos.Industry-standard clock-skew is 5 minutes.
  7. El token tiene una firma criptográfica válida con una clave enumerada en el documento de claves de OpenID que se recuperó en el paso 3.The token has a valid cryptographic signature with a key listed in the OpenID keys document that was retrieved in Step 3.

Nota

El requisito 5 es específico de la ruta de verificación del emulador.Requirement 5 is a specific to the Emulator verification path.

Si el token no cumple todos estos requisitos, el bot debe finalizar la solicitud devolviendo un código de estado HTTP 403 (prohibido) .If the token does not meet all of these requirements, your bot should terminate the request by returning an HTTP 403 (Forbidden) status code.

Importante

Todos estos requisitos son importantes, especialmente los requisitos 4 y 7.All of these requirements are important, particularly requirements 4 and 7. En caso de no implementarse todos estos requisitos de comprobación, se dejaría el bot abierto a ataques que podrían provocar que el bot divulgue su token JWT.Failure to implement ALL of these verification requirements will leave the bot open to attacks which could cause the bot to divulge its JWT token.

Emulador a bot: componentes JWT de ejemploEmulator to Bot: example JWT components

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
}

Nota

Los campos reales pueden variar en la práctica.Actual fields may vary in practice. Debe crear y validar todos los tokens JWT según lo especificado anteriormente.Create and validate all JWT tokens as specified above.

Cambios del protocolo de seguridadSecurity protocol changes

Advertencia

La compatibilidad con la versión v3.0 del protocolo de seguridad se interrumpió el 31 de julio de 2017.Support for v3.0 of the security protocol was discontinued on July 31, 2017. Si ha escrito su propio código de autenticación (es decir, no ha usado Bot Framework SDK para crear el bot), debe actualizar a la versión v3.1 del protocolo de seguridad mediante la actualización de la aplicación para que utilice los valores de la versión v3.1 que se enumeran a continuación.If you have written your own authentication code (i.e., did not use the Bot Framework SDK to create your bot), you must upgrade to v3.1 of the security protocol by updating your application to use the v3.1 values that are listed below.

Autenticación bot a ConnectorBot to Connector authentication

Dirección URL de inicio de sesión de OAuthOAuth login URL

Versión del protocoloProtocol version Valor válidoValid value
v3.1 y v3.2v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

Ámbito de OAuthOAuth scope

Versión del protocoloProtocol version Valor válidoValid value
v3.1 y v3.2v3.1 & v3.2 https://api.botframework.com/.default

Autenticación de Connector a botConnector to Bot authentication

Documento de metadatos de OpenIDOpenID metadata document

Versión del protocoloProtocol version Valor válidoValid value
v3.1 y v3.2v3.1 & v3.2 https://login.botframework.com/v1/.well-known/openidconfiguration

Emisor de JWTJWT Issuer

Versión del protocoloProtocol version Valor válidoValid value
v3.1 y v3.2v3.1 & v3.2 https://api.botframework.com

Autenticación de emulador a botEmulator to Bot authentication

Dirección URL de inicio de sesión de OAuthOAuth login URL

Versión del protocoloProtocol version Valor válidoValid value
v3.1 y v3.2v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

Ámbito de OAuthOAuth scope

Versión del protocoloProtocol version Valor válidoValid value
v3.1 y v3.2v3.1 & v3.2 Identificador de aplicación de Microsoft del bot + /.defaultYour bot's Microsoft App ID + /.default

Audiencia de JWTJWT Audience

Versión del protocoloProtocol version Valor válidoValid value
v3.1 y v3.2v3.1 & v3.2 Identificador de aplicación de Microsoft del botYour bot's Microsoft App ID

Emisor de JWTJWT Issuer

Versión del protocoloProtocol version Valor válidoValid value
v3.1 1.0v3.1 1.0 https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/
v3.1 2.0v3.1 2.0 https://login.microsoftonline.com/d6d49420-f39b-4df7-a1dc-d59a935871db/v2.0
v3.2 1.0v3.2 1.0 https://sts.windows.net/f8cdef31-a31e-4b4a-93e4-5f571e91255a/
v3.2 2.0v3.2 2.0 https://login.microsoftonline.com/f8cdef31-a31e-4b4a-93e4-5f571e91255a/v2.0

Consulte también los valores resaltados para casos no gubernamentales.See also the highlighted values for non governmental cases.

Documento de metadatos de OpenIDOpenID metadata document

Versión del protocoloProtocol version Valor válidoValid value
v3.1 y v3.2v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

Recursos adicionalesAdditional resources