Autenticación con la API Bot Connector

El bot se comunica con el servicio Bot Connector con HTTP mediante un canal seguro (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. 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. 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. 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.

Importante

Si está escribiendo su propio código de autenticación, es fundamental que aplique correctamente todos los procedimientos de seguridad. 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.

Si usa el SDK Bot Framework, no es necesario implementar los procedimientos de seguridad descritos en este artículo, que el SDK lo hace automáticamente. 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.

Tecnologías de autenticación

Se utilizan cuatro tecnologías de autenticación para establecer la confianza entre un bot y Bot Connector:

Technology	Descripción
SSL/TLS	Se usa SSL/TLS para todas las conexiones de servicio a servicio. Se utilizan certificadosX.509v3 para establecer la identidad de todos los servicios HTTPS. Los clientes siempre deben inspeccionar los certificados del servicio para asegurarse de que son válidos y de confianza. (No se usan certificados de cliente como parte de este esquema).
OAuth 2.0	OAuth 2.0 utiliza el servicio de inicio de sesión de cuenta de Microsoft Entra ID para generar un token seguro que un bot puede utilizar para enviar mensajes. Este token es un token de servicio a servicio, no es necesario ningún inicio de sesión de usuario.
JSON Web Token (JWT)	Los JSON Web Token se usan para codificar los tokens que se envían hacia y desde el bot. Los clientes deben comprobar completamente todos los tokens JWT que reciben, según los requisitos descritos en este artículo.
Metadatos de OpenID	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.

En este artículo se describe cómo usar estas tecnologías mediante HTTPS y JSON estándar. No es necesario ningún SDK especial, aunque es posible que los asistentes para OpenID y otros le sean útiles.

Autenticación de las solicitudes del bot al servicio Bot Connector

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:

Authorization: Bearer ACCESS_TOKEN

Para obtener y usar un token JWT para el bot:

1. El bot envía una solicitud HTTP GET al servicio de inicio de sesión de MSA.
2. La respuesta del servicio contiene el token JWT que se va a usar.
3. El bot incluye este token JWT en el encabezado de autorización en las solicitudes al servicio Bot Connector.

Paso 1: Solicitud de un token de acceso desde el servicio de inicio de sesión de la cuenta de Microsoft Entra ID

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. Necesita el identificador de la aplicación del bot y la contraseña para solicitar un token de acceso.

La identidad del bot se puede administrar de varias maneras diferentes en Azure.

• Como identidad administrada asignada por el usuario, por lo que no es necesario administrar las credenciales del bot usted mismo.
• Como una aplicación de un inquilino único.
• Como una aplicación multiinquilino.

Solicite un token de acceso basado en el tipo de aplicación del bot.

Multiinquilino

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 Servicio de 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

Inquilino único

Para solicitar un token de acceso al servicio de inicio de sesión, emita la siguiente solicitud y reemplace MICROSOFT-APP-ID, MICROSOFT-APP-PASSWORD y MICROSOFT-TENANT-ID por el identificador de aplicación del bot y la contraseña que obtuvo cuando registró el bot en Servicio de 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

Identidad administrada asignada por el usuario

App Service y Azure Functions proporcionan un punto de conexión REST accesible internamente para la recuperación de tokens. Para solicitar un token de acceso desde el punto de conexión MSI/token, realice una solicitud GET al punto de conexión. Use los parámetros de consulta resource y client_id. Establezca resource en https://api.botframework.com y client_id en el identificador de aplicación de identidad administrada del bot. La solicitud no requiere otros parámetros de consulta.

• Para más información sobre el punto de conexión de token, consulte Conectar a los servicios de Azure en el código de la aplicación.
• Para más información sobre los identificadores de aplicación de bot, consulte Creación de un recurso de Azure Bot.

Paso 2: Obtención del token JWT de la respuesta del servicio de inicio de sesión de la cuenta de Microsoft Entra ID

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

Al agregar el token al encabezado Authorization de una solicitud, debe usar el valor exacto especificado en esta respuesta, sin escape ni codificación del valor del token. El token de acceso es válido hasta su expiración. Para evitar que expire el token y afecte al rendimiento del bot, puede almacenarlo en caché y actualizar el token de forma proactiva.

En este ejemplo se muestra una respuesta del servicio de inicio de sesión de cuenta de Microsoft Entra ID:

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 solicitudes

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:

Authorization: Bearer ACCESS_TOKEN

Todas las solicitudes que envíe al servicio Bot Connector deben incluir el token de acceso en el encabezado Authorization. Si el token tiene un formato correcto, no ha expirado y fue generado por el servicio de inicio de sesión de cuenta de Microsoft Entra ID, el servicio Bot Connector autorizará la solicitud. Se realizan comprobaciones adicionales para asegurarse de que el token pertenece al bot que envió la solicitud.

El ejemplo siguiente muestra cómo especificar el token de acceso en el encabezado Authorization de la solicitud.

POST https://smba.trafficmanager.net/teams/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. No envíe el token por canales no seguros y no lo incluya en las solicitudes HTTP que se envían a otros servicios. El token JWT que obtiene del servicio de inicio de sesión de cuenta de Microsoft Entra ID es como una contraseña y debe utilizarse con mucho cuidado. Cualquiera que tenga el token puede usarlo para realizar operaciones en nombre del bot.

Bot a Connector: componentes JWT de ejemplo

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. Debe crear y validar todos los tokens JWT según lo especificado anteriormente.

Autenticación de las solicitudes del servicio Bot Connector al bot

Cuando el servicio Bot Connector envía una solicitud al bot, especifica un token JWT firmado en el encabezado Authorization de la solicitud. El bot puede autenticar las llamadas desde el servicio Bot Connector al verificar la autenticidad del token JWT firmado.

Para autenticar las llamadas desde el servicio Bot Connector:

1. El bot obtiene el token JWT del encabezado de autorización en las solicitudes enviadas desde el servicio Bot Connector.
2. El bot obtiene el documento de metadatos de OpenID para el servicio Bot Connector.
3. El bot obtiene la lista de claves de firma válidas del documento.
4. El bot comprueba la autenticidad del token JWT.

Paso 2: Obtención del documento de metadatos de OpenID

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. Para obtener el documento de metadatos de OpenID, emita esta solicitud mediante 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.

El ejemplo siguiente muestra un documento de metadatos de OpenID devuelto en respuesta a la solicitud GET. La propiedad jwks_uri especifica la ubicación del documento que contiene las claves de firma válidas del servicio 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"
    ]
}

