Partilhar via

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 estes passos para cenários em que uma aplicação cliente (ou bot) precise de aceder a recursos online seguros no backend em nome de um utilizador autenticado (por exemplo, para verificar emails ou fazer uma encomenda).

Descrição geral do cenário

Observação

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, pode ter uma aplicação web estática que acede a uma API backend do GitHub e quer aceder a dados específicos do utilizador iniciado sessão. O diagrama a seguir ilustra o cenário.

Diagrama mostrando o fluxo do processo para permissões delegadas pelo usuário.

  • O utilizador deve autorizar a aplicação a aceder a recursos protegidos em seu nome. Para autorizar a aplicação, o utilizador deve autenticar a sua identidade no Microsoft Entra.
  • Para realizar operações em nome do utilizador, a aplicação chama o serviço backend externo, como o GitHub.
  • Cada serviço externo tem uma forma 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 solicitar que o usuário entre para que ele possa adquirir o token do usuário.
  • Como parte da configuração, regista um fornecedor de credenciais usando o gestor de credenciais na instância de Gestão da 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.
  • Crias e usas uma ligação para ajudar a iniciar sessão do utilizador e obter o token de utilizador para que possa ser gerido.

Pré-requisitos

  • Acesso a um locatário do Microsoft Entra onde é possível ter permissões para criar um registo de aplicação e dar consentimento de administrador para as permissões da aplicação. 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. Por exemplo, a API do GitHub.

Etapa 1: Configurar a entidade de serviço do Plano de Dados do Gerenciamento de APIs 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. Utilize os seguintes passos para provisionar o principal de serviço utilizando Azure PowerShell.

  1. Entre 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 à esquerda, selecione Gerir>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, introduza um nome significativo que os utilizadores vejam, como Permissões de Utilizador.
    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.
    4. Selecione Register.
  5. No menu à esquerda, selecione Gerenciar>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 depois 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 esquerdo, selecione Gerir>Certificados & Segredos, depois 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. Você precisa dele em uma etapa posterior.

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

Neste passo, crie um fornecedor de credenciais para a sua API OAuth 2.0 backend que pretende aceder em nome do utilizador ou grupo. Por exemplo, siga os passos para criar um fornecedor de credenciais para a API do GitHub. Aqui estão os passos breves:

  1. Crie uma aplicação OAuth no GitHub para a API e atribua-lhe as permissões apropriadas para as solicitações que quiser chamar.
  2. Entre no portal do Azure e vá para sua instância de Gerenciamento de API.
  3. No menu esquerdo, selecione APIs>Gestor de credenciais, depois selecione + Criar. Captura de tela da criação de uma credencial de API no portal.
  4. No Criar fornecedor de credenciais, introduza as definições do fornecedor do GitHub. Para este cenário, no tipo Concessão, selecione Código de Autorização. Para obter mais informações, consulte Configurar provedores de credenciais no gerenciador de credenciais.
  5. Selecione Criar.
  6. Quando solicitado, reveja o URL de redirecionamento OAuth que é mostrado e selecione Sim para confirmar se corresponde ao URL que introduziu no registo da aplicação GitHub.

Etapa 4: Configurar uma conexão

Depois de criar um fornecedor de credenciais, pode adicionar uma ligação ao fornecedor do GitHub. 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 Passo 2: Inicie sessão na sua ligação, selecione o botão Iniciar sessão . 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. Procure um ou mais utilizadores ou grupos para adicionar e assinale a caixa de seleção.
    2. Procure o registo da aplicação que criou numa secção anterior.
    3. Selecione Selecione.
  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.

Sugestão

Use o portal do Azure 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.

Passo 5: Obtenha um token de acesso Microsoft Entra ID

Para permitir o acesso delegado pelo utilizador à API do backend, deve fornecer um token de acesso para o utilizador ou grupo delegado durante a execução na política get-authorization-context. Normalmente, a sua aplicação cliente recebe este token programaticamente através da Microsoft Authentication Library (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. Quando solicitado, inicie sessão. No corpo da resposta, copie o valor do código fornecido (exemplo: "0.AXYAh2yl...").

  3. Envie o seguinte pedido POST para o ponto final do token, substituindo <tenant-id> pelo ID do inquilino e incluindo o cabeçalho indicado, além dos parâmetros do corpo da configuração da aplicação 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: eyJ0...). Passa este valor na configuração da política no passo seguinte.

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 do Azure e vá para sua instância de Gerenciamento de API.

  2. No menu à esquerda, selecione APIs> APIs e 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 secção, definindo identity-type para jwt. Configure também as duas set-header políticas para definir o Authorization cabeçalho com o token obtido na get-authorization-context política e para configurar um cabeçalho obrigatório User-Agent para a API do GitHub.

    <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" />
         <set-header name="Authorization" exists-action="override">
            <value>@("Bearer " + ((Authorization)context.Variables.GetValueOrDefault("auth-context"))?.AccessToken)</value>
        </set-header>
        <set-header name="User-Agent" exists-action="override">
            <value>API Management</value>
        </set-header>
        [...]
    </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údo relacionado

  • Last updated on