JSON Web Token (JWT) validação no Gateway de Aplicação do Azure (pré-visualização)

O Gateway de Aplicação do Azure valida os JSON Web Tokens (JWTs) emitidos pelo Microsoft Entra ID (anteriormente Azure Active Directory) em pedidos HTTPS recebidos. Esta funcionalidade proporciona a implementação de autenticação primeiro-hop para APIs web ou qualquer recurso protegido, sem necessidade de código personalizado nas suas aplicações de servidor.

Esta capacidade verifica a integridade e autenticidade dos tokens nos pedidos recebidos. Depois determina se permite ou recusa o acesso antes de encaminhar o tráfego para os serviços de backend. Após validação bem-sucedida, o gateway injeta o x-msft-entra-identity cabeçalho no pedido e encaminha-o para o backend. As aplicações a jusante podem então consumir de forma segura informações de identidade verificadas.

Ao realizar validação de tokens na borda, o Application Gateway simplifica a arquitetura da aplicação e fortalece a postura geral de segurança. A validação do JWT é sem estado. Ou seja, cada pedido deve apresentar um token válido para que o acesso seja concedido.

O Application Gateway não mantém qualquer estado baseado em sessão ou cookies. Esta abordagem ajuda a garantir validação consistente entre pedidos e alinhamento com os princípios do Confiança Zero .

Importante

A validação do JWT no Gateway de Aplicação do Azure está atualmente em pré-visualização. Esta versão de pré-visualização é fornecida sem um contrato de nível de serviço e não a recomendamos para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

Capacidades chave

  • Validação de tokens: Valida a assinatura, emissor, locatário, audiência e tempo de vida do JWT. Os tokens devem ser emitidos pelo Microsoft Entra ID.
  • Propagação de identidade: Injeta um x-msft-entra-identity cabeçalho com tenantId:oid no backend.
  • Ações flexíveis: Configura Deny (devolver o estado 401) ou Allow (encaminha sem cabeçalho identidade) para tokens inválidos.
  • Suporte a múltiplos locatários: Suporta configurações comuns de locatários para organizações e consumidores.
  • Apenas HTTPS: Requer ouvintes HTTPS. HTTP não é suportado.

Diagrama mostrando a Validação JWT para o Gateway de Aplicação.

Pré-requisitos

  • Requisitos do Gateway de Aplicação:

    • Standard_v2 ou WAF_v2 SKU. O SKU Básico não é suportado.
    • Ouvinte HTTPS, juntamente com a configuração de um certificado TLS/SSL.
    • Azure Resource Manager API version 2025-03-01 ou posterior.

  • Requisitos de rede:

    • Conectividade de saída da sub-rede do Gateway de Aplicação para a porta TCP 443 em login.microsoftonline.com.

  • Requisitos do ID Microsoft Entra:

    • Registo da sua API web no Microsoft Entra ID.
    • Uma chamada para o Microsoft Entra ID para solicitar acesso a um serviço. O Microsoft Entra ID responde com um token de acesso.

  • Configuração da validação JWT no Application Gateway.

Registar uma aplicação no Microsoft Entra ID

  1. No portal Azure, vá a Registos de Aplicações.

  2. Selecione Novo registo.

  3. Para o Nome, introduza MyWebAPI.

  4. Para tipos de conta suportados, selecione Contas apenas neste diretório organizacional (apenas Microsoft - Inquilino único).

    Observação

    Os tipos de contas suportados são:

    • Locatário único (apenas neste diretório)
    • Multitenant (qualquer diretório Microsoft Entra ID)
    • Contas em qualquer diretório Microsoft Entra ID e contas pessoais da Microsoft

  5. Para URI de Redirecionamento (opcional), podes deixar as caixas em branco. Esta configuração não é necessária para cenários de API.

  6. Selecione Register.

  7. Anote os valores para o ID da Aplicação (cliente) e o ID do Diretório (inquilino).

  8. (Opcional) Configurar um URI de ID de aplicação:

    1. Vá para expor uma API>e defina um ID de aplicação URI.
    2. Use o URI padrão api://<ClientID> ou personalizado (por exemplo, https://api.contoso.com).

  9. (Opcional) Defina os âmbitos das APIs:

    • Vá a Exponer uma API>Adicionar um escopo.

    Esta funcionalidade serve para futuras funcionalidades de autorização. Não é obrigatório para a pré-visualização.

