Adicione a autorização do usuário usando a Credencial de Identidade Federada

O Serviço de Bot de IA do Azure facilita o desenvolvimento de agentes que podem acessar recursos online que exigem autenticação de usuário. Seu agente não precisa gerenciar tokens de autenticação, pois o Azure faz isso para você. O Azure usa o OAuth 2.0 para gerar um token com base nas credenciais de cada usuário. O agente usa o token gerado pelo Azure para acessar esses recursos. Dessa forma, o usuário não precisa fornecer ID e senha ao agente para acessar um recurso seguro, mas apenas para um provedor de identidade confiável.

Para configurar o OAuth no agente, registre um Bot do Azure se você ainda não fez isso.

Serviço de identidade do Microsoft Entra ID

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

Você pode usar um destes três serviços de identidade:

1. Plataforma de identidade da Microsoft (v2.0): também conhecida como ponto de extremidade do Azure Active Directory v2, que é uma evolução da plataforma do Azure AD (v1.0).
2. Credenciais Federadas: também conhecidas como AAD v2 com Credenciais Federadas.
3. Certificados: também conhecidos como AAD v2 com Certificados.

Isso permite que você crie aplicativos que entrem em todos os provedores de identidade da Microsoft e obtenham tokens para chamar APIs da Microsoft, como o Microsoft Graph, ou outras APIs que foram criadas por desenvolvedores.

Criar o provedor de identidade do Microsoft Entra ID

Esta seção mostra como criar um provedor de identidades do Microsoft Entra ID que usa o OAuth 2.0 para autenticar o agente ao Graph.

1. Abra o painel do Microsoft Entra ID no portal do Azure. Se você não estiver no locatário correto, selecione Alternar diretório para alternar para o locatário correto. (Para obter informações sobre como criar um locatário, consulte Acessar o portal e criar um locatário.)

2. Abra o painel Registros de aplicativo.

3. Configurar Registro do Aplicativo

   1. Para o SSO do Teams, abra o Registro de Aplicativo existente para o Agente/Bot do Azure.

      1. No painel Autenticação se você não vir uma plataforma Web, selecione + Adicionar uma plataforma.

         1. Selecione Web

         2. Insira o URI de Redirecionamento da tabela na próxima etapa.

         3. Clique em Configurar

            

   2. Para outros canais ou OAuth

      1. No painel Registros de aplicativo, escolha Novo registro.

      2. Preencha os campos obrigatórios e crie o registro do aplicativo.

         1. Nome do seu aplicativo.

         2. Selecione os Tipos de conta compatíveis para o aplicativo. Selecione Locatário Único.

         3. Para o URI de Redirecionamento, selecione Web e defina a URL como uma das URLs de redirecionamento OAuth com suporte.

            Residência de dados	Nuvem	URL do OAuth	URL de Redirecionamento do OAuth
            Nenhum	Público	https://token.botframework.com	https://token.botframework.com/.auth/web/redirect
            Europa	Público	https://europe.token.botframework.com	https://europe.token.botframework.com/.auth/web/redirect
            Estados Unidos	Público	https://unitedstates.token.botframework.com	https://unitedstates.token.botframework.com/.auth/web/redirect
            Índia	Público	https://india.token.botframework.com	https://india.token.botframework.com/.auth/web/redirect
            Nenhum	Azure Governamental	https://token.botframework.azure.us	https://token.botframework.azure.us/.auth/web/redirect
            Nenhum	Azure operado pela 21Vianet	https://token.botframework.azure.cn	https://token.botframework.azure.cn/.auth/web/redirect

         4. Selecione Registrar.

            1. Depois de criado, o Azure exibe a página Visão Geral do aplicativo.
            2. Registre o valor da ID do aplicativo (cliente). Você usará esse valor mais tarde como a ID do cliente ao criar a cadeia de conexão e registrar o provedor do Microsoft Entra ID com o registro do agente.
            3. Registre o valor da ID do diretório (locatário). Você usa esse valor para registrar este aplicativo do provedor com seu bot.

