Proteger uma API na Gestão de API do Azure mediante a utilização da autorização OAuth 2.0 com o Microsoft Entra ID

  • Artigo

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

Neste artigo, você aprenderá etapas de alto nível para configurar sua instância de Gerenciamento de API do Azure para proteger uma API, usando o protocolo OAuth 2.0 com a ID do Microsoft Entra.

Para obter uma visão geral conceitual da autorização de API, consulte Autenticação e autorização para APIs no Gerenciamento de API.

Pré-requisitos

Antes de seguir as etapas neste artigo, você deve ter:

  • Uma instância de gerenciamento de API
  • Uma API publicada usando a instância de Gerenciamento de API
  • Um inquilino do Microsoft Entra

Descrição geral

Siga estas etapas para proteger uma API no Gerenciamento de API, usando a autorização OAuth 2.0 com o Microsoft Entra ID.

  1. Registre um aplicativo (chamado backend-app neste artigo) no Microsoft Entra ID para proteger o acesso à API.

    Para acessar a API, os usuários ou aplicativos adquirirão e apresentarão um token OAuth válido concedendo acesso a este aplicativo com cada solicitação de API.

  2. Configure a política validate-jwt no Gerenciamento de API para validar o token OAuth apresentado em cada solicitação de API de entrada. Solicitações válidas podem ser passadas para a API.

Detalhes sobre fluxos de autorização OAuth e como gerar os tokens OAuth necessários estão além do escopo deste artigo. Normalmente, um aplicativo cliente separado é usado para adquirir tokens do Microsoft Entra ID que autorizam o acesso à API. Para obter links para obter mais informações, consulte as próximas etapas.

Registrar um aplicativo no Microsoft Entra ID para representar a API

Usando o portal do Azure, proteja uma API com a ID do Microsoft Entra registrando primeiro um aplicativo que representa a API.

Para obter detalhes sobre o registro do aplicativo, consulte Guia de início rápido: configurar um aplicativo para expor uma API da Web.

  1. No portal do Azure, procure e selecione Registos de aplicações.

  2. Selecione Novo registo.

  3. Quando a página Registar uma aplicação for apresentada, introduza as informações de registo da aplicação:

    • Na seção Nome, insira um nome de aplicativo significativo que será exibido para os usuários do aplicativo, como back-end-app.
    • Na seção Tipos de conta suportados, selecione uma opção adequada ao seu cenário.

  4. Deixe a seção Redirecionar URI vazia.

  5. Selecione Registar para criar a aplicação.

  6. Na página Visão geral do aplicativo, localize o valor da ID do aplicativo (cliente) e registre-o para mais tarde.

  7. Na seção Gerenciar do menu lateral, selecione Expor uma API e defina o URI da ID do Aplicativo com o valor padrão. Se você estiver desenvolvendo um aplicativo cliente separado para obter tokens OAuth 2.0 para acesso ao aplicativo de back-end, registre esse valor para mais tarde.

  8. Selecione o botão Adicionar um escopo para exibir a página Adicionar um escopo :

    1. Insira um novo nome de escopo, nome de exibição do consentimento do administrador e descrição do consentimento do administrador.
    2. Verifique se o estado do escopo Ativado está selecionado.

  9. Selecione o botão Adicionar escopo para criar o escopo.

  10. Repita as duas etapas anteriores para adicionar todos os escopos suportados pela API.

  11. Depois que os escopos forem criados, anote-os para uso posterior.

Configurar uma política de validação JWT para pré-autorizar solicitações

O exemplo de política a seguir, quando adicionado à <inbound> seção policy, verifica o valor da declaração de audiência em um token de acesso obtido do Microsoft Entra ID que é apresentado no cabeçalho Authorization. Ele retorna uma mensagem de erro se o token não for válido. Configure essa política em um escopo de política apropriado para seu cenário.

  • openid-config Na URL, o é o aad-tenant ID do locatário no ID do Microsoft Entra. Encontre esse valor no portal do Azure, por exemplo, na página Visão geral do seu recurso Microsoft Entra. O exemplo mostrado pressupõe um aplicativo Microsoft Entra de locatário único e um ponto de extremidade de configuração v2.
  • O valor do é a ID do claim cliente do aplicativo de back-end que você registrou no Microsoft Entra ID.
<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>{audience-value - (ex:api://guid)}</audience>
    </audiences>
    <issuers>
        <issuer>{issuer-value - (ex: https://sts.windows.net/{tenant id}/)}</issuer>
    </issuers>
    <required-claims>
        <claim name="aud">
            <value>{backend-app-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

Nota

O URL anterior openid-config corresponde ao ponto de extremidade v2. Para o ponto de extremidade v1 openid-config , use https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration.

Para obter informações sobre como configurar políticas, consulte Definir ou editar políticas. Consulte a referência validate-jwt para obter mais personalização nas validações JWT. Para validar um JWT fornecido pelo serviço Microsoft Entra, o Gerenciamento de API também fornece a validate-azure-ad-token política.

Fluxo de trabalho de autorização

  1. Um usuário ou aplicativo adquire um token do Microsoft Entra ID com permissões que concedem acesso ao aplicativo de back-end.

  2. O token é adicionado no cabeçalho Authorization of API requests to API Management.

  3. O Gerenciamento de API valida o token usando a validate-jwt política.

    • Se uma solicitação não tiver um token válido, o Gerenciamento de API a bloqueará.

    • Se uma solicitação for acompanhada por um token válido, o gateway poderá encaminhá-la para a API.

Próximos passos