Proteger uma API no Gerenciamento de API do Azure usando a autorização do OAuth 2.0 com a ID do Microsoft Entra

  • Artigo

APLICA-SE A: todas as camadas do Gerenciamento de API

Neste artigo, você aprenderá as 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 o Microsoft Entra ID.

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

Pré-requisitos

Para seguir as etapas neste artigo, você precisa ter:

  • Uma instância de Gerenciamento de API
  • Uma API publicada usando instância do Gerenciamento de API
  • Um locatário do Microsoft Entra

Visão geral

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

  1. Registre um aplicativo (chamado de back-end-app neste artigo) na ID do Microsoft Entra para proteger o acesso à API.

    Para acessar a API, os usuários ou aplicativos adquirirão e apresentarão um token OAuth válido que concede acesso ao 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 recebida. As solicitações válidas podem ser transmitidas para a API.

Os detalhes sobre os fluxos de autorização do OAuth e como gerar os tokens OAuth necessários não serão abordados neste artigo. Normalmente, um aplicativo cliente separado é usado para adquirir tokens da ID do Microsoft Entra que autorizam o acesso à API. Para saber mais, confira 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 Início Rápido: Configurar um aplicativo para expor uma API Web.

  1. No portal do Azure, pesquise e selecione Registros de aplicativo.

  2. Selecione Novo registro.

  3. Quando a página Registrar um aplicativo for exibida, insira as informações de registro do aplicativo:

    • Na seção Nome, insira um nome de aplicativo relevante que será exibido aos usuários do aplicativo, como aplicativo de back-end.
    • Na seção Tipos de conta com suporte, selecione uma opção que se adapte ao seu cenário.

  4. Deixe a seção URI de redirecionamento vazia.

  5. Selecione Registrar para criar o aplicativo.

  6. Na página Visão geral do aplicativo, localize o valor de ID do aplicativo (cliente) e registre-o para uso posterior.

  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, grave esse valor para uso posterior.

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

    1. Insira novos valores para Nome do escopo, Nome de exibição do consentimento do administrador e Descrição do consentimento do administrador.
    2. Verifique se o estado de escopo Habilitado está selecionado.

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

  10. Repita as duas etapas anteriores para adicionar todos os escopos com suporte da API.

  11. Após a criação dos escopos, anote-os para uso em uma etapa posterior.

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

A política de exemplo a seguir, quando adicionada à seção de política <inbound>, verifica o valor da declaração de audiência em um token de acesso obtido da ID do Microsoft Entra apresentada no cabeçalho autorização. Se ele não for válido, ela retornará uma mensagem de erro. Configure essa política em um escopo de política apropriado para seu cenário.

  • No URL do openid-config, o aad-tenant é a ID do locatário no Microsoft Entra ID. Encontre esse valor no portal do Azure, por exemplo, na página Visão geral do recurso do Microsoft Entra. O exemplo mostrado pressupõe um aplicativo do Microsoft Entra de locatário único e um ponto de extremidade de configuração v2.
  • O valor do claim é a ID do cliente do aplicativo de back-end registrado 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>

Observação

A URL openid-config acima corresponde ao ponto de extremidade v2. No ponto de extremidade openid-config v1, use https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration.

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

Fluxo de trabalho de autorização

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

  2. O token é adicionado no cabeçalho de autorização das solicitações de API para o Gerenciamento de API.

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

    • 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óximas etapas