4. No painel de navegação, selecione Certificados & segredos para adicionar credenciais para seu aplicativo.

   1. Em Credenciais Federadas, selecione Adicionar Credenciais.

      

   2. Na página Adicionar Credenciais, escolha o Cenário de credencial Federada para Outro Emissor

      

   3. Insira valores nos campos necessários e examine e atualize as configurações

      1. Forneça informações em Conectar sua conta.

         

      2. Emissor: https://login.microsoftonline.com/{customer-tenant-ID}/v2.0

      3. Identificador de Identidade : /eid1/c/pub/t/{base64 encoded customer tenant ID}/a/{base64 encoded 1-P app client ID}/{unique-identifier-for-projected-identity}

         A tabela a seguir contém a representação de matriz de bytes codificada em Base64url de IDs de aplicativo interno com suporte. Use esse valor que representa nosso aplicativo interno.

         Valor codificado	Description
         9ExAW52n_ky4ZiS_jhpJIQ	Repositório de Tokens do Serviço de Bot codificado em Base64url
         ND1y8_Vv60yhSNmdzSUR_A	Codificação Base64url do Portal de Desenvolvimento do Bot Framework

         A tabela a seguir contém a representação de matriz de bytes codificada em Base64url de alguns IDs de locatário com suporte. Use o valor que representa o locatário do seu aplicativo.

         Valor codificado	Description
         v4j5cvGGr0GRqy180BHbRw	ID de locatário MSIT codificada em Base64url (aaaabbbb-0000-cccc-1111-dddd2222eeee)
         PwFflyR_6Een06vEdSvzRg	ID do locatário PME codificado em Base64url (bbbbcccc-1111-dddd-2222-eeee3333ffff)
         6q7FzcUVtk2wefyt0lBdwg	ID do locatário do Torus codificada em Base64url (ccccdddd-2222-eeee-3333-ffff4444aaa)
         IRngM2RNjE-gVVva_9XjPQ	ID do locatário do AME codificado em Base64url (ddddeeee-3333-ffff-4444-aaaa5555bbbb)

         Os proprietários do serviço de Identidade Primária calculam uma vez e fornecem para seus consumidores.

      4. Unique-identifier-for-projected-identity: um Identificador Exclusivo, de sua escolha, que é usado na Configuração de Conexão OAuth no Bot do Azure.

      5. Nome: nome de sua escolha, por exemplo. "agente oauth"

      6. Público-alvo: api://AzureADTokenExchange (usar valores específicos da nuvem)

   4. Forneça informações em detalhes da Credencial.

      

   5. Selecione Adicionar para adicionar a credencial.

5. Expor ponto de extremidade da API

   1. Clique em Expor uma API na barra lateral esquerda

      • Para um Bot do Serviço de Bot do Azure: o padrão api://{appid} é adequado.
      • Para um bot do Teams: esse formato é OBRIGATÓRIO api://botid-{appid}

   2. Adicionar um Escopo

      1. Selecione + Adicionar um escopo nos Escopos definidos por esta seção de API.

         

      2. Insira os detalhes para configurar o escopo.

         

      3. Inserir o nome do escopo defaultScopes

      4. Selecione o usuário que pode dar consentimento para este escopo. A opção padrão é Somente administradores.

      5. Insira o Nome de exibição de consentimento do administrador.

      6. Insira a descrição do consentimento do administrador.

      7. Insira o Nome de exibição de consentimento do usuário.

      8. Introduza a descrição do consentimento do usuário.

      9. Selecione a opção Habilitado para o estado.

      10. Selecione Adicionar escopo.

   3. Somente para o Teams, configure um aplicativo cliente autorizado

      1. Selecione + Adicionar um aplicativo cliente.

         

      2. Introduza o ID de cliente do Microsoft 365 adequado para os aplicativos que você pretende autorizar para o aplicativo Web.

         

      3. Selecione um dos seguintes IDs do cliente:

         ID do cliente a ser usada	Tipo de aplicativo para autorizar
         1fec8e78-bce4-4aaf-ab1b-5451cc387264	Aplicativo para celular ou desktop do Teams
         5e3ce6c0-2b1f-4285-8d4b-75ee78787346	Aplicativo Web do Teams
         4765445B-32C6-49B0-83E6-1D93765276CA	Aplicativo Web do Microsoft 365
         0ec893e0-5785-4de6-99da-4ed124e5296c	Aplicativo da área de trabalho do Microsoft 365
         D3590ED6-52B3-4102-AEF-AAD2292AB01C	Aplicativo móvel do Microsoft 365/aplicativo da área de trabalho do Outlook
         bc59ab01-8403-45c6-8796-ac3ef710b3e3	Aplicativo Web do Outlook
         27922004-5251-4030-b22d-91ecd9a37ea4	Aplicativo móvel do Outlook

      4. Selecione o URI da ID do aplicativo criada para seu aplicativo em escopos Autorizados para adicionar o escopo à API Web exposta.

      5. Selecione Adicionar aplicativo.

         

