Compartilhar via

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 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, para verificar emails ou fazer um pedido).

Visão geral do cenário

Observação

Esse cenário só se aplica aos 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 deseja acessar dados específicos para o usuário conectado. O diagrama a seguir ilustra o cenário.

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

  • O usuário deve autorizar o aplicativo a acessar recursos protegidos em seu nome. Para autorizar o aplicativo, o usuário deve autenticar sua identidade no Microsoft Entra.
  • Para executar operações em nome de um usuário, o aplicativo chama o serviço de back-end externo, como 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, você registra um provedor de credenciais 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.
  • Você cria e usa uma conexão 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 de Desenvolvedores do Microsoft 365.

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

  • Uma instância de Gerenciamento de API em execução. Se 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. Por exemplo, a API do GitHub.

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 seu inquilino com o seguinte comando:

    Connect-AzureAD -TenantId "<YOUR_TENANT_ID>"

  4. Se solicitado, faça o login com as credenciais da conta de administrador para seu cliente.

  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 de ID do Microsoft Entra 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. Nos Serviços do Azure, pesquise ID do Microsoft Entra.
  3. No menu à esquerda, selecione Gerenciar>registros de aplicativo e, em seguida, selecione + Novo registro.
  4. Na página Registrar um aplicativo , insira as configurações de registro do aplicativo:
    1. Em Nome, insira um nome significativo que os usuários veem, como UserPermissions.
    2. Em tipos de conta com suporte, selecione uma opção que se adapte ao seu cenário, por exemplo, Contas somente neste diretório organizacional (locatário único).
    3. Defina o URI de Redirecionamento para a Web e insira https://www.postman-echo.com/get.
    4. Selecione Registrar.
  5. No menu à esquerda, selecione Gerenciar>permissões de API e, em seguida, selecione + Adicionar uma permissão.
    1. Selecione as APIs que minha organização usa guia, digite o Plano de Dados de Gerenciamento de API do Azure e selecione-o.
    2. Em Permissões, selecione Authorizations.Read 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 Gerenciar>Certificados &segredos e, em seguida, selecione + Novo segredo do cliente.
    1. Insira uma Descrição.
    2. Selecione uma opção para Expira em.
    3. Selecione Adicionar.
    4. Copie o Valor da chave secreta do cliente antes de sair da página. Ela será necessária em uma etapa posterior.

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

Nesta etapa, crie um provedor de credenciais para sua API OAuth 2.0 de back-end que você deseja acessar em nome do usuário ou grupo. Por exemplo, siga as etapas para criar um provedor de credenciais para a API do GitHub. Etapas breves a seguir:

  1. Crie um aplicativo OAuth no GitHub para a API e dê a ele as permissões apropriadas para as solicitações que você deseja chamar.
  2. Entre no portal do Azure e vá para sua instância de Gerenciamento de API.
  3. No menu à esquerda, selecione ogerenciador de Credenciais de > e, em seguida, selecione + Criar. Captura de tela da criação de uma credencial de API no portal.
  4. Em Criar provedor de credenciais, insira as configurações para o provedor do GitHub. Para esse cenário, no tipo Grant, 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, examine a URL de redirecionamento do OAuth exibida e selecione Sim para confirmar se ela corresponde à URL inserida no registro do aplicativo GitHub.

Etapa 4: Configurar uma conexão

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

  1. Insira um nome de conexão e, em seguida, selecione Salvar.
  2. Na Etapa 2: Faça logon em sua conexão, selecione o botão Logon . Conclua as etapas para autorizar o acesso e retorne ao Gerenciamento de API.
  3. Na 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. Pesquise por um ou mais usuários ou grupos para adicionar e marcar a caixa de seleção.
    2. Pesquise o registro do aplicativo que você criou em uma seção anterior.
    3. Selecione 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 do Azure 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: Obter um token de acesso da ID do Microsoft Entra

Para habilitar o acesso delegado pelo usuário à API de back-end, você deve fornecer um token de acesso para o usuário ou grupo delegado em runtime na get-authorization-context política. Normalmente, seu aplicativo cliente obtém esse token programaticamente 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 em seu navegador, substituindo os valores para <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

    Header

    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...). Você passa 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 get-authorization-context 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 do Azure e vá para sua instância de 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 get-authorization-context política na inbound seção, definindo identity-type como jwt. Configure também as duas políticas set-header para definir o cabeçalho Authorization com o token obtido na política get-authorization-context e para configurar um cabeçalho User-Agent obrigatório 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 gerado 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