Adicionar uma autorização de utilizador utilizando a Credencial de Identidade Federada

O Serviço de Bot de IA do Azure facilita o desenvolvimento de agentes que podem aceder a recursos online que exigem autenticação do utilizador. O seu agente não precisa de gerir tokens de autenticação porque o Azure faz isso por si. O Azure usa o OAuth 2.0 para gerar um token com base nas credenciais de cada utilizador. O seu agente usa o token gerado pelo Azure para aceder a esses recursos. Deste modo, o utilizador não precisa de fornecer o ID e a palavra-passe ao agente para aceder um recurso seguro, mas apenas a um fornecedor de identidade fiável.

Para configurar o OAuth no agente, registe um Bot do Azure se ainda não o tiver feito.

Serviço de identidade Microsoft Entra ID

O Microsoft Entra ID é um serviço de identidade na nuvem que permite criar aplicações que permitem aos usuários entrar com segurança usando protocolos padrão da indústria, como o OAuth 2.0.

Pode utilizar um destes três serviços de identidade:

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

Permitem que crie aplicações que entram em todos os fornecedores de identidade da Microsoft e obtêm tokens para chamar APIs da Microsoft, como o Microsoft Graph, ou outras APIs criadas pelos programadores.

Criar o provedor de identidade Microsoft Entra ID

Esta secção mostra como criar um fornecedor de identidade do Microsoft Entra ID que usa o OAuth 2.0 para autenticar o agente do Graph.

1. Abra o painel do Microsoft Entra ID no portal do Azure. Se não estiver no inquilino correto, selecione Mudar de diretório para mudar para o inquilino correto. (Para obter informações sobre como criar um inquilino, consulte Aceder ao portal e criar um inquilino.)

2. Abra o painel de Registo de Aplicações.

3. Configurar Registo de Aplicação

   1. Para SSO do Teams, abra o Registo de Aplicação existente para o Bot do Agente/Azure.

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

         1. Selecione Web.

         2. Introduza o URI de redirecionamento a partir da tabela no passo seguinte.

         3. Clique em Configurar

            

   2. Para outros canais ou o OAuth

      1. No painel Registos de aplicações, selecione Novo registo.

      2. Preencha os campos obrigatórios e crie o registo da aplicação.

         1. Dê um nome à aplicação.

         2. Selecione os tipos de conta suportados para seu aplicativo. Selecione Único Inquilino.

         3. Para o URI de redirecionamento, selecione Web e defina o URL como um dos URLs de redirecionamento do OAuth suportados.

            Residência dos dados	Cloud	URL de OAuth	URL de Redirecionamento do OAuth
            Nenhuma	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
            Nenhuma	Azure Government	https://token.botframework.azure.us	https://token.botframework.azure.us/.auth/web/redirect
            Nenhuma	Azure operado pela 21Vianet	https://token.botframework.azure.cn	https://token.botframework.azure.cn/.auth/web/redirect

         4. Selecione Registar.

            1. Depois de criado, o Azure exibe a página Visão Geral do aplicativo.
            2. Registre o valor da ID do aplicativo (cliente). Utilize este valor posteriormente como o ID do cliente quando cria a cadeia de ligação e regista o fornecedor do Microsoft Entra ID com o registo do agente.
            3. Registre o valor do ID do diretório (tenant). Você usa este valor para registar esta aplicação de fornecedor com o seu bot.

4. No painel de navegação, selecione Certificados e segredos para adicionar credenciais à sua aplicação.

   1. Em Credenciais Federadas, selecione Adicionar Credenciais.

      

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

      

   3. Insira valores nos campos obrigatórios e revise e atualize as configurações

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

         

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

      3. Identificador do Requerente: /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 da matriz de bytes codificada em Base64url de IDs das Aplicações originais suportadas. Use este valor que representa a nossa Aplicação original.

         Valor codificado	Description
         9ExAW52n_ky4ZiS_jhpJIQ	Codificado em Base64url do Bot Service Token Store
         ND1y8_Vv60yhSNmdzSUR_A	Codificado em Base64url do Portal de Desenvolvimento do Bot Framework

         A tabela a seguir contém a representação da matriz de bytes codificada em Base64url de alguns IDs de inquilinos suportados. Use o valor que representa o inquilino da sua aplicação.

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

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

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

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

      6. Audiência: api://AzureADTokenExchange (Utilizar valores específicos da Cloud)

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

      

   5. Selecione Adicionar para adicionar a credencial.