Configurar a validação JWT no Application Gateway

  1. Abra o portal de configuração de pré-visualização.

  2. Abra a sua instância do Gateway de Aplicação, vá a Definições no menu esquerdo e depois selecione configurações de validação JWT>Adicionar configuração de validação JWT.

    Captura de ecrã do painel para atualizar a configuração do JSON Web Token para o Application Gateway.

  3. Forneça os seguintes detalhes:

    Configuração Example Description
    Nome jwt-policy-1 Nome amigável para a configuração de validação
    Pedido não autorizado Deny Opção para rejeitar pedidos com JWTs em falta ou inválidos
    ID do Inquilino <your-tenant-id> GUID válido ou um dos common, organizations, ou consumers
    ID de Cliente <your-client-id> GUID do aplicativo registrado no Microsoft Entra
    Audiências <api://<client-id> (Opcional) Valores válidos adicionais de reivindicações de audiência (máximo 5)

  4. Associe a configuração a uma regra de roteamento conforme descrito na secção seguinte, caso precise de uma nova regra de roteamento.

Crie uma regra de roteamento (se necessário)

  1. Ir para Gateway de Aplicação>Regras>Adicionar Regra de Encaminhamento.

  2. Introduza ou selecione os seguintes itens:

    • Ouvinte: Use o protocolo HTTPS, um certificado atribuído ou um segredo Azure Key Vault.
    • Backend target: Selecionar ou criar um pool de backend.
    • Definições do backend: Use uma porta HTTP/HTTPS apropriada.
    • Nome da regra: Introduza um nome como jwt-route-rule.

  3. Vincule esta regra à sua configuração de validação JWT.

A configuração de validação JWT agora está anexada a um listener HTTPS seguro e a uma regra de encaminhamento.

Envie um token de acesso JWT com cada pedido para a aplicação segura

Para aceder de forma segura a uma aplicação que o Application Gateway ajuda a proteger, o cliente deve primeiro obter um token de acesso JWT do endpoint do token Microsoft Entra ID. O cliente inclui então este token no cabeçalho de autorização (por exemplo, Authorization: Bearer TOKEN) em cada pedido que envia para o Application Gateway.

O Application Gateway valida o token antes de encaminhar o pedido para a aplicação de backend. Esta validação assegura que apenas o tráfego autenticado e autorizado chega à aplicação segura.

Para mais informações, consulte Tokens de acesso na plataforma de identidade da Microsoft.

Resultados esperados dos pedidos

Scenario Estado HTTP Cabeçalho de identidade Observações
Token válido, action=Allow 200 Atualidade Token validado, identidade encaminhada
Token inválido, action=Deny 401 Ausente Pedido de blocos de gateway
Ficha em falta, action=Deny 401 Ausente Sem cabeçalho de autorização
Reivindicação em falta oid, action=Deny 403 Ausente Reivindicação crítica em falta

Verificação de backend

Verifique o x-msft-entra-identity cabeçalho para confirmar a autenticação.

Resolução de problemas das respostas 401 e 403

Se os pedidos devolverem um estado de 401 ou 403, verifique:

  • Configuration
    • O ID do locatário ou emissor (iss) corresponde ao seu locatário no Microsoft Entra.
    • Audiência (aud) corresponde ao ID do cliente configurado ou à lista de audiência.
  • Integridade do token
    • O token não está expirado (exp) e nbf não está no futuro.
  • Formatação dos pedidos
    • Authorization: Bearer <access_token> o cabeçalho está presente e intacto.
  • Implementação de política de Gateway
    • A validação do JWT está associada ao ouvinte correto e à regra de encaminhamento.
  • Ainda está a falhar?
    • Adquira um novo token para o público-alvo correto.
    • Verifique os registos de acesso ao Gateway de Aplicação para uma razão detalhada de falha.

Conteúdo relacionado

Para saber mais sobre validação JWT e funcionalidades de identidade relacionadas no Azure:

  • Last updated on