Paso 3: Obtención de la lista de claves de firma válidas

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. Por ejemplo:

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.

Sugerencia

La lista de claves es estable y se puede almacenar en caché, pero se pueden agregar claves nuevas en cualquier momento. Para asegurarse de que el bot tiene una copia actualizada del documento antes de usar estas claves, todas las instancias de bot deben actualizar su caché local del documento al menos una vez cada 24 horas.

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 Activity de la solicitud entrante es auténtico. La lista de identificadores de canal que requieren aprobaciones es configurable en cada 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.

Paso 4: Verificación del token JWT

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.

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

1. El token se ha enviado en el encabezado HTTP Authorization con un esquema "Bearer" (Portador).
2. El token tiene un formato JSON válido que se ajusta al estándar JWT.
3. El token contiene una notificación "issuer" (emisor) con el valor 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.
5. El token está dentro de su período de validez. El tiempo estándar del sector es de 5 minutos.
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.
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 Activity de la solicitud entrante.

Si se requiere aprobación para un identificador de canal:

• 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.
• Si la aprobación no está presente, el bot debe rechazar la solicitud devolviendo un código de estado HTTP 403 (prohibido).

Importante

Todos estos requisitos son importantes, especialmente los requisitos 4 y 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.

Los implementadores no deben exponer una manera de deshabilitar la validación del token JWT que se envía al bot.

Connector a bot: componentes JWT de ejemplo

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. Debe crear y validar todos los tokens JWT según lo especificado anteriormente.

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

