Autenticación en la API de línea directa 1,1Authentication in Direct Line API 1.1

Importante

En este artículo se describe la autenticación en Direct Line API 1.1.This article describes authentication in Direct Line API 1.1. Si va a crear una nueva conexión entre la aplicación cliente y el bot, use Direct Line API 3.0 en su lugar.If you are creating a new connection between your client application and bot, use Direct Line API 3.0 instead.

Un cliente puede autenticar solicitudes a Direct Line API 1.1 mediante un secreto que se obtiene de la página de configuración del canal de Direct Line en el portal de Bot Framework o mediante un token que se obtiene en tiempo de ejecución.A client can authenticate requests to Direct Line API 1.1 either by using a secret that you obtain from the Direct Line channel configuration page in the Bot Framework Portal or by using a token that you obtain at runtime.

El secreto o token debe especificarse en el encabezado Authorization de cada solicitud, mediante los esquemas "Bearer" o "BotConnector".The secret or token should be specified in the Authorization header of each request, using either the "Bearer" scheme or the "BotConnector" scheme.

Esquema Bearer:Bearer scheme:

Authorization: Bearer SECRET_OR_TOKEN

Esquema BotConnector:BotConnector scheme:

Authorization: BotConnector SECRET_OR_TOKEN

Secretos y tokensSecrets and tokens

Un secreto de Direct Line es una clave maestra que se puede usar para acceder a cualquier conversación que pertenezca al bot asociado.A Direct Line secret is a master key that can be used to access any conversation that belongs to the associated bot. Un secreto se puede usar también para obtener un token.A secret can also be used to obtain a token. Los secretos no expiran.Secrets do not expire.

Un token de Direct Line es una clave que se puede usar para acceder a una única conversación.A Direct Line token is a key that can be used to access a single conversation. Un token expira, pero se puede actualizar.A token expires but can be refreshed.

Si va a crear una aplicación de servicio a servicio, puede que el enfoque más sencillo sea especificar el secreto en el encabezado Authorization de las solicitudes de Direct Line API.If you're creating a service-to-service application, specifying the secret in the Authorization header of Direct Line API requests may be simplest approach. Si va a escribir una aplicación en la que el cliente se ejecuta en un explorador web o una aplicación móvil, puede que quiera intercambiar el secreto por un token (que solo sirve para una única conversación y expira a menos que se actualice) y especificar el token en el encabezado Authorization de las solicitudes de Direct Line API.If you're writing an application where the client runs in a web browser or mobile app, you may want to exchange your secret for a token (which only works for a single conversation and will expire unless refreshed) and specify the token in the Authorization header of Direct Line API requests. Elija el modelo de seguridad que mejor funcione en su caso.Choose the security model that works best for you.

Nota

Las credenciales de cliente de Direct Line son diferentes de las credenciales del bot.Your Direct Line client credentials are different from your bot's credentials. Esto le permite revisar las claves de forma independiente y compartir los tokens de cliente sin revelar la contraseña del bot.This enables you to revise your keys independently and lets you share client tokens without disclosing your bot's password.

Obtención de un secreto de Direct LineGet a Direct Line secret

Se puede obtener un secreto de Direct Line en la página de configuración del canal Direct Line de su bot en Azure Portal:You can obtain a Direct Line secret via the Direct Line channel configuration page for your bot in the Azure Portal:

Configuración de Direct Line

Generación de un token de Direct LineGenerate a Direct Line token

Para generar un token de Direct Line que pueda usarse para acceder a una única conversación, primero obtenga el secreto de Direct Line de la página de configuración del canal Direct Line en Azure Portal.To generate a Direct Line token that can be used to access a single conversation, first obtain the Direct Line secret from the Direct Line channel configuration page in the Azure Portal. A continuación, emita esta solicitud para intercambiar el secreto de Direct Line por un token de Direct Line:Then issue this request to exchange your Direct Line secret for a Direct Line token:

