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

APLICA-SE A: todas as camadas do 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 delegados 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, verificando emails ou fazendo um pedido).

Visão geral do cenário

Observação

Esse cenário só se aplica a provedores de credenciais configurados com o código de autorização tipo de concessã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 para o 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 precisa solicitar que o usuário entre, para que ele possa adquirir o token do usuário desse serviço
• Como parte da configuração, um provedor de credenciais é registrado usando o gerenciador de credenciais na instância de Gerenciamento de API. A conexão contém informações sobre o provedor de identidade a ser usado, juntamente com uma ID e um segredo do cliente OAuth válidos, os escopos do 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 conectar 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 em que você tem permissões para criar um registro de aplicativo e conceder consentimento do administrador para as permissões do aplicativo. Saiba mais

  Se você quiser criar seu próprio locatário de desenvolvedor, inscreva-se no Programa para Desenvolvedores do Microsoft 365.

• Um ou mais usuários ou grupos no locatário para o qual delegar permissões.

• Uma instância do Gerenciamento de API em execução. Se você precisar, crie uma instância do 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 do Az PowerShell.
  • Conecte-se à sua conta do Azure usando o cmdlet Connect-AzAccount.
• Se você optar por usar o Azure Cloud Shell:
  • Confira 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. Entre no Azure PowerShell.

2. Se o módulo do 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 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 do Microsoft Entra

Crie um aplicativo do Microsoft Entra ID para delegação de usuário e conceda 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 à esquerda, selecione Registros de aplicativo e escolha Novo registro.
4. Na página Registrar um aplicativo, insira as configurações de registro do aplicativo:
   1. Em Nome, insira um nome relevante que será exibido aos usuários do aplicativo, como UserPermissions.
   2. Em Tipos de conta com suporte, selecione uma opção que atenda ao seu cenário, por exemplo, Contas somente neste diretório organizacional (locatário único).
   3. Defina o URI de Redirecionamento como Web e insira https://www.postman-echo.com/get.
5. No menu à esquerda, selecione Permissões de API e 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 Authorizations.Reade selecione Adicionar permissões.
6. No menu à esquerda, selecione Visão geral. Na página Visão geral, localize o valor de ID do aplicativo (cliente) e registre-o para uso em uma etapa posterior.
7. No menu esquerdo, selecione Certificados e 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 deixar a página. Ela será necessária em uma etapa posterior.

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

1. Entre no portal e vá para a instância do Gerenciamento de API.
2. No menu à esquerda, selecione Gerenciador de credenciais e selecione + Criar.
   
3. Na página Criar provedor de credenciais,insira as configurações para o provedor de credenciais para a sua API. Para esse cenário, em Tipo de concessão, você deve selecionar código de autorização. Para saber mais, consulte Configure provedores de credenciais gerenciador de credenciais.
4. Selecione Criar.
5. Quando solicitado, examine a URL de redirecionamento do OAuth exibida e selecione Sim para confirmar se 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. Insira um Nome de conexão e selecione Salvar.
2. Em Etapa 2: Fazer logon na conexão, selecione o link para fazer logon no provedor de credenciais. Conclua as etapas para autorizar o acesso e retorne 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, pesquise por um ou mais usuários (ou grupos) para adicionar e marcar a caixa de seleção.
   2. Em seguida, na lista exibida, pesquise o registro do aplicativo que você criou em uma seçã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 você quiser criar outra conexão para o provedor de credenciais, conclua as etapas anteriores.

Dica

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

Etapa 5: Atualizar 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 runtime na política de get-authorization-context. Normalmente, isso é feito programaticamente em seu aplicativo cliente usando a MSAL (Biblioteca de Autenticação da Microsoft). Esta seção fornece etapas manuais para criar um token de acesso para teste.

1. Cole a seguinte URL no navegador, substituindo os valores de <tenant-id> e <client-id> por 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. Quando solicitado, entre. No corpo da resposta, copie o valor do código fornecido (exemplo: "0.AXYAh2yl…").

3. Envie a solicitação de POST a seguir para o ponto de extremidade do token, substituindo <tenant-id> pela 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 do access_token fornecido (exemplo: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjZqQmZ1...). Você passará esse valor na configuração de política na próxima etapa.

Etapa 6: Configurar a política de contexto de autorização para a API de back-end

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

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

2. No menu à esquerda, selecione APIs e selecione sua API de back-end do 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 política de get-authorization-context na seção inbound, 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, configurados em uma etapa anterior.

• <access-token> com o token de acesso do Microsoft Entra ID gerado na etapa anterior.

Etapa 7: Testar a API

1. Na guia Testar, 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údo relacionado

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