El Emulador de Bot Framework es una herramienta de escritorio que puede usar para probar la funcionalidad del 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. 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 que son idénticos a los que crea el bot. Cuando el emulador envía una solicitud al bot, especifica el token JWT en el encabezado Authorization de la solicitud: en esencia, utiliza las propias credenciales del bot para autenticar la solicitud.

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. La ruta de acceso es estructuralmente similar a la ruta de acceso de comprobación Connector -> Bot, pero usa el documento de OpenID de MSA en lugar del documento de OpenID de Bot Connector.

Para autenticar las llamadas del emulador de Bot Framework Emulator:

1. El bot obtiene el token JWT del encabezado de autorización en las solicitudes enviadas desde Bot Framework Emulator.
2. El bot obtiene el documento de metadatos de OpenID para el servicio Bot Connector.
3. El bot obtiene la lista de claves de firma válidas del documento.
4. El bot comprueba la autenticidad del token JWT.

---

Paso 2: Obtención del documento de metadatos de OpenID de MSA

El documento de metadatos de OpenID especifica la ubicación de un segundo documento que enumera las claves de firma válidas. Para obtener el documento de metadatos de OpenID de MSA, emita esta solicitud mediante 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. La propiedad jwks_uri especifica la ubicación del documento que contiene las claves de firma válidas.

{
    "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álidas

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. Por ejemplo:

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.

Paso 4: Verificación del token JWT

Para verificar la autenticidad del token enviado por el emulador, debe extraer el token del encabezado Authorization de la solicitud, analizar el token, verificar su contenido y verificar su firma.

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

1. El token se ha enviado en el encabezado HTTP Authorization con un esquema "Bearer" (Portador).
2. El token tiene un formato JSON válido que se ajusta al estándar JWT.
3. El token contiene una notificación de "emisor" con uno de los valores resaltados para casos no gubernamentales. La comprobación de ambos valores de emisor garantizará que está comprobando tanto los valores de emisor del protocolo de seguridad v3.1 como los del v3.2.
4. El token contiene una notificación "audience" (audiencia) con un valor igual al identificador de aplicación de Microsoft del bot.
5. El emulador, en función 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).
6. El token está dentro de su período de validez. El tiempo estándar del sector es de 5 minutos.
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.

Nota:

El requisito 5 es específico para la ruta de acceso de comprobación del emulador.

Si el token no cumple todos estos requisitos, el bot debe finalizar la solicitud devolviendo un código de estado HTTP 403 (prohibido).

Importante

Todos estos requisitos son importantes, especialmente los requisitos 4 y 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.

Emulador a bot: componentes JWT de ejemplo

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. Debe crear y validar todos los tokens JWT según lo especificado anteriormente.

Cambios del protocolo de seguridad

Autenticación bot a Connector

Dirección URL de inicio de sesión de OAuth

Versión del protocolo	Valor válido
v3.1 y v3.2	https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

Ámbito de OAuth

Versión del protocolo	Valor válido
v3.1 y v3.2	https://api.botframework.com/.default

Autenticación de Connector a bot

Documento de metadatos de OpenID

Versión del protocolo	Valor válido
v3.1 y v3.2	https://login.botframework.com/v1/.well-known/openidconfiguration

Emisor de JWT

Versión del protocolo	Valor válido
v3.1 y v3.2	https://api.botframework.com

Autenticación de emulador a bot

Dirección URL de inicio de sesión de OAuth

Versión del protocolo	Valor válido
v3.1 y v3.2	https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

Ámbito de OAuth

Versión del protocolo	Valor válido
v3.1 y v3.2	Identificador de aplicación de Microsoft del bot + /.default

Audiencia de JWT

Versión del protocolo	Valor válido
v3.1 y v3.2	Identificador de aplicación de Microsoft del bot

Emisor de JWT

Versión del protocolo	Valor válido
v3.1 1.0	https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/
v3.1 2.0	https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/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

Vea también los valores resaltados para casos no gubernamentales.

Documento de metadatos de OpenID

Versión del protocolo	Valor válido
v3.1 y v3.2	https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

Recursos adicionales

• Solución de problemas de autenticación de Bot Framework
• Esquema Activity de Bot Framework
• JSON Web Token (JWT) draft-jones-json-web-token-07
• Firma web JSON (JWS) draft-jones-json-web-signature-04
• Clave web JSON (JWK) RFC 7517