5. Expor o ponto final da API

   1. Clique em Expor uma API no carril esquerdo.

      • Para um Azure Bot Service Bot: a predefinição api://{appid} é adequada.
      • Para um bot do Teams: este formato é OBRIGATÓRIO api://botid-{appid}

   2. Adicionar um Âmbito

      1. Selecione + Adicionar um âmbito na secção Âmbitos definidos por esta API.

         

      2. Introduza os detalhes para configurar o âmbito.

         

      3. Introduza o nome da âmbito defaultScopes.

      4. Selecione o utilizador que pode dar o consentimento para este âmbito. A opção predefinida é Apenas administradores.

      5. Introduza o Nome a apresentar de consentimento do administrador.

      6. Introduza a descrição para o consentimento do administrador.

      7. Introduza o Nome a apresentar de consentimento do utilizador.

      8. Introduza a descrição do consentimento do utilizador.

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

      10. Selecione Adicionar escopo.

   3. Apenas para o Teams, configure uma aplicação cliente autorizada.

      1. Selecione + Adicionar um aplicativo cliente.

         

      2. Introduza o ID do cliente Microsoft 365 apropriado para as aplicações que deseja autorizar para a aplicação Web da sua aplicação.

         

      3. Selecione um dos seguintes IDs de cliente:

         ID de cliente a utilizar	Tipo de aplicação a ser autorizado
         1fec8e78-bce4-4aaf-ab1b-5451cc387264	Aplicação móvel ou de ambiente de trabalho do Teams
         5e3ce6c0-2b1f-4285-8d4b-75ee78787346	Aplicação Web do Teams
         4765445b-32c6-49b0-83e6-1d93765276ca	Aplicação Web do Microsoft 365
         0ec893e0-5785-4de6-99da-4ed124e5296c	Aplicação de ambiente de trabalho do Microsoft 365
         d3590ed6-52b3-4102-aeff-aad2292ab01c	Aplicação móvel do Microsoft 365/Aplicação de ambiente de trabalho Outlook
         bc59ab01-8403-45c6-8796-ac3ef710b3e3	Aplicação Web do Outlook
         27922004-5251-4030-b22d-91ecd9a37ea4	Aplicação móvel do Outlook

      4. Selecione o URI do ID da aplicação que criou para a sua aplicação em Âmbitos autorizados para adicionar o âmbito à API da Web que expôs.

      5. Selecione Adicionar aplicativo.

         

6. No painel de navegação, selecione Permissões de API para abrir o painel de Permissões de API. É uma prática recomendada definir explicitamente as permissões de API para o aplicativo.

   1. Selecione Adicionar uma permissão para mostrar o painel Solicitar permissões da API .

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

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

      Nota: qualquer permissão marcada como CONSENTIMENTO DO ADMINISTRADOR OBRIGATÓRIO exigirá que um utilizador e um administrador de inquilinos inicie sessão, portanto, o seu agente tende a manter-se afastar-se destes.

      • Usuário.Read

   4. Selecione Adicionar permissões. (A primeira vez que um utilizador acede a esta aplicação através do agente, precisa de conceder o consentimento.)

7. Agora tem uma aplicação do OAuth configurada.

   Observação

   Irá atribuir a ID da aplicação (cliente) quando criar a cadeia de ligação e registar o fornecedor de identidade com o registo do agente. Ver secção seguinte.

Criar uma Ligação do OAuth no Azure Bot

O próximo passo é registar o seu fornecedor de identidades junto do seu agente.

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

2. Selecione Configurações e, em seguida , Configuração.

3. Selecione o botão Configurações de Ligação do OAuth na parte inferior da página.

4. Preencha o formulário da seguinte forma:

   1. Nome. Introduza um nome para a sua ligação. Utilize-o no seu código do agente.

   2. Prestador de Serviços. Selecione AAD v2 com Credenciais Federadas para exibir campos específicos do fornecedor de serviços.

   3. pt-PT: ID do cliente. Introduza o ID da aplicação (cliente) que registou para o seu fornecedor de identidade Microsoft Entra ID (Apenas Suporte para Inquilino Único).

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

   5. URL de Intercâmbio de Tokens. Para o SSO do Teams, introduza o ponto final da API criado anteriormente: api://botid-{appId}. Caso contrário, deixe em branco.

   6. ID do inquilino. Introduza o ID do diretório (inquilino) que registou anteriormente para a sua aplicação do Microsoft Entra ID ou common dependendo dos tipos de conta com suporte selecionados quando criou a aplicação Azure DD. Para decidir qual valor atribuir, siga estes critérios:

      • Ao criar o aplicativo Microsoft Entra ID, se você selecionou Contas somente neste diretório organizacional (somente Microsoft - Locatário único), insira a ID do locatário que você registrou anteriormente para o aplicativo Microsoft Entra ID.
      • No entanto, caso tenhas selecionado Contas em qualquer diretório organizacional (Qualquer diretório Microsoft Entra ID - multi-inquilino e contas pessoais da Microsoft, por exemplo, Xbox, Outlook.com) ou Contas em qualquer diretório organizacional (diretório ID do Microsoft Entra - multi-inquilino), introduz common em vez de uma ID de inquilino. Caso contrário, a aplicação Microsoft Entra ID verifica através do inquilino cuja ID foi selecionada e exclui contas pessoais da Microsoft.

      Este é o inquilino associado aos utilizadores que podem ser autenticados. Para obter mais informações, consulte Inquilinos no Microsoft Entra ID.

   7. Em Escopos, insira os nomes das permissões escolhidas no registo do aplicativo. Para fins de teste, basta inserir: User.Read.

      1. Se precisar de utilizar este token para OBO para outro serviço (um token permutável), utilize api://botid-{{appId}}/defaultScopes.

   Nota: para o Microsoft Entra ID, o campo Âmbitos usa uma lista de valores que diferencia maiúsculas de minúsculas e separadas por espaços.

5. Selecione Guardar.

Teste a sua ligação

1. Selecione na entrada de conexão para abrir a conexão que você criou.
2. Selecione Testar Conexão na parte superior do painel Configuração de Ligação do Provedor de Serviços.
3. 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.
4. Selecione Aceitar.
5. Isto deve redirecioná-lo para uma página Testar Ligação do nome da ligação Com êxito, onde your-connection-succeeded é o nome da ligação específica.
6. Apenas para tokens permutáveis
   1. Copie o token JWT
   2. Descodifique o token utilizando https://jwt.io/
   3. O valor da afirmação aud deve começar por api://