POST https://directline.botframework.com/api/tokens/conversation
Authorization: Bearer SECRET

En el encabezado Authorization de esta solicitud, reemplace SECRET por el valor del secreto de Direct Line.In the Authorization header of this request, replace SECRET with the value of your Direct Line secret.

Los fragmentos de código siguientes proporcionan un ejemplo de la solicitud y respuesta de Generar un token.The following snippets provide an example of the Generate Token request and response.

SolicitudRequest

POST https://directline.botframework.com/api/tokens/conversation
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0

ResponseResponse

Si la solicitud es correcta, la respuesta contiene un token válido para una conversación.If the request is successful, the response contains a token that is valid for one conversation. El token expira en 30 minutos.The token will expire in 30 minutes. Para que el token siga siendo útil, debe actualizarlo antes de que expire.For the token to remain useful, you must refresh the token before it expires.

HTTP/1.1 200 OK
[other headers]

"RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn"

Generar token frente a Iniciar conversaciónGenerate Token versus Start Conversation

La operación Generar token (POST /api/tokens/conversation) es parecida a la operación Iniciar conversación (POST /api/conversations) en el sentido de que ambas operaciones devuelven un token que se puede usar para acceder a una única conversación.The Generate Token operation (POST /api/tokens/conversation) is similar to the Start Conversation operation (POST /api/conversations) in that both operations return a token that can be used to access a single conversation. Sin embargo, a diferencia de la operación Iniciar conversación, la operación Generar token no inicia la conversación o el contacto con el bot.However, unlike the Start Conversation operation, the Generate Token operation does not start the conversation or contact the bot.

Si va a distribuir el token a los clientes y quiere que inicien la conversación, use la operación Generar token.If you plan to distribute the token to clients and want them to initiate the conversation, use the Generate Token operation. Si tiene previsto iniciar inmediatamente la conversación, use en su lugar la operación Iniciar conversación.If you intend to start the conversation immediately, use the Start Conversation operation instead.

Actualización de un token de Direct LineRefresh a Direct Line token

Un token de Direct Line es válido durante 30 minutos desde el momento en que se genera y se puede actualizar una cantidad ilimitada de veces, siempre y cuando no haya expirado.A Direct Line token is valid for 30 minutes from the time it is generated and can be refreshed an unlimited amount of times, as long as it has not expired. No se puede actualizar un token expirado.An expired token cannot be refreshed. Para actualizar un token de Direct Line, emita esta solicitud:To refresh a Direct Line token, issue this request:

POST https://directline.botframework.com/api/tokens/{conversationId}/renew
Authorization: Bearer TOKEN_TO_BE_REFRESHED

En el URI de esta solicitud, reemplace {conversationId} por el identificador de la conversación para la que el token es válido, y en el encabezado Authorization de esta solicitud, reemplace TOKEN_TO_BE_REFRESHED por el token de Direct Line que quiere actualizar.In the URI of this request, replace {conversationId} with the ID of the conversation for which the token is valid and in the Authorization header of this request, replace TOKEN_TO_BE_REFRESHED with the Direct Line token that you want to refresh.

Los fragmentos de código siguientes proporcionan un ejemplo de la solicitud y respuesta de Actualizar token.The following snippets provide an example of the Refresh Token request and response.

SolicitudRequest

POST https://directline.botframework.com/api/tokens/abc123/renew
Authorization: Bearer CurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

ResponseResponse

Si la solicitud es correcta, la respuesta contiene un nuevo token que es válido para la misma conversación que el token anterior.If the request is successful, the response contains a new token that is valid for the same conversation as the previous token. El token nuevo expirará en 30 minutos.The new token will expire in 30 minutes. Para que el nuevo token siga siendo útil, debe actualizarlo antes de que expire.For the new token to remain useful, you must refresh the token before it expires.

HTTP/1.1 200 OK
[other headers]

"RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0"

Recursos adicionalesAdditional resources