Adicionar logon único a um bot

Artigo
10/27/2023

APLICA-SE A: SDK v4

Este artigo mostra como usar o recurso de logon único (SSO) em um bot. Para fazer isso, esse recurso usa um bot de consumidor — também conhecido como bot raiz ou pai — para interagir com um bot de habilidade ou filho. Este artigo usa os termos bot raiz e skill bot.

Se você incluir suporte a SSO, um usuário poderá entrar no bot raiz usando um provedor de identidade e não precisará entrar novamente quando o controle passar para uma habilidade.

Os bots raiz e de habilidade são bots separados, executados em servidores potencialmente diferentes, cada um com sua própria memória e estado separados. Para obter mais informações sobre habilidades, consulte Visão geral de habilidades e Implementar uma habilidade. Para obter mais informações sobre autenticação de usuário, consulte Noções básicas de autenticação do Bot Framework, Autenticação de usuário e Adicionar autenticação a um bot.

Importante

Quando você usa a autenticação do Serviço de Bot do Azure AI com o Chat da Web, há algumas considerações de segurança importantes que você deve ter em mente. Para obter mais informações, consulte a seção de considerações de segurança no artigo Autenticação REST.

Pré-requisitos

Conhecimento das noções básicas de Bot, Gerenciando o estado e Sobre o logon único.
Conhecimento da biblioteca de diálogos e como implementar o fluxo de conversação sequencial e reutilizar diálogos
Conhecimento de desenvolvimento Azure e OAuth 2.0.
Visual Studio 2019 ou posterior para .NET.
O SSO com habilidade simples consumidor e habilidade em C#.

Sobre a amostra

Este artigo faz referência a dois bots: o RootBot e o SkillBot. O RootBot encaminha atividades para o SkillBot. Eles modelam este cenário típico de habilidade:

Um bot raiz chama um ou mais bots de habilidade.
Os bots raiz e de habilidade implementam a autenticação básica descrita no artigo Adicionar autenticação a um bot .
O usuário efetua login no bot raiz.
Por causa do SSO e já estar conectado ao bot raiz, eles são conectados ao bot de habilidades sem exigir a interação do usuário novamente.

Para obter uma visão geral de como o Bot Framework lida com a autenticação, consulte Autenticação de usuário. Para obter informações básicas sobre SSO, consulte Logon único.

O RootBot suporta SSO. Ele se comunica com o SkillBot em nome do usuário, sem que o usuário seja obrigado a se autenticar novamente no _SkillBot.

Para cada projeto no exemplo, você precisa do seguinte:

Um aplicativo Microsoft Entra ID para registrar um recurso de bot no Azure.
Um aplicativo de provedor de identidade Microsoft Entra ID para autenticação.

Nota

Atualmente, apenas o provedor de identidade Microsoft Entra ID é suportado.

Criar o recurso Azure RootBot

Crie um recurso de bot do Azure no portal do Azure para o RootBot. Siga as etapas descritas em Criar um recurso de bot do Azure.
Copie e salve o ID do aplicativo de registro do bot e o segredo do cliente.

Criar a identidade de ID do Microsoft Entra para o RootBot

O Microsoft Entra ID é um serviço de identidade na nuvem que permite criar aplicativos que entram com segurança nos usuários usando protocolos padrão do setor, como o OAuth2.0.

Crie um aplicativo de identidade para o que usa o Microsoft Entra ID para autenticar o RootBot usuário. Siga as etapas descritas em Criar o provedor de identidade do Microsoft Entra ID.
No painel esquerdo, selecione Manifesto.
Definido accessTokenAcceptedVersion como 2.
Selecione Guardar.
No painel esquerdo, selecione Expor uma API.
No painel direito, selecione Adicionar um escopo.
Na extremidade direita Adicionar uma seção de escopo , selecione Salvar e continuar.
Na janela exibida, em Quem pode consentir?, selecione Administradores e usuários.
Insira as informações necessárias restantes.
Selecione Adicionar escopo.
Copie e salve o valor do escopo.

