Autenticación en la API de línea directa 3,0Authentication in Direct Line API 3.0

Un cliente puede autenticar solicitudes en Direct Line API 3.0 ya sea 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 el tiempo de ejecución.A client can authenticate requests to Direct Line API 3.0 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, con este formato:The secret or token should be specified in the Authorization header of each request, using this format:

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

La decisión sobre si usar la clave secreta o un token y sobre cuándo utilizarla debe basarse en aspectos de seguridad.Deciding when or if to use the secret key or a token must be based on security considerations. Se podría aceptar la exposición de la clave secreta si se realiza intencionadamente y con cuidado.Exposing the secret key could be acceptable if done intentionally and with care. De hecho, este es el comportamiento predeterminado, ya que permite que Direct Line averigüe si el cliente es legítimo.As matter of a fact, this is the default behavior because this allows Direct Line to figure out if the client is legitimate. En términos generales, la seguridad es un problema si intenta conservar los datos de usuario.Generally speaking though, security is a concern if you're trying to persist user data. Para más información, consulte la sección Consideraciones sobre la seguridad.For more information, see section Security considerations.

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/v3/directline/tokens/generate
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/v3/directline/tokens/generate
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0

La carga de la solicitud, que contiene los parámetros del token, es opcional pero recomendable.The request payload, which contains the token parameters, is optional but recommended. Cuando se genera un token que se puede enviar al servicio Direct Line, proporcione la siguiente carga para hacer más segura la conexión.When generating a token that can be sent back to the Direct Line service, provide the following payload to make the connection more secure. Al incluir estos valores, Direct Line puede realizar validaciones adicionales de la seguridad del identificador y el nombre de usuario, e impedir que clientes malintencionados manipulen estos valores.By including these values, Direct Line can perform additional security validation of the user ID and name, inhibiting tampering of these values by malicious clients. Con estos valores también mejora la capacidad de Direct Line de enviar la actividad actualización de la conversación, lo que le permite generar la actualización de la conversación inmediatamente cuando el usuario se une a la conversación.Including these values also improves Direct Line's ability to send the conversation update activity, allowing it to generate the conversation update immediately upon the user joining the conversation. Cuando no se proporciona esta información, el usuario debe enviar contenido para que Direct Line pueda enviar la actualización de la conversación.When this information is not provided, the user must send content before Direct Line can send the conversation update.

{
  "user": {
    "id": "string",
    "name": "string"
  },
  "trustedOrigins": [
    "string"
  ]
}
ParámetroParameter TipoType DescripciónDescription
user.id stringstring Opcional.Optional. Identificador de usuario específico del canal para su codificación dentro del token.Channel-specific ID of the user to encode within the token. Para un usuario de Direct Line, debe comenzar con dl_.For a Direct Line user, this must begin with dl_. Puede crear un identificador de usuario único para cada conversación y, para mejorar la seguridad, no se debería poder averiguar este identificador.You can create a unique user ID for each conversation, and for better security, you should make this ID unguessable.
user.name stringstring Opcional.Optional. Nombre para mostrar descriptivo del usuario para su codificación dentro del token.The display-friendly name of the user to encode within the token.
trustedOrigins matriz de cadenasstring array Opcional.Optional. Lista de dominios de confianza para insertar dentro del token.A list of trusted domains to embed within the token. Estos son los dominios que pueden hospedar el cliente de chat web del bot.These are the domains that can host the bot's Web Chat client. Debería coincidir con la lista de la página de configuración de Direct Line del bot.This should match the list in the Direct Line configuration page for your bot.

ResponseResponse

Si la solicitud es correcta, la respuesta contiene un token que es válido para una conversación y un valor expires_in que indica el número de segundos hasta que el token expira.If the request is successful, the response contains a token that is valid for one conversation and an expires_in value that indicates the number of seconds until the token expires. 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]
{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 1800
}

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

La operación Generar token (POST /v3/directline/tokens/generate) es parecida a la operación Iniciar conversación (POST /v3/directline/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 /v3/directline/tokens/generate) is similar to the Start Conversation operation (POST /v3/directline/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, y no crea una dirección URL de WebSocket de streaming.However, unlike the Start Conversation operation, the Generate Token operation does not start the conversation, does not contact the bot, and does not create a streaming WebSocket URL.

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 se puede actualizar una cantidad ilimitada de veces, siempre y cuando no haya expirado.A Direct Line token 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/v3/directline/tokens/refresh
Authorization: Bearer TOKEN_TO_BE_REFRESHED

En el encabezado Authorization de esta solicitud, reemplace TOKEN_TO_BE_REFRESHED por el token de Direct Line que quiere actualizar.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/v3/directline/tokens/refresh
Authorization: Bearer CurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

ResponseResponse

Si la solicitud tiene éxito, la respuesta contiene un nuevo token que es válido para la misma conversación que el token anterior, y un valor expires_in que indica el número de segundos hasta que expira el nuevo token.If the request is successful, the response contains a new token that is valid for the same conversation as the previous token and an expires_in value that indicates the number of seconds until the new token expires. 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]
{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0",
  "expires_in": 1800
}

