Adición del inicio de sesión único a un botAdd single sign on to a bot

se aplica a: SDK V4APPLIES TO: SDK v4

En este artículo se muestra cómo usar la característica de inicio de sesión único (SSO) en un bot.This article shows how to use the Single sign on (SSO) feature in a bot. Para ello, usa un bot consumidor, también conocido como bot raíz, para interactuar con un bot de aptitud.To do so, it uses a consumer bot, also known as root bot, to interact with a skill bot.

Una vez que los usuarios inician sesión en el bot raíz, no es necesario que inicien sesión en cada bot de aptitud que puedan usar con el bot raíz.Once the users sign in the root bot, they are not required to sign into each skill bot they might use through the root bot. Esto se debe al inicio de sesión único.This is because of SSO. Sin él, los usuarios tendrían que iniciar sesión cada vez que se comunican con un bot de aptitud diferente.Without it the users would have to sign in every time they communicate with a different skill bot.

Nota

El bot consumidor también se llama bot raíz o principal.The consumer bot is also called root or parent bot. El bot de aptitud también se llama bot secundario.The skill bot is also called child bot.</span> En este artículo se utilizan los términos bot raíz y bot de aptitud.This article uses the terms root bot and skill bot.</span> Con las aptitudes, los bots raíz y de aptitud son independientes que se podrían ejecutan en servidores diferentes, cada uno con su propia memoria y estado independientes.With skills, the root and skill are separate bots, running on potentially different servers, each with its own separate memory and state.

Consideraciones de Web Chat y Direct LineWeb Chat and Direct Line considerations

Importante

Cuando se usa la autenticación de Azure Bot Service con Chat en web 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. Para más información, consulte la sección Consideraciones de seguridad del artículo de autenticación REST.For more information, see the security considerations section in the REST authentication article.

PrerrequisitosPrerequisites

MuestraSample Versión de BotBuilderBotBuilder version MuestraDemonstrates
SSO con aptitud y bot consumidor de aptitud simple en CSharpSSO with Simple Skill Consumer and Skill in CSharp v4v4 La compatibilidad con SSO.SSO support

Información acerca de las muestrasAbout the samples

En este artículo se hace referencia a dos ejemplos: RootBot y SkillBot.This article references two samples: the RootBot and the SkillBot. RootBot reenvía actividades a SkillBot.The RootBot forwards activities to the SkillBot. Modelan este típico escenario de conocimientos:They model this typical skill scenario:

  • Un bot raíz llama a uno o varios bots de aptitud.A root bot calls one or more skill bots.
  • Tanto el bot raíz como los bots de aptitud implementan la autenticación básica que se describe en el artículo Adición de autenticación a un bot.Both the root and skill bots implement the basic authentication described in the Add authentication to a bot article.
  • El usuario inicia sesión en el bot raíz.The user logs into root bot.
  • Debido al inicio de sesión único (SSO) y que ya está conectado al bot raíz, ha iniciado sesión en el bot de aptitud sin necesidad de que el usuario vuelva a interactuar.Because of the SSO and being already logged into the root bot, she is logged into the skill bot without requiring user interaction again.

Para obtener información general sobre cómo el Bot Framework controla la autenticación, vea Autenticación de usuario.For an overview of how the Bot Framework handles authentication, see User authentication. Para más información sobre SSO, consulte Inicio de sesión único.For SSO background information, see Single sign on.

RootBot admite SSO del usuario.The RootBot supports user's SSO. Se comunica con SkillBot en nombre del usuario, sin que este tenga que autenticarse de nuevo en SkillBot.It communicates with the SkillBot on behalf of the user, without the user being required to authenticate again into the SkillBot.

Para cada proyecto del ejemplo, necesita lo siguiente:For each project in the sample, you need the following:

  1. Una aplicación Azure AD para registrar un recurso de bot en Azure.An Azure AD application to register a bot resource in Azure.
  2. Una aplicación de proveedor de identidades de Azure AD para la autenticación.An Azure AD identity provider application for authentication.

    Nota

    Actualmente, solo se admite el proveedor de identidades de Azure AD v2.Currently, only the Azure AD v2 identity provider is supported.