Criar uma configuração de conexão OAuth para o RootBot

Crie uma conexão Microsoft Entra ID no registro do bot e insira os RootBot valores conforme descrito em Microsoft Entra ID e o valor descrito abaixo.
Deixe a URL do Token Exchange vazia.
Na caixa Escopos, insira o valor do RootBot escopo salvo nas etapas anteriores.

Nota

Scopes contém a URL na qual o usuário entra inicialmente no bot raiz, enquanto a URL da troca de token é deixada vazia.

Como exemplo, vamos supor que o appid do bot raiz seja rootAppId e o appid do bot de habilidade seja skillAppId. Os escopos do bot raiz serão parecidos com api://rootAppId/customScope, que é usado para fazer login no usuário. Os escopos desse bot raiz são então trocados com api://skillAppId/customscope durante o SSO.
Copie e salve o nome da conexão.

Criar o recurso do Azure SkillBot

Crie um recurso de bot do Azure no portal do Azure para o SkillBot. Siga as etapas descritas em Criar um recurso de bot do Azure.
Copie e salve o ID do aplicativo de registro do bot e o segredo do cliente.

Criar a identidade Microsoft Entra ID para o SkillBot

O Microsoft Entra ID é um serviço de identidade na nuvem que permite criar aplicativos que entram com segurança nos usuários usando protocolos padrão do setor, como o OAuth2.0.

Crie um aplicativo de identidade para o que usa o Microsoft Entra ID para autenticar o SkillBot bot. Siga as etapas descritas em Criar o provedor de identidade do Microsoft Entra ID.
No painel esquerdo, selecione Manifesto.
Definido accessTokenAcceptedVersion como 2.
Selecione Guardar.
No painel esquerdo, selecione Expor uma API.
No painel direito, selecione Adicionar um escopo.
Na seção Adicionar um escopo à direita, selecione Salvar e continuar.
Na janela exibida, em Quem pode consentir? , selecione Administradores e usuários.
Insira as informações necessárias restantes.
Selecione Adicionar escopo.
Copie e salve o valor do escopo.
Selecione Adicionar um aplicativo cliente. Na seção mais à direita, na caixa ID do cliente, digite o ID do aplicativo de identidade RootBot que você salvou antes. Certifique-se de usar a identidade do RootBot e não o ID do aplicativo de registro.

Nota

Para aplicativos cliente, o Serviço de Bot do Azure AI não oferece suporte a um único sing-on com o provedor de identidade B2C do Microsoft Entra ID.
Em Escopo autorizado, marque a caixa pelo valor do escopo.
Selecione Adicionar aplicativo.
No painel de navegação à esquerda, selecione Permissões de API. É uma prática recomendada definir explicitamente as permissões de API para o aplicativo.
1. No painel direito, selecione Adicionar uma permissão.
2. Selecione APIs da Microsoft e, em seguida, Microsoft Graph.
3. Escolha Permissões delegadas e verifique se as permissões necessárias estão selecionadas. Este exemplo requer as permissões listadas abaixo.
  
  Nota
  
  Qualquer permissão marcada como CONSENTIMENTO DE ADMINISTRADOR NECESSÁRIO exigirá que um usuário e um administrador de locatário façam login.
  - OpenID
  - perfil
  - Usuário.Read
  - Usuário.ReadBasic.All
4. Selecione Adicionar permissões.

Criar uma configuração de conexão OAuth para o SkillBot

Crie uma conexão Microsoft Entra ID no registro do bot e insira os SkillBot valores conforme descrito em Microsoft Entra ID e os valores descritos abaixo.
Na caixa URL da Troca de Tokens, insira o valor do SkillBot escopo salvo nas etapas anteriores.
Na caixa Escopos, insira os seguintes valores separados por espaço em branco:openidprofileUser.ReadUser.ReadBasic.All .
Copie e salve em um arquivo o nome da conexão.

