Validação do JWT (Token Web JSON) no Gateway de Aplicativo do Azure (versão prévia)

O Gateway de Aplicativo do Azure valida Tokens Web JSON (JWTs) emitidos pelo Microsoft Entra ID (antigo Azure Active Directory) em solicitações HTTPS de entrada. Essa funcionalidade fornece a imposição de autenticação de primeiro salto para APIs Web ou qualquer recurso protegido sem a necessidade de código personalizado em seus aplicativos de back-end.

Essa funcionalidade verifica a integridade e a autenticidade dos tokens em solicitações de entrada. Em seguida, ele determina se deseja permitir ou negar o acesso antes de encaminhar o tráfego para serviços de back-end. Após a validação bem-sucedida, o gateway injeta o x-msft-entra-identity cabeçalho na solicitação e o encaminha para o back-end. Os aplicativos downstream podem consumir com segurança informações de identidade verificadas.

Ao realizar a validação de token na borda, o Gateway de Aplicações simplifica a arquitetura das aplicações e reforça a segurança geral. A validação JWT é sem estado. Ou seja, cada solicitação deve apresentar um token válido para que o acesso seja concedido.

O Gateway de Aplicativo não mantém estado algum baseado em sessão ou em cookie. Essa abordagem ajuda a garantir a validação consistente entre solicitações e o alinhamento com princípios de Confiança Zero .

Importante

A validação JWT no Gateway de Aplicativo do Azure está atualmente em versão prévia. Essa versão prévia é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.

Principais capacidades

  • Validação de token: valida a assinatura, o emissor, o locatário, o público-alvo e o tempo de vida do JWT. Os tokens devem ser emitidos pela ID do Microsoft Entra.
  • Propagação de identidade: injeta o cabeçalho x-msft-entra-identity com tenantId:oid para o back-end.
  • Ações flexíveis: configura Deny (retornar o status 401) ou Allow (encaminhar sem cabeçalho de identidade) para tokens inválidos.
  • Suporte multilocatário: dá suporte a configurações de locatário comuns de organizações e consumidores.
  • Somente HTTPS: requer ouvintes HTTPS. Não há suporte para HTTP.

Diagrama mostrando a validação JWT para o Gateway de Aplicativo.

Pré-requisitos

  • Requisitos do Gateway de Aplicativo:

    • Standard_v2 ou WAF_v2 SKU. Não há suporte para o SKU Básico.
    • Ouvinte HTTPS, juntamente com a configuração de um certificado TLS/SSL.
    • API do Azure Resource Manager versão 2025-03-01 ou posterior.

  • Requisitos de rede:

    • Conectividade de saída da sub-rede do Gateway de Aplicativo com login.microsoftonline.com pela porta TCP 443.

  • Requisitos de ID do Microsoft Entra:

    • Registro da API Web no Microsoft Entra ID.
    • Uma chamada à ID do Microsoft Entra para solicitar acesso a um serviço. O Microsoft Entra ID responde com um token de acesso.

  • Configuração da validação JWT no Gateway de Aplicativo.

Registrar um aplicativo no Microsoft Entra ID

  1. No portal do Azure, acesse registros de aplicativo.

  2. Selecione Novo registro.

  3. Para Nome, insira MyWebAPI.

  4. Em Tipos de conta compatíveis, selecione Somente contas neste diretório organizacional (Somente Microsoft – Único locatário).

    Observação

    Os tipos de conta com suporte são:

    • Locatário único (somente este diretório)
    • Multilocatário (qualquer diretório do Microsoft Entra ID)
    • Contas em qualquer diretório do Microsoft Entra ID e contas pessoais da Microsoft

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

  6. Selecione Registrar.

  7. Anote os valores para ID do Aplicativo (cliente) e ID do Diretório (locatário).

  8. (Opcional) Configurar um URI de ID do aplicativo:

    1. Vá para Expor uma API>Definir o URI de ID do Aplicativo.
    2. Use o URI padrão api://<ClientID> ou personalizado (por exemplo, https://api.contoso.com).

  9. (Opcional) Definir escopos de API:

    • Vá para Expor uma API>Adicionar um escopo.

    Essa funcionalidade é para recursos futuros de autorização. Não é necessário para a visualização.