Creación del recurso RootBot de AzureCreate the Azure RootBot resource

  1. Cree un recurso de bot de Azure en Azure Portal para RootBot .Create an Azure bot resource in the Azure portal for the RootBot. Siga los pasos descritos en Creación de un recurso de bot de Azure.Follow the steps described in Create an Azure bot resource.
  2. Copie y guarde el identificador de aplicación y el secreto de cliente del registro de bot.Copy and save the bot registration app ID and the client secret.

Creación de identidad de Azure AD para RootBotCreate the Azure AD identity for RootBot

Azure AD es un servicio de identidad en la nube que permite crear aplicaciones que inician sesión de forma segura mediante protocolos estándar del sector como OAuth 2.0.The Azure AD is a cloud identity service that allows you to build applications that securely sign in users using industry standard protocols like OAuth2.0.

  1. Cree una aplicación de identidad para RootBot que use Azure AD v2 para autenticar al usuario.Create an identity application for the RootBot that uses Azure AD v2 to authenticate the user. Siga los pasos descritos en Creación del proveedor Azure AD identidades.Follow the steps described in Create the Azure AD identity provider.

  2. En el panel izquierdo, haga clic en Manifiesto.In the left pane, click Manifest.

  3. Establezca accessTokenAcceptedVersion en 2.Set accessTokenAcceptedVersion to 2.

  4. Haga clic en Save(Guardar).Click Save.

  5. En el panel izquierdo, haga clic en Exponer una API.In the left pane, click Expose an API.

  6. En el panel derecho, haga clic en Agregar un ámbito.In the right pane, click Add a scope.

  7. En el extremo derecho, en la sección Agregar un ámbito, haga clic en Guardar y continuar.In the far right Add a scope section click Save and continue.

  8. En la ventana que aparece, en ¿Quién puede dar el consentimiento? , seleccione Administradores y usuarios.In the displayed window, under Who can consent? select Admins and users.

  9. Escriba la información necesaria restante.Enter the remaining required information.

  10. Haga clic en Agregar ámbito.Click Add scope.

  11. Copie y guarde el valor de ámbito.Copy and save the scope value.

Creación de una configuración de conexión OAuthCreate an OAuth connection settings

  1. Cree una conexión de Azure AD v2 en el registro de bot RootBot y especifique los valores tal y como se describe en Azure AD v2, y el valor que se describe a continuación.Create an Azure AD v2 connection in the RootBot bot registration and enter values as described in Azure AD v2 and the value described below.

  2. Deje vacío el campo Dirección URL de intercambio de tokens.Leave the Token Exchange URL empty.

  3. En el cuadro Ámbitos, escriba el valor de ámbito RootBot que guardó en los pasos anteriores.In the Scopes box enter the RootBot scope value you saved in the previous steps.

  4. Copie y guarde el nombre de la conexión.Copy and save the name of the connection.

Creación del recurso SkillBot de AzureCreate the Azure SkillBot resource

  1. Cree un recurso de bot de Azure en Azure Portal para SkillBot .Create an Azure bot resource in the Azure portal for the SkillBot. Siga los pasos descritos en Creación de un recurso de bot de Azure.Follow the steps described in Create an Azure bot resource.
  2. Copie y guarde el identificador de aplicación y el secreto de cliente del registro de bot.Copy and save the bot registration app ID and the client secret.

Crear la identidad de Azure AD para SkillBotCreate the Azure AD identity for SkillBot

