Configurar o gerenciador de credenciais - acesso delegado pelo usuário à API de back-end

APLICA-SE A: Todas as camadas de gerenciamento de API

Este artigo orienta você pelas etapas de alto nível para configurar e usar uma conexão gerenciada que concede aos usuários ou grupos do Microsoft Entra permissões delegadas a uma API OAuth 2.0 de back-end. Siga estas etapas para cenários em que um aplicativo cliente (ou bot) precisa acessar recursos online protegidos de back-end em nome de um usuário autenticado (por exemplo, verificar e-mails ou fazer um pedido).

Descrição geral do cenário

Nota

Esse cenário só se aplica a provedores de credenciais configurados com o tipo de concessão de código de autorização.

Nesse cenário, você configura uma conexão gerenciada que permite que um aplicativo cliente (ou bot) acesse uma API de back-end em nome de um usuário ou grupo do Microsoft Entra. Por exemplo, você pode ter um aplicativo Web estático que acessa uma API do GitHub de back-end e que deseja acessar dados específicos do usuário conectado. O diagrama a seguir ilustra o cenário.

• O usuário deve autorizar o aplicativo a acessar recursos protegidos em seu nome e, para autorizar o aplicativo, o usuário deve autenticar sua identidade
• Para executar operações em nome de um usuário, o aplicativo chama o serviço de back-end externo, como o Microsoft Graph ou o GitHub
• Cada serviço externo tem uma maneira de proteger essas chamadas - por exemplo, com um token de usuário que identifica exclusivamente o usuário
• Para proteger a chamada para o serviço externo, o aplicativo deve pedir ao usuário para entrar, para que ele possa adquirir o token do usuário
• Como parte da configuração, um provedor de credenciais é registrado usando o gerenciador de credenciais na instância de Gerenciamento de API. Ele contém informações sobre o provedor de identidade a ser usado, juntamente com um ID de cliente OAuth válido e segredo, os escopos OAuth a serem habilitados e outros metadados de conexão exigidos por esse provedor de identidade.
• Além disso, uma conexão é criada e usada para ajudar a entrar o usuário e obter o token de usuário para que ele possa ser gerenciado

Pré-requisitos

• Acesso a um locatário do Microsoft Entra onde você tem permissões para criar um registro de aplicativo e conceder consentimento de administrador para as permissões do aplicativo. Mais informações

  Se você quiser criar seu próprio locatário de desenvolvedor, você pode se inscrever para o Microsoft 365 Developer Program.

• Um ou mais usuários ou grupos no locatário aos quais delegar permissões.

• Uma instância de Gerenciamento de API em execução. Se precisar, crie uma instância de Gerenciamento de API do Azure.

• Uma API OAuth 2.0 de back-end que você deseja acessar em nome do usuário ou grupo.

• Se você optar por usar o Azure PowerShell localmente:
  • Instale a versão mais recente do módulo Az PowerShell.
  • Conecte-se à sua conta do Azure usando o cmdlet Connect-AzAccount .
• Se você optar por usar o Azure Cloud Shell:
  • Consulte Visão geral do Azure Cloud Shell para obter mais informações.

Etapa 1: Provisionar a entidade de serviço do Plano de Dados de Gerenciamento de API do Azure

Você precisa provisionar a entidade de serviço do Plano de Dados de Gerenciamento de API do Azure para conceder aos usuários ou grupos as permissões delegadas necessárias. Use as etapas a seguir para provisionar a entidade de serviço usando o Azure PowerShell.

1. Iniciar sessão no Azure PowerShell.

2. Se o módulo AzureAD ainda não estiver instalado, instale-o com o seguinte comando:

   Install-Module -Name AzureAD -Scope CurrentUser -Repository PSGallery -Force
   

3. Conecte-se ao seu locatário com o seguinte comando:

   Connect-AzureAD -TenantId "<YOUR_TENANT_ID>"
   

4. Se solicitado, entre com as credenciais da conta de administrador do seu locatário.

5. Provisione a entidade de serviço do Plano de Dados de Gerenciamento de API do Azure com o seguinte comando:

   New-AzureADServicePrincipal -AppId c8623e40-e6ab-4d2b-b123-2ca193542c65 -DisplayName "Azure API Management Data Plane"
   

Etapa 2: Criar um registro de aplicativo Microsoft Entra

Crie um aplicativo Microsoft Entra ID para delegação de usuários e dê a ele as permissões apropriadas para ler a conexão no Gerenciamento de API.

1. Entre no portal do Azure com uma conta com permissões suficientes no locatário.
2. Em Serviços do Azure, procure Microsoft Entra ID.
3. No menu esquerdo, selecione Registos de aplicações e, em seguida, selecione + Novo registo.
4. Na página Registar uma candidatura, introduza as definições de registo da sua aplicação:
   1. Em Nome, insira um nome significativo que será exibido para os usuários do aplicativo, como UserPermissions.
   2. Em Tipos de conta suportados, selecione uma opção que se adapte ao seu cenário, por exemplo, Contas apenas neste diretório organizacional (Locatário único).
   3. Defina o URI de redirecionamento para Web e digite https://www.postman-echo.com/get.
5. No menu à esquerda, selecione Permissões de API e, em seguida, selecione + Adicionar uma permissão.
   1. Selecione a guia APIs que minha organização usa , digite Plano de Dados de Gerenciamento de API do Azure e selecione-o.
   2. Em Permissões, selecione Autorizações.Ler e, em seguida, selecione Adicionar permissões.