Testar a ligação

Selecione na entrada de conexão para abrir a conexão que você criou.
Selecione Testar Conexão na parte superior do painel Configuração de Conexão do Provedor de Serviços.
Na primeira vez, isso deve abrir uma nova guia do navegador listando as permissões que seu aplicativo está solicitando e solicitar que você aceite.
Selecione Aceitar.
Isso deve redirecioná-lo para uma conexão de teste para <sua página de nome> de conexão bem-sucedida .

Para obter mais informações, consulte a visão geral do Microsoft Entra ID para desenvolvedores (v1.0) e a visão geral da plataforma de identidade da Microsoft (v2.0). Para obter informações sobre as diferenças entre os pontos de extremidade v1 e v2, consulte Por que atualizar para a plataforma de identidade da Microsoft (v2.0)?. Para obter informações completas, consulte Plataforma de identidade da Microsoft (anteriormente Microsoft Entra ID para desenvolvedores).

Preparar o código de exemplo

Você deve atualizar o appsettings.json arquivo em ambos os exemplos, conforme descrito abaixo.

Clone o SSO com o exemplo Simple Skill Consumer and Skill do repositório GitHub.

Abra o arquivo de SkillBot projeto appsettings.json . Atribua os seguintes valores do arquivo salvo:

{
    "MicrosoftAppId": "<SkillBot registration app ID>",
    "MicrosoftAppPassword": "<SkillBot registration password>",
    "ConnectionName": "<SkillBot connection name>",
    "AllowedCallers": [ "<RootBot registration app ID>" ]
}

Abra o arquivo de RootBot projeto appsettings.json . Atribua os seguintes valores do arquivo salvo:

{
    "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"
            }
        ]
}

Testar as amostras

Use o seguinte para testes:

RootBot comandos
- login permite que o usuário entre no registro do Microsoft Entra ID usando o RootBot. Uma vez conectado, o SSO cuida do login no SkillBot também. O usuário não precisa entrar novamente.
- token Exibe o token do usuário.
- logout Efetua logout do usuário do RootBotarquivo .
SkillBot comandos
- skill login permite que o RootBot para entrar no SkillBot, em nome do usuário. O usuário não verá um cartão de entrada, se já estiver conectado, a menos que o SSO falhe.
- skill token Exibe o token do usuário do SkillBot.
- skill logout desconecta o usuário do SkillBot

Nota

Na primeira vez que os usuários tentarem SSO em uma habilidade, eles poderão receber um cartão OAuth para fazer login. Isso ocorre porque eles ainda não deram consentimento para o aplicativo Microsoft Entra ID da habilidade. Para evitar isso, eles podem conceder consentimento de administrador para quaisquer permissões de gráfico solicitadas pelo aplicativo Microsoft Entra ID.

Emulador
Bate-papo na Web

Se você ainda não fez isso, instale o Bot Framework Emulator. Consulte também Depurar com o emulador.

Você precisará configurar o emulador para que o login de exemplo de bot funcione. Use as etapas abaixo: conforme mostrado em Configurar o emulador para autenticação.

Depois de configurar o mecanismo de autenticação, você pode executar o teste de amostra de bot real.

No Visual Studio, abra a solução e configure-a para iniciar a SSOWithSkills.sln depuração com vários processos.
Comece a depurar localmente na sua máquina. Observe que noRootBot arquivo de projeto appsettings.json você tem as seguintes configurações:
```
"SkillHostEndpoint": "http://localhost:3978/api/skills/"
"SkillEndpoint": "http://localhost:39783/api/messages"
```
Nota