Azure AD es un servicio de identidad en la nube que permite crear aplicaciones que inician sesión de forma segura mediante protocolos estándar del sector como OAuth 2.0.The Azure AD is a cloud identity service that allows you to build applications that securely sign in users using industry standard protocols like OAuth2.0.

  1. Cree una aplicación de identidad para SkillBot que use Azure AD v2 para autenticar el bot.Create an identity application for the SkillBot that uses Azure AD v2 to authenticate the bot. Siga los pasos descritos en Creación del proveedor Azure AD identidades.Follow the steps described in Create the Azure AD identity provider.

  2. En el panel izquierdo, haga clic en Manifiesto.In the left pane, click Manifest.

  3. Establezca accessTokenAcceptedVersion en 2.Set accessTokenAcceptedVersion to 2.

  4. Haga clic en Save(Guardar).Click Save.

  5. En el panel izquierdo, haga clic en Exponer una API.In the left pane, click Expose an API.

  6. En el panel derecho, haga clic en Agregar un ámbito.In the right pane, click Add a scope.

  7. En el extremo derecho, en la sección Agregar un ámbito, haga clic en Guardar y continuar.In the far right Add a scope section click Save and continue.

  8. En la ventana que aparece, en ¿Quién puede dar el consentimiento? , seleccione Administradores y usuarios.In the displayed window, under Who can consent? select Admins and users.

  9. Escriba la información necesaria restante.Enter the remaining required information.

  10. Haga clic en Agregar ámbito.Click Add scope.

  11. Copie y guarde el valor de ámbito.Copy and save the scope value.

  12. Haga clic en Agregar una aplicación cliente.Click Add a client application. En la sección de la derecha, en el cuadro Id. de cliente, escriba el identificador de aplicación de la identidad de RootBot que guardó anteriormente.In the far right section, in the Client ID box, enter the RootBot identity app ID you saved before. Asegúrese de usar la identidad de RootBot y no el identificador de la aplicación de registro.Make sure you use the RootBot identity and not the registration app ID.

  13. En Ámbito autorizado, active la casilla por el valor del ámbito.Under Authorized scope, check the box by the scope value.

  14. Haga clic en Agregar aplicación.Click Add application.

  15. En el panel de navegación de la izquierda, haga clic en Permisos de API.In the navigation pane on the left, click API permissions. Es un procedimiento recomendado establecer explícitamente los permisos de API de la aplicación.It is a best practice to explicitly set the API permissions for the app.

    1. En el panel de la derecha, haga clic en Agregar un permiso.In the right pane, click Add a permission.

    2. Seleccione API de Microsoft y, luego, Microsoft Graph.Select Microsoft APIs then Microsoft Graph.

    3. Elija Permisos delegados y asegúrese de que se seleccionan los permisos que necesita.Choose Delegated permissions and make sure the permissions you need are selected. Este ejemplo requiere los permisos que se enumeran a continuación.This sample requires the permissions listed below.

      Nota

      Los permisos marcados como SE NECESITA EL CONSENTIMIENTO DEL ADMINISTRADOR requerirán un usuario y un administrador de inquilinos para iniciar sesión.Any permission marked as ADMIN CONSENT REQUIRED will require both a user and a tenant admin to login.

      • openidopenid
      • profileprofile
      • User.ReadUser.Read
      • User.ReadBasic.AllUser.ReadBasic.All
    4. Haga clic en Agregar permisos.Click Add permissions.

Creación de una configuración de conexión OAuthCreate an OAuth connection settings

  1. Cree una conexión de Azure AD v2 en el registro de bot SkillBot y especifique los valores tal y como se describe en Azure AD v2, y los valores que se describen a continuación.Create an Azure AD v2 connection in the SkillBot bot registration and enter values as described in Azure AD v2 and the values described below.

  2. En el cuadro Dirección URL de intercambio de tokens, escriba el valor de ámbito SkillBot que guardó en los pasos anteriores.In the Token Exchange URL box enter the SkillBot scope value you saved in the previous steps.

  3. En el cuadro Ámbitos, escriba los valores siguientes separados por espacio en blanco: profile User.Read User.ReadBasic.All openid.In the Scopes box enter the following values separated by blank space: profile User.Read User.ReadBasic.All openid.

  4. Copie y guarde el nombre de la conexión en un archivo.Copy and save to a file the name of the connection.

Comprobación de la conexiónTest the connection

  1. Haga clic en la entrada de la conexión para abrir la conexión que acaba de crear.Click on the connection entry to open the connection you just created.
  2. Haga clic en Probar conexión en la parte superior del panel Configuración de conexión del proveedor de servicios.Click Test Connection at the top of the Service Provider Connection Setting pane.
  3. La primera vez, se debería abrir una pestaña del explorador nueva con los permisos que solicita la aplicación y en la que se le pide que acepte.The first time, this should open a new browser tab listing the permissions your app is requesting and prompt you to accept.
  4. Haga clic en Aceptar.Click Accept.
  5. A continuación, se le redirigirá a una página Test Connection to <your-connection-name> Succeeded (Resultado satisfactorio de la prueba de conexión a).This should then redirect you to a Test Connection to <your-connection-name> Succeeded page.