Configurar a validação JWT no Gateway de Aplicativo

  1. Abra o portal de configuração de visualização.

  2. Abra sua instância do Gateway de Aplicativo, vá para Configurações no menu à esquerda e selecione configurações de >Adicionar configuração de validação JWT.

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

  3. Forneça os seguintes detalhes:

    Configurações Example Description
    Nome jwt-policy-1 Nome amigável para a configuração de validação
    Solicitação não autorizada Deny Opção para rejeitar solicitações com JWTs ausentes ou inválidos
    ID do locatário <your-tenant-id> GUID válido ou um de common, organizations ou consumers
    ID do cliente <your-client-id> GUID do aplicativo registrado no Microsoft Entra
    Públicos-alvo <api://<client-id> (Opcional) Valores de declaração de públicos-alvo válidos adicionais (máximo 5)

  4. Associe a configuração a uma regra de roteamento, conforme descrito na seção a seguir, se você precisar de uma nova regra de roteamento.

Criar uma regra de roteamento (se necessário)

  1. Vá para Gateway de Aplicativo>Regras>Adicionar regra de roteamento.

  2. Insira ou selecione os seguintes itens:

    • Ouvinte: use o protocolo HTTPS, um certificado atribuído ou um segredo do Azure Key Vault.
    • Destino de backend: selecione ou crie um pool de backend.
    • Configurações de back-end: use uma porta HTTP/HTTPS apropriada.
    • Nome da regra: insira um nome como jwt-route-rule.

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

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

Enviar um token de acesso JWT com cada solicitação para o aplicativo seguro

Para acessar com segurança um aplicativo que o Gateway de Aplicativo ajuda a proteger, o cliente deve primeiro obter um token de acesso JWT do ponto de extremidade de token do Microsoft Entra ID. Em seguida, o cliente inclui esse token no cabeçalho de autorização (por exemplo, Authorization: Bearer TOKEN) em cada solicitação que ele envia ao Gateway de Aplicativo.

O Gateway de Aplicação valida o token antes de encaminhar a solicitação para o aplicativo de back-end. Essa validação garante que somente o tráfego autenticado e autorizado atinja o aplicativo seguro.

Para obter mais informações, consulte tokens do Access na plataforma de identidade da Microsoft.

Resultados esperados de solicitações

Scenario Status HTTP Cabeçalho de identidade Anotações
Token válido, action=Allow 200 Presente Token validado, identidade encaminhada
Token inválido, action=Deny 401 Ausente Gateway bloqueia solicitação
Token ausente, action=Deny 401 Ausente Nenhum cabeçalho de autorização
Ausência da declaração oid, action=Deny 403 Ausente Declaração crítica ausente

Verificação de backend

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

Solução de problemas de respostas 401 e 403

Se as solicitações retornarem um status 401 ou 403, verifique:

  • Configuration
    • A ID do locatário ou o emissor (iss) corresponde ao locatário do Microsoft Entra.
    • O público-alvo (aud) corresponde à lista de públicos-alvo ou ID de cliente configurada.
  • Integridade do token
    • O token não expirou (exp) e nbf não está no futuro.
  • Formatação de solicitação
    • Authorization: Bearer <access_token> o cabeçalho está presente e intacto.
  • Política de posicionamento de gateway
    • A validação JWT está anexada ao ouvinte e à regra de roteamento corretos.
  • Ainda falhando?
    • Adquira um novo token para o público-alvo correto.
    • Verifique os logs de acesso do Application Gateway para obter uma razão detalhada para a falha.

Conteúdo relacionado

Para saber mais sobre a validação JWT e os recursos de identidade relacionados no Azure:

  • Last updated on