Autenticación con Bot Connector API

El bot se comunica con el servicio Bot Connector mediante HTTP a través de un canal protegido (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 de autenticación para la autenticación de nivel de servicio que tiene lugar entre un bot y el servicio Bot Connector. Si va a escribir su propio código de autenticación, debe implementar los procedimientos de seguridad descritos en este artículo para permitir que el bot intercambie mensajes con el servicio Bot Connector.

Si usa Bot Framework SDK, no es necesario implementar los procedimientos de seguridad descritos en este artículo, ya que el SDK lo hace automáticamente. Solo tiene que 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 usan cuatro tecnologías de autenticación para establecer la confianza entre un bot y Bot Connector:

En este artículo se describe cómo usar estas tecnologías a través de HTTPS estándar y JSON. No se requieren SDK especiales, aunque es posible que los asistentes para OpenID y otros sean útiles.

Autenticación de solicitudes del bot en el servicio Bot Connector

Para comunicarse con el servicio Bot Connector, debe especificar un token de acceso en el Authorization encabezado de cada solicitud de API mediante 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: Solicitar un token de acceso desde el servicio de inicio de sesión de la cuenta de Microsoft Entra ID

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

• Usar una identidad administrada asignada por el usuario para no tener que administrar las credenciales del bot.
• 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.

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

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

Si el servicio de inicio de sesión autoriza la aplicación, el cuerpo de la respuesta JSON especificará el token de acceso, su tipo y su expiración (en segundos).

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

En este ejemplo se muestra una respuesta del servicio de inicio de sesión de la 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: Especificar el token JWT en el encabezado de autorización de las solicitudes

Al enviar una solicitud de API al servicio Bot Connector, especifique el token de acceso en el Authorization encabezado 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 Authorization encabezado. Si el token tiene el formato correcto, no ha expirado y lo generó el servicio de inicio de sesión de la 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.

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

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

(JSON-serialized Activity message goes here)

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

Autenticación de solicitudes del servicio Bot Connector en el bot

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

Para autenticar 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 del 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: Obtener el 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 a través de HTTPS:

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

En el ejemplo siguiente se muestra un documento de metadatos de OpenID que se devuelve en respuesta a la GET solicitud. La jwks_uri propiedad 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: Obtener la lista de claves de firma válidas

Para obtener la lista de claves de firma válidas, emita una GET solicitud a través de HTTPS a la dirección URL especificada por la jwks_uri propiedad 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.

La endorsements propiedad de cada clave contiene una o varias cadenas de aprobación que puede usar para comprobar que el identificador de canal especificado en la channelId propiedad dentro del objeto Activity de la solicitud entrante es auténtico. La lista de identificadores de canal que requieren aprobaciones se puede configurar dentro de 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 de cualquier manera.

Paso 4: Comprobación del token JWT

Para comprobar la autenticidad del token enviado por el servicio Bot Connector, debe extraer el token del Authorization encabezado de la solicitud, analizar el token, comprobar su contenido y comprobar su firma.

Las bibliotecas de análisis de JWT están disponibles para muchas plataformas y la mayoría implementan análisis seguro y confiable para tokens JWT, aunque normalmente debe configurar estas bibliotecas para requerir que ciertas 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 envió en la cabecera HTTP Authorization con el esquema «Bearer».
2. El token es JSON válido que se ajusta al estándar JWT.
3. El token contiene una declaración "issuer" con el valor de https://api.botframework.com.
4. El token contiene una declaración "audience" con un valor igual al Microsoft App ID del bot.
5. El token está dentro de su período de validez. El desfase de reloj 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 openID que se recuperó en el paso 3, mediante el algoritmo de firma especificado en la id_token_signing_alg_values_supported propiedad del documento de metadatos de Open ID que se recuperó en el paso 2.
7. El token contiene una declaración "serviceUrl" 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 Activity objeto enviado al bot con ese identificador de canal esté 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).

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

Conector a bot: componentes de 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
}

Autentique las solicitudes del Emulador de Bot Framework a su bot

Bot Framework Emulator es una herramienta de escritorio que puede usar para probar la funcionalidad del bot. Aunque Bot Framework Emulator usa las mismas tecnologías de autenticación que se describió anteriormente, no puede suplantar al servicio Bot Connector real. En su lugar, usa el identificador de aplicación de Microsoft y Microsoft contraseña de aplicación que especifique al conectar el emulador al bot para crear tokens idénticos a los que crea el bot. Cuando el emulador envía una solicitud al bot, especifica el token JWT en el Authorization encabezado de la solicitud, en esencia, mediante las propias credenciales del bot para autenticar la solicitud.

Si va a implementar una biblioteca de autenticación y desea aceptar solicitudes de Bot Framework Emulator, debe agregar esta ruta de verificación adicional. La ruta es estructuralmente similar a la ruta de verificación de Connector -> Bot, pero utiliza el documento OpenID de MSA en lugar del documento OpenID de Bot Connector.

Para autenticar llamadas desde Bot Framework Emulator:

1. El bot obtiene el token JWT del encabezado de autorización en las solicitudes enviadas desde el Bot Framework Emulator.
2. El bot obtiene el documento de metadatos de OpenID del 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: Obtener el 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 a través de HTTPS:

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

En el ejemplo siguiente se muestra un documento de metadatos de OpenID que se devuelve en respuesta a la GET solicitud. La jwks_uri propiedad 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: Obtener la lista de claves de firma válidas

Para obtener la lista de claves de firma válidas, emita una GET solicitud a través de HTTPS a la dirección URL especificada por la jwks_uri propiedad 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: Comprobación del token JWT

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

Las bibliotecas de análisis de JWT están disponibles para muchas plataformas y la mayoría implementan análisis seguro y confiable para tokens JWT, aunque normalmente debe configurar estas bibliotecas para requerir que ciertas 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 envió en la cabecera HTTP Authorization con el esquema «Bearer».
2. El token es JSON válido que se ajusta al estándar JWT.
3. El token contiene una declaración del emisor para el protocolo de seguridad correspondiente. Para obtener la implementación actual, consulte Microsoft. Agents.Connector.
4. El token contiene una declaración "audience" con un valor igual al Microsoft App ID 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 desfase de reloj estándar del sector es de 5 minutos.
7. El token tiene una firma criptográfica válida con una clave que aparece en el documento claves openID que se recuperó en el paso 3.

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

Emulador para bot: componentes de 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
}

Cambios en el protocolo de seguridad

Autenticación del bot con el conector

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

Ámbito de OAuth

Conector a autenticación de bot

Documento de metadatos de OpenID

Emisor de JWT

Autenticación de emulador a bot

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

Ámbito de OAuth

Audiencia de JWT

Emisor de JWT

Para obtener la implementación actual, consulte Microsoft. Agents.Connector.

Documento de metadatos de OpenID

Recursos adicionales

• Solución de problemas de autenticación de Bot Framework
• Especificación del protocolo de actividad
• Referencia de la API restConnectorClient
• JSON Web Token (JWT) draft-jones-json-web-token-07
• Firma Web JSON (JWS) draft-jones-json-web-signature-04
• JSON Web Key (JWK) RFC 7517