Essas configurações implicam que, com ambos RootBot e SkillBot estão sendo executados na máquina local. O emulador se comunica com na porta 3978 e RootBot se comunica com RootBotSkillBot na porta 39783. Assim que você iniciar a depuração, duas janelas padrão do navegador serão abertas. Um na porta 3978 e outro na porta 39783.
Inicie o emulador.
Quando você se conectar ao bot, insira o RootBot ID e a senha do aplicativo de registro.
Digite hi para iniciar a conversa.
Insira o login. O RootBot exibirá um cartão de autenticação Entrar no AAD .
Selecione Iniciar sessão. A caixa de diálogo pop-up Confirmar URL aberto é exibida.
Selecione Confirmar. Você será conectado e o RootBot token será exibido.
Insira o token para exibir o token novamente.

Agora você está pronto para se comunicar com o SkillBot. Depois de assinar usando o RootBot, você não precisa fornecer suas credenciais novamente até sair. Isso demonstra que o SSO está funcionando.
Digite login de habilidade na caixa Emulador. Não lhe será pedido para iniciar sessão novamente. Em vez disso, o token do SkillBot é exibido.
Insira o token de habilidade para exibir o token novamente.
Agora você pode inserir o logout de habilidade para sair do SkillBot. Em seguida, digite logout para sair do SimpleRootBootarquivo .

Implante o bot raiz e o bot de habilidade no Azure. Para obter mais informações, consulte Tutorial: Provisionar um bot no Azure e Tutorial: Publicar um bot básico.
No editor de códigos, por exemplo Visual Studio, substitua os endereços localhost no arquivo de RootBot projeto appsetting.js com os IDdresses reais do Microsoft Entra, conforme mostrado abaixo.
```
"SkillHostEndpoint": "https://<your root bot deployed name>.azurewebsites.net/api/skills"
"SkillEndpoint": "https://<your skill bot deployed name>.azurewebsites.net/api/messages"
```
No browser, aceda ao Portal do Azure.
Abra seu registro de bot raiz. No painel esquerdo, selecione Testar no Web Chat. A janela de diálogo com o bot raiz é exibida com a mensagem de saudação do bot.
Inicie a conversa com o bot digitando oi , por exemplo. O bot repetirá sua mensagem de volta.
Insira o login. O RootBot exibirá um cartão de autenticação Entrar no AAD .
Selecione Iniciar sessão. Uma página da Web com um código de validação é exibida.
Para concluir o login, copie o código e insira-o na caixa de entrada. O RootBot token é exibido.
Insira o token para exibir o token novamente.

Agora você está pronto para se comunicar com o SkillBot. Depois de entrar no RootBot, você não precisa fornecer suas credenciais novamente até sair. Isso demonstra que o SSO está funcionando.
Insira o login de habilidade. O token do SkillBot é exibido.
Insira o token de habilidade para exibir o token novamente. Isso informa que você está se comunicando com o SkillBot sem a necessidade de entrar novamente. SSO em ação!
Agora você pode inserir o logout de habilidade para sair do SkillBot. Em seguida, digite logout para sair do SimpleRootBootarquivo .

Informações adicionais

O diagrama de sequência temporal a seguir se aplica aos exemplos usados no artigo e mostra a interação entre os vários componentes envolvidos. ABS significa Azure AI Bot Service (Serviço de Bot de IA do Azure).

Sequence diagram illustrating the skill token flow.

Na primeira vez, o usuário insere o comando para o loginRootBot.
O RootBot envia um OAuthCard solicitando que o usuário faça login.
O usuário insere as credenciais de autenticação que são enviadas para o ABS (Azure AI Bot Service).
O ABS envia o token de autenticação, gerado com base nas credenciais do usuário, para o RootBot.
O RootBot exibe o token raiz para o usuário ver.
O usuário insere o comando para o skill loginSkillBot.
O SkillBot envia um OAuthCard para o RootBot.
O RootBot pede um token trocável da ABS.
O SSO envia o token de habilidade do SkillBot para o RootBot.
O RootBot exibe o token de habilidade para o usuário ver. Observe que o token de habilidade foi gerado sem que o usuário precise entrar no SKillBot. Isso ocorre por causa do SSO.

O exemplo a seguir mostra como a troca de token acontece. O código é do arquivo 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;
}

Partilhar via