Autenticación de Azure Bot ServiceAzure Bot Service authentication

La información que se presenta en esta sección se basa en el artículo Incorporación de autenticación al bot mediante Azure Bot Service.The information presented in this section is based on the Add authentication to your bot via Azure Bot Service article.

La autenticación de Azure Bot Service le permite autenticar usuarios y obtener tokens de acceso de diversos proveedores de identidades como Azure Active Directory, GitHub, Uber, etc.Azure Bot Service authentication enables you to authenticate users to and get access tokens from a variety of identity providers such as Azure Active Directory, GitHub, Uber and so on. También puede configurar la autenticación para un proveedor de identidades de OAuth2 personalizado.You can also configure authentication for a custom OAuth2 identity provider. Todo esto le permite escribir un fragmento de código de autenticación que funciona en todos los proveedores de identidades y canales admitidos.All this enables you to write one piece of authentication code that works across all supported identity providers and channels. Para utilizar estas funcionalidades debe realizar los siguientes pasos:To utilize these capabilities you need to perform the following steps:

  1. Configure settings de forma estática en el bot que contiene los detalles del registro de aplicación con un proveedor de identidades.Statically configure settings on your bot that contains the details of your application registration with an identity provider.
  2. Use un OAuthCard, con el respaldo de la información de la aplicación que proporcionó en el paso anterior, para iniciar sesión en un usuario.Use an OAuthCard, backed by the application information you supplied in the previous step, to sign-in a user.
  3. Recupere los tokens de acceso mediante la API de Azure Bot Service.Retrieve access tokens through Azure Bot Service API.

Consideraciones sobre la seguridadSecurity considerations

Cuando se usa la autenticación de Azure Bot Service con Web Chat hay algunos aspectos de seguridad importantes que debe tener en cuenta.When you use Azure Bot Service authentication with Web Chat there are some important security considerations you must keep in mind.

  1. Suplantación.Impersonation. La suplantación aquí significa que un atacante hace que el bot crea que es otra persona.Impersonation here means an attacker makes the bot thinks he is someone else. En Web Chat, un atacante puede suplantar a otra persona cambiando el identificador de usuario de su instancia de Web Chat.In Web Chat, an attacker can impersonate someone else by changing the user ID of his Web Chat instance. Para evitar esto, se recomienda a los desarrolladores de bots que hagan que el identificador de usuario no se pueda adivinar.To prevent this, it is recommend to bot developers to make the user ID unguessable.

    Si habilita las opciones de autenticación mejoradas, Azure Bot Service puede además detectar y rechazar cualquier cambio de identificador de usuario.If you enable enhanced authentication options, Azure Bot Service can further detect and reject any user ID change. Esto significa que en los mensajes de Direct Line al bot, el identificador de usuario (Activity.From.Id) siempre será igual al identificador con el que inicializó Web Chat.This means the user ID (Activity.From.Id) on messages from Direct Line to your bot will always be the same as the one you initialized the Web Chat with. Tenga en cuenta que esta característica requiere que el identificador de usuario empiece por dl_.Note that this feature requires the user ID starts with dl_.

    Nota

    Cuando se proporciona un valor de User.Id al intercambiar un secreto para un token, se inserta User.Id en el token.When a User.Id is provided while exchanging a secret for a token, that User.Id is embedded in the token. DirectLine se asegura de que los mensajes enviados al bot tengan ese identificador como valor de From.Id de la actividad. Si un cliente envía un mensaje a DirectLine con un valor de From.Id diferente, se cambiará por el identificador que hay en el token antes de reenviar el mensaje al bot.DirectLine makes sure the messages sent to the bot have that id as the activity's From.Id. If a client sends a message to DirectLine having a different From.Id, it will be changed to the Id in the token before forwarding the message to the bot. Por lo tanto, después de inicializar un secreto de canal con un identificador de usuario, no puede usar otro.So you cannot use another user id after a channel secret is initialized with a user id

  2. Identidades de usuario.User identities. Debe tener en cuenta que está tratando con dos identidades de usuario:You must be aware that your are dealing with two user identities:

    1. La identidad del usuario en un canal.The user's identity in a channel.
    2. La identidad del usuario en un proveedor de identidades en el que está interesado el bot.The user's identity in an identity provider that the bot is interested in.

    Cuando un bot solicita al usuario a en un canal para iniciar sesión en un proveedor de identidades P, el proceso de inicio de sesión debe asegurarse de que el usuario A es el que inicia sesión en P. Si otro usuario B puede iniciar sesión, el usuario a tendría acceso al recurso del usuario B a través del bot.When a bot asks user A in a channel to sign-in to an identity provider P, the sign-in process must assure that user A is the one that signs into P. If another user B is allowed to sign-in, then user A would have access to user B's resource through the bot. En Web Chat existen 2 mecanismos para asegurarse de que ha iniciado sesión el usuario correcto como se describe a continuación.In Web Chat we have 2 mechanisms for ensuring the right user signed in as described next.

    1. En el pasado, al final del inicio de sesión, se presentaba al usuario un código de 6 dígitos generado aleatoriamente (también conocido como código mágico).At the end of sign-in, in the past, the user was presented with a randomly generated 6-digit code (aka magic code). El usuario debía escribir este código en la conversación que iniciaba el inicio de sesión para completar dicho proceso.The user must type this code in the conversation that initiated the sign-in to complete the sign-in process. Este mecanismo solía producir una mala experiencia del usuario.This mechanism tends to result in a bad user experience. Además, aún así se corría el riesgo de sufrir ataques de suplantación de identidad (phishing).Additionally, it is still susceptible to phishing attacks. Un usuario malintencionado puede engañar a otro usuario para que inicie sesión y obtenga el código mágico mediante la suplantación de identidad (phishing).A malicious user can trick another user to sign-in and obtain the magic code through phishing.

    2. Debido a los problemas con el enfoque anterior, Azure Bot Service eliminó la necesidad del código mágico.Because of the issues with the previous approach, Azure Bot Service removed the need for the magic code. Azure Bot Service garantiza que el proceso de inicio de sesión solo se puede completar en la misma sesión del explorador que el propio Web Chat.Azure Bot Service guarantees that the sign-in process can only be completed in the same browser session as the Web Chat itself. Para habilitar esta protección, como desarrollador de bot, debe iniciar el chat web con un token de línea directa que contenga una lista de dominios de confianza que pueden hospedar el cliente de chat web del bot.To enable this protection, as a bot developer, you must start Web Chat with a Direct Line token that contains a list of trusted domains that can host the bot's Web Chat client. Antes, solo podía obtener este token pasando un parámetro opcional no documentado a la API de token de Direct Line.Before, you could only obtain this token by passing an undocumented optional parameter to the Direct Line token API. Ahora, con las opciones de autenticación mejoradas, puede especificar estáticamente la lista de dominios de confianza (origen) en la página de configuración de Direct Line.Now, with enhanced authentication options, you can statically specify the trusted domain (origin) list in the Direct Line configuration page.

    Consulte también Incorporación de autenticación al bot mediante Azure Bot Service.See also Add authentication to your bot via Azure Bot Service.