Para más información, consulte Introducción a Azure Active Directory para desarrolladores (v1.0) y Introducción a la Plataforma de identidad de Microsoft (versión 2.0).For more information, see the Azure Active Directory for developers (v1.0) overview and Microsoft identity platform (v2.0) overview. Para obtener información sobre las diferencias entre los puntos de conexión v1 y v2, consulte Motivos para actualizar a la Plataforma de identidad de Microsoft (v2.0).For information about the differences between the v1 and v2 endpoints, see Why update to Microsoft identity platform (v2.0)?. Para más información, consulte Plataforma de identidad de Microsoft (antes Azure Active Directory para desarrolladores).For complete information, see Microsoft identity platform (formerly Azure Active Directory for developers).

Preparación del código de ejemploPrepare the samples code

Debe actualizar el archivo de appsettings.json en ambos ejemplos, como se describe a continuación.You must update the appsettings.json file in both samples as described below.

  1. En el repositorio de GitHub, clone el ejemplo de SSO con aptitud y bot consumidor de aptitud simple en CSharp.From the GitHub repository clone the sample SSO with Simple Skill Consumer and Skill

  2. Abra el proyecto SkillBot, archivo appsettings.json.Open the SkillBot project appsettings.json file. En el archivo guardado, asigne los valores siguientes:From the saved file, assign the following values:

    {
        "MicrosoftAppId": "<SkillBot registration app ID>",
        "MicrosoftAppPassword": "<SkillBot registration password>",
        "ConnectionName": "<SkillBot connection name>",
        "AllowedCallers": [ "<RootBot registration app ID>" ]
    }
    
    
  3. Open the RootBot project appsettings.json file. From the saved file, assign the following values:

    {
        "MicrosoftAppId": "<RootBot registration app ID>",
        "MicrosoftAppPassword": "<RootBot registration password>",
        "ConnectionName": "<RootBot connection name>",
        "SkillHostEndpoint": "http://localhost:3978/api/skills/",
        "BotFrameworkSkills": [
                {
                "Id": "SkillBot",
                "AppId": "<SkillBot registration app ID>",
                "SkillEndpoint": "http://localhost:39783/api/messages"
                }
            ]
    }
    

Prueba de los ejemplosTest the samples

Use lo siguiente para las pruebas:Use the following for testing:

  • Comandos de RootBotRootBot commands

    • login permite al usuario iniciar sesión en el registro de Azure AD mediante RootBot.login allows the user to sign into the Azure AD registration using the RootBot. Una vez iniciada la sesión, SSO se encarga también del inicio de sesión en SkillBot.Once signed in, SSO takes care of the sign in into the the SkillBot also. El usuario no tiene que iniciar sesión de nuevo.The user does not have to sign in again.
    • token muestra el token del usuario.token displays the user's token.
    • logout cierra la sesión del usuario en RootBot.logout logs the user out of the RootBot.
  • Comandos de SkillBotSkillBot commands

    • skill login permite que RootBot inicie sesión en SkillBot en nombre del usuario.skill login allows the RootBot to sign into the SkillBot, on behalf of the user. Si el usuario ya ha iniciado sesión, no se le muestra una tarjeta de inicio de sesión, a menos que se produzca un error de SSO.The user is not shown a sign in card, if already signed in, unless SSO fails.
    • skill token muestra el token del usuario de SkillBot.skill token displays the user's token from the SkillBot.
    • skill logout cierra la sesión del usuario en SkillBot.skill logout logs the user out of the SkillBot

Nota

La primera vez que los usuarios prueben el inicio de sesión único en una aptitud, es posible que se les muestre una tarjeta de OAuth para iniciar sesión.The first time users try SSO on a skill, they may be presented with an OAuth card to log in. Esto se debe a que aún no ha dado su consentimiento a la aplicación de Azure AD de la aptitud.This is because they have not yet given consent to the skill's Azure AD app. Para evitar esto, pueden dar su consentimiento de administrador a todos los permisos de Graph solicitados por la aplicación de Azure AD.To avoid this, they can grant admin consent for any graph permissions requested by the Azure AD app.

