Compartilhar via

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

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 a ID do Microsoft Entra.

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

Pré-requisitos

Antes de seguir as etapas deste artigo, você deve 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 backend-app neste artigo) no Microsoft Entra ID.

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

  2. Configure a política validate-jwt no serviço de Gerenciamento de API. Essa política valida o token OAuth apresentado em cada solicitação de API de entrada. 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 obter links para mais informações, consulte a seção conteúdo relacionado.

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 significativo, como back-end-app. Esse nome é exibido para os usuários do aplicativo.
    • 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 do Microsoft Entra ID apresentado no cabeçalho de 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. Para o 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. Se você usar o ponto de extremidade v2, verifique se a propriedade accessTokenAcceptedVersion está definida como 2 no manifesto do aplicativo de back-end e qualquer aplicativo cliente configurado.

  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 tiver um token válido, o gateway poderá encaminhar a solicitação para a API.

Conteúdo relacionado