Ejemplos de códigoCode examples

El siguiente controlador de .NET funciona con opciones de autenticación mejoradas habilitadas y devuelve un token y un identificador de usuario de Direct Line.The following .NET controller works with enhanced authentication options enabled and returns a Direct Line Token and user ID.

public class HomeController : Controller
{
    public async Task<ActionResult> Index()
    {
        var secret = GetSecret();

        HttpClient client = new HttpClient();

        HttpRequestMessage request = new HttpRequestMessage(
            HttpMethod.Post,
            $"https://directline.botframework.com/v3/directline/tokens/generate");

        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", secret);

        var userId = $"dl_{Guid.NewGuid()}";

        request.Content = new StringContent(
            JsonConvert.SerializeObject(
                new { User = new { Id = userId } }),
                Encoding.UTF8,
                "application/json");

        var response = await client.SendAsync(request);
        string token = String.Empty;

        if (response.IsSuccessStatusCode)
        {
            var body = await response.Content.ReadAsStringAsync();
            token = JsonConvert.DeserializeObject<DirectLineToken>(body).token;
        }

        var config = new ChatConfig()
        {
            Token = token,
            UserId = userId
        };

        return View(config);
    }
}

public class DirectLineToken
{
    public string conversationId { get; set; }
    public string token { get; set; }
    public int expires_in { get; set; }
}
public class ChatConfig
{
    public string Token { get; set; }
    public string UserId { get; set; }
}

El siguiente controlador de JavaScript funciona con opciones de autenticación mejoradas habilitadas y devuelve un token y un identificador de usuario de Direct Line.The following JavaScript controller works with enhanced authentication options enabled and returns a Direct Line Token and user ID.

var router = express.Router(); // get an instance of the express Router

// Get a directline configuration (accessed at GET /api/config)
const userId = "dl_" + createUniqueId();

router.get('/config', function(req, res) {
    const options = {
        method: 'POST',
        uri: 'https://directline.botframework.com/v3/directline/tokens/generate',
        headers: {
            'Authorization': 'Bearer ' + secret
        },
        json: {
            User: { Id: userId }
        }
    };

    request.post(options, (error, response, body) => {
        if (!error && response.statusCode < 300) {
            res.json({
                    token: body.token,
                    userId: userId
                });
        }
        else {
            res.status(500).send('Call to retrieve token from Direct Line failed');
        }
    });
});

Recursos adicionalesAdditional resources