Prueba mediante el emuladorTest using the Emulator

Si aún no lo ha hecho, instale Bot Framework Emulator.If you have not done so already, install the Bot Framework Emulator. Consulte también Depurar con el emulador.See also Debug with the Emulator.

Para que el inicio de sesión de ejemplo del bot funcione, debe configurar el emulador como se muestra en Configuración del emulador para la autenticación.In order for the bot sample login to work you must configure the Emulator as shown in Configure the Emulator for authentication.

Después de haber configurado el mecanismo de autenticación, puede realizar las pruebas del bot de ejemplo.After you have configured the authentication mechanism, you can perform the actual bot sample testing.

  1. En Visual Studio, abra la solución SSOWithSkills.sln y configúrela para iniciar la depuración con varios procesos.In Visual Studio, open the SSOWithSkills.sln solution and configure it to start debugging with multiple processes.
  2. Inicie la depuración localmente en el equipo.Start debugging locally on your machine. Tenga en cuenta que, en el archivo appsettings.json del proyecto RootBot tiene la siguiente configuración:Notice that in theRootBot project appsettings.json file you have the following settings:
    "SkillHostEndpoint": "http://localhost:3978/api/skills/"
    "SkillEndpoint": "http://localhost:39783/api/messages"

Nota

Esta configuración implica que RootBot y SkillBot están en ejecución en el equipo local.These settings imply that, with both RootBot and SkillBot are running on the local machine. El emulador se comunica con RootBot en el puerto 3978 y RootBot se comunica con en el puerto SkillBot 39783.The Emulator communicates with RootBot on port 3978 and RootBot communicates with SkillBot on port 39783. En cuanto se inicia la depuración, se abren dos ventanas del explorador predeterminado.As soon as you start debugging, two default browser windows open. Una en el puerto 3978 y otra en el puerto 39783.One on port 3978 and the other on port 39783.

  1. Inicie el emulador.Start the Emulator.

  2. Tendrá que proporcionar el identificador de aplicación y la contraseña del registro de RootBot al conectarse al bot.You need to provide your RootBot registration app ID and password when you connect to the bot.

  3. Escriba hi para iniciar la conversación.Type hi to start the conversation.

  4. Escriba login (inicio de sesión).Enter login. RootBot mostrará un tarjeta de autenticación Sign In to AAD (Inicio de sesión en AAD).The RootBot will display a Sign In to AAD authentication card.

    Inicio de sesión raíz

  5. Haga clic en Iniciar sesión.Click Sign In. Se muestra el diálogo emergente Confirm Open URL (Confirmar apertura de URL).The pop-up dialog Confirm Open URL is displayed.

    Confirmación de URL raíz

  6. Haga clic en Confirmar.Click Confirm. Iniciará sesión y se mostrará el token de RootBot.You will be logged in and the RootBot token is displayed.

  7. Escriba token para volver a mostrar el token.Enter token to display the token again.

    Imagen de token raíz

    Ahora está listo para comunicarse con SkillBot.Now you are ready to communicate with the SkillBot. Una vez que haya iniciado sesión con RootBot, no es necesario que vuelva a proporcionar las credenciales hasta que cierre la sesión. Esto demuestra que el inicio de sesión único funciona.Once you've signed using the RootBot, you don't need to provide your credentials again until you sign out. This demonstrates that SSO is working.

  8. Escriba el inicio de sesión de la aptitud en el cuadro Emulador.Enter skill login in the Emulator box. No se le pedirá que vuelva a iniciar sesión.You will not be asked to login again. En su lugar, se muestra el token de SkillBot.Instead the SkillBot token is displayed.

  9. Escriba skill token (token de aptitud) para volver a mostrar el token.Go ahead enter skill token to display the token again.

    Imagen del token de aptitud

  10. Ahora puede escribir skill logout (cierre de sesión de aptitud) para cerrar la sesión de SkillBot.Now you can enter skill logout to sign out of the SkillBot. Después, escriba logout (cierre de sesión) para cerrar la sesión de SimpleRootBoot.Then enter logout to sign out of the SimpleRootBoot.