6. No menu à esquerda, selecione Visão geral. Na página Visão geral, localize o valor da ID do aplicativo (cliente) e registre-o para uso em uma etapa posterior.
7. No menu à esquerda, selecione Certificados & segredos e, em seguida, selecione + Novo segredo do cliente.
   1. Insira uma descrição.
   2. Selecione uma opção para Expira.
   3. Selecione Adicionar.
   4. Copie o Valor do segredo do cliente antes de sair da página. Irá precisar delas noutro passo.

Etapa 3: Configurar um provedor de credenciais no Gerenciamento de API

1. Entre no portal e vá para sua instância de Gerenciamento de API.
2. No menu à esquerda, selecione Gerenciador de credenciais e, em seguida, selecione + Criar.
   
3. Na página Criar provedor de credenciais, insira as configurações do provedor de credenciais para sua API. Para esse cenário, em Tipo de concessão, você deve selecionar Código de autorização. Para obter mais informações, consulte Configurar provedores de credenciais no gerenciador de credenciais.
4. Selecione Criar.
5. Quando solicitado, revise a URL de redirecionamento OAuth exibida e selecione Sim para confirmar que ela corresponde à URL inserida no registro do aplicativo.

Etapa 4: Configurar uma conexão

Depois de criar um provedor de credenciais, você pode adicionar uma conexão ao provedor. Na guia Conexão, conclua as etapas para sua conexão:

1. Introduza um Nome de ligação e, em seguida, selecione Guardar.
2. Em Etapa 2: faça login na sua conexão, selecione o link para fazer login no provedor de credenciais. Conclua as etapas para autorizar o acesso e retornar ao Gerenciamento de API.
3. Em Etapa 3: Determinar quem terá acesso a essa conexão (política de acesso), selecione + Adicionar. Dependendo do cenário de delegação, selecione Usuários ou Grupo.
4. Na janela Selecionar item, faça seleções na seguinte ordem:
   1. Primeiro, procure um ou mais usuários (ou grupos) para adicionar e marque a caixa de seleção.
   2. Em seguida, na lista apresentada, procure o registo da aplicação que criou numa secção anterior.
   3. Em seguida, clique em Selecionar.
5. Selecione Concluir.

A nova conexão aparece na lista de conexões e mostra um status de Conectado. Se desejar criar outra conexão para o provedor de credenciais, conclua as etapas anteriores.

Gorjeta

Use o portal para adicionar, atualizar ou excluir conexões com um provedor de credenciais a qualquer momento. Para obter mais informações, consulte Configurar várias conexões.

Etapa 5: Adquirir um token de acesso do Microsoft Entra ID

Para habilitar o acesso delegado pelo usuário à API de back-end, um token de acesso para o usuário ou grupo delegado deve ser fornecido em tempo de execução na get-authorization-context política. Normalmente, isso é feito programaticamente em seu aplicativo cliente usando a Biblioteca de Autenticação da Microsoft (MSAL). Esta seção fornece etapas manuais para criar um token de acesso para teste.

1. Cole o seguinte URL no navegador, substituindo os valores para <tenant-id> e <client-id> pelos valores do registro do aplicativo Microsoft Entra:

   https://login.microsoftonline.com/<tenant-id>/oauth2/authorize?client_id=<client-id>&response_type=code&redirect_uri=https://www.postman-echo.com/get&response_mode=query&resource=https://azure-api.net/authorization-manager&state=1234`
   

2. Inicie sessão quando lhe for pedido. No corpo da resposta, copie o valor do código fornecido (exemplo: "0.AXYAh2yl…").

3. Envie a seguinte POST solicitação para o ponto de extremidade do token, substituindo <tenant-id> pelo ID do locatário e incluindo o cabeçalho indicado e os parâmetros do corpo do registro do aplicativo e o código copiado na etapa anterior.

   POST https://login.microsoftonline.com/<tenant-id>/oauth2/token HTTP/1.1
   

   Cabeçalho

   Content-Type: application/x-www-form-urlencoded

   Corpo

   grant_type: "authorization_code"
   client_id: <client-id>
   client_secret: <client-secret>
   redirect_uri: <redirect-url> 
   code: <code>   ## The code you copied in the previous step
   

4. No corpo da resposta, copie o valor de access_token fornecido (exemplo: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjZqQmZ1...). Você passará esse valor na configuração da política na próxima etapa.

Etapa 6: Configurar a política get-authorization-context para API de back-end

Configure a política get-authorization-context para a API de back-end que você deseja acessar em nome do usuário ou grupo. Para fins de teste, você pode configurar a política usando o token de acesso do Microsoft Entra ID para o usuário que você obteve na seção anterior.

1. Entre no portal e vá para sua instância de Gerenciamento de API.

2. No menu à esquerda, selecione APIs e, em seguida, selecione sua API de back-end OAuth 2.0.

3. Selecione Todas as operações. Na seção Processamento de entrada, selecione o ícone (</>) (editor de código).

4. Configure a get-authorization-context política na inbound seção , definindo identity-type como jwt:

   <policies>
       <inbound>
           [...]
           <get-authorization-context provider-id="<credential-provider-id>" authorization-id="<connection-id>" context-variable-name="auth-context" identity-type="jwt" identity="<access-token>" ignore-error="false" />
           [...]
       </inbound> 
   </policies>
   

Na definição de política anterior, substitua:

• <credential-provider-id> e <connection-id> com os nomes do provedor de credenciais e da conexão, respectivamente, que você configurou em uma etapa anterior.

• <access-token> com o token de acesso do Microsoft Entra ID que você gerou na etapa anterior.

Etapa 7: Testar a API

1. Na guia Teste, selecione uma operação que você configurou.

2. Selecione Enviar.

   Uma resposta bem-sucedida retorna dados do usuário da API de back-end.

Conteúdos relacionados

• Saiba mais sobre políticas de autenticação e autorização
• Saiba mais sobre escopos e permissões no Microsoft Entra ID.