6. No painel de navegação, escolha Permissões de API para abrir o painel Permissões de API. A melhor prática é definir explicitamente as permissões de API para o aplicativo.

   1. Escolha Adicionar uma permissão para mostrar o painel Solicitar permissões de API.

   2. Para este exemplo, selecione as APIs da Microsoft e o Microsoft Graph.

   3. Escolha Permissões delegadas e verifique se as permissões necessárias estão selecionadas. Este exemplo requer estas permissões.

      Observação: qualquer permissão marcada como CONSENTIMENTO DO ADMINISTRADOR NECESSÁRIA exigirá que tanto um usuário quanto um administrador do locatário façam login, portanto, para seu agente, procure evitar essas permissões.

      • User.Read

   4. Selecione Adicionar permissões. (Na primeira vez que um usuário acessa esse aplicativo por meio do agente, ele precisa conceder consentimento.)

7. Agora você tem um aplicativo OAuth configurado.

   Note

   Você atribuirá a ID do aplicativo (cliente) ao criar a cadeia de conexão e registrar o provedor de identidade com o registro do agente. Confira a próxima seção.

Criar uma Conexão OAuth no Bot do Azure

A próxima etapa é registrar seu provedor de identidade com seu agente.

1. Abra a página de recursos do Bot do Azure do bot no portal do Azure.

2. Selecione Configurações e, depois, Configuração.

3. Selecione o botão Configurações de Conexão OAuth próximo à parte inferior da página.

4. Preencha o formulário da seguinte maneira:

   1. Nome. Digite um nome para a conexão. Use-o no código do agente.

   2. Provedor de serviços. Selecione AAD v2 com Credenciais Federadas para exibir campos específicos do provedor de serviços.

   3. ID do cliente. Insira a ID do aplicativo (cliente) que você registrou para seu provedor de identidade do Microsoft Entra ID (somente locatário único com suporte).

   4. Identificador exclusivo. Insira o identificador exclusivo que você registrou para seu provedor de identidade do Microsoft Entra ID ao criar credenciais federadas.

   5. URL de troca de token. Para o SSO do Teams, insira o ponto de extremidade de API criado anteriormente: api://botid-{appId}. Caso contrário, deixe em branco.

   6. ID do locatário. Insira a ID do diretório (locatário) que você registrou anteriormente para seu aplicativo Microsoft Entra ID ou common dependendo dos tipos de conta com suporte selecionados quando você criou o aplicativo DD do Azure. Para decidir qual valor atribuir, siga estes critérios:

      • Quando criar o aplicativo do Microsoft Entra ID, se você tiver escolhido Contas neste diretório organizacional somente (somente Microsoft: locatário único), insira a ID de locatário que você registrou anteriormente para o aplicativo do Microsoft Entra ID.
      • No entanto, se você tiver escolhido Contas em qualquer diretório organizacional (qualquer diretório do Microsoft Entra ID: contas Microsoft multilocatário e pessoais, p. ex., XBox, Outlook.com) ou Contas em qualquer diretório organizacional (diretório do Microsoft entra ID: multilocatário), insira common em vez de um ID de locatário. Caso contrário, o aplicativo Microsoft Entra ID verifica através do locatário cuja ID foi selecionada e exclui as contas pessoais da Microsoft.

      Esse é o locatário associado aos usuários que podem ser autenticados. Para obter mais informações, consulte Locatário no Microsoft Entra ID.

   7. Em Escopos, digite os nomes da permissão que você escolheu no registro de aplicativo. Para fins de teste, insira somente User.Read.

      1. Se você precisar usar esse token para o OBO para outro serviço (um token que pode ser trocado), use api://botid-{{appId}}/defaultScopes.

   Observação: para Microsoft Entra ID, o campo Escopos usa uma lista de valores separados por espaços, que diferencia maiúsculas de minúsculas.

5. Clique em Salvar.

Teste a conexão

1. Escolha a entrada de conexão para abrir a conexão que você criou.
2. Escolha Testar Conectividade na parte superior do painel Configuração da Conexão do Provedor de Serviços.
3. Na primeira vez, deve abrir uma nova guia do navegador listando as permissões que seu aplicativo está solicitando e solicitará que você aceite.
4. Selecione Aceitar.
5. Em seguida, isso deve redirecioná-lo para uma página Testar conectividade para seu nome de conexão concluído com sucesso, onde your-connection-succeeded é seu nome de conexão específico.
6. Somente para tokens que podem ser trocados
   1. Copiar o token JWT
   2. Decodificar o token usando https://jwt.io/
   3. O valor da declaração aud deve começar com api://