Información adicionalAdditional information

El siguiente diagrama temporal se aplica a los ejemplos que se usan en el artículo y muestra la interacción entre los distintos componentes implicados.The following time-sequence diagram applies to the samples used in the article and shows the interaction between the various components involved. ABS es Azure Bot Service.ABS stands for Azure Bot Service.

Flujo de token de aptitud

  1. La primera vez, el usuario escribe el comando login para RootBot.The first time, the user enters the login command for the RootBot.
  2. RootBot envía una OAuthCard para pedir al usuario que inicie sesión.The RootBot sends an OAuthCard asking the user to sign in.
  3. El usuario especifica las credenciales de autenticación que se envían a ABS (Azure Bot Service).The user enters the authentication credentials that are sent to the ABS (Azure Bot Service).
  4. ABS envía el token de autenticación, generado según las credenciales del usuario, a RootBot.The ABS sends the authentication token, generated based on the user's credentials, to the RootBot.
  5. RootBot muestra el token raíz que el usuario debe ver.The RootBot displays the root token for the user to see.
  6. El usuario especifica el comando skill login para SkillBot.The user enters the skill login command for the SkillBot.
  7. SkillBot envía OAuthCard a RootBot.The SkillBot sends an OAuthCard to the RootBot.
  8. RootBot solicita token intercambiable de ABS.The RootBot asks for an exchangeable token from ABS.
  9. En este momento, entra en juego el "baile" de SSO, que finaliza con el envío del token de aptitud por parte de SkillBot a RootBot.At this point the SSO "dance" comes into play which ends with the skill token sent by the SkillBot to the RootBot.
  10. RootBot muestra el token de aptitud que el usuario debe ver.The RootBot displays the skill token for the user to see. Tenga en cuenta que el token de aptitud se generó sin que el usuario tenga que iniciar sesión en SKillBot.Notice that the skill token was generated without the user having to sign in the SKillBot. Esto se debe al inicio de sesión único.This is because of the SSO.

Para ver cómo se produce el intercambio de tokens, consulte el ejemplo siguiente.To see how the token exchange happens, please refer to the example shown below. La función se puede encontrar en TokenExchangeSkillHandler.cs.The function can be found in TokenExchangeSkillHandler.cs.

private async Task<bool> InterceptOAuthCards(ClaimsIdentity claimsIdentity, Activity activity)
{
    var oauthCardAttachment = activity.Attachments?.FirstOrDefault(a => a?.ContentType == OAuthCard.ContentType);
    if (oauthCardAttachment != null)
    {
        var targetSkill = GetCallingSkill(claimsIdentity);
        if (targetSkill != null)
        {
            var oauthCard = ((JObject)oauthCardAttachment.Content).ToObject<OAuthCard>();

            if (!string.IsNullOrWhiteSpace(oauthCard?.TokenExchangeResource?.Uri))
            {
                using (var context = new TurnContext(_adapter, activity))
                {
                    context.TurnState.Add<IIdentity>("BotIdentity", claimsIdentity);

                    // AAD token exchange
                    try
                    {
                        var result = await _tokenExchangeProvider.ExchangeTokenAsync(
                            context,
                            _connectionName,
                            activity.Recipient.Id,
                            new TokenExchangeRequest() { Uri = oauthCard.TokenExchangeResource.Uri }).ConfigureAwait(false);

                        if (!string.IsNullOrEmpty(result?.Token))
                        {
                            // If token above is null, then SSO has failed and hence we return false.
                            // If not, send an invoke to the skill with the token. 
                            return await SendTokenExchangeInvokeToSkill(activity, oauthCard.TokenExchangeResource.Id, result.Token, oauthCard.ConnectionName, targetSkill, default).ConfigureAwait(false);
                        }
                    }
                    catch
                    {
                        // Show oauth card if token exchange fails.
                        return false;
                    }

                    return false;
                }
            }
        }
    }
    return false;
}

Lecturas adicionalesFurther reading