Skip to content

Commit 0066eec

Browse files
jmart1428jmart1428
authored
Merge pull request #309848 from ShawnJackson/jwt-validation-azure-application-gateway
[AQ] edit pass: Article about JWT validation in Azure Application Gateway
2 parents 2d3d961 + ad88031 commit 0066eec

1 file changed

Lines changed: 95 additions & 100 deletions

File tree

‎articles/application-gateway/json-web-token-overview.md‎

Lines changed: 95 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: JSON Web Token (JWT) validation in Azure Application Gateway (Preview)
2+
title: JSON Web Token (JWT) Validation in Azure Application Gateway (Preview)
33
titleSuffix: Azure Application Gateway
44
description: Learn how to configure JSON Web Token (JWT) validation in Azure Application Gateway to enforce authentication and authorization policies.
55
author: rnautiyal
@@ -9,158 +9,153 @@ ms.topic: article
99
ms.date: 11/18/2025
1010
---
1111

12-
# JSON Web Token (JWT) validation in Azure Application Gateway (Preview)
12+
# JSON Web Token (JWT) validation in Azure Application Gateway (preview)
1313

14-
The Microsoft Entra JSON Web Tokens (JWTs) feature enables [Azure Application Gateway](/azure/application-gateway/) to validate JSON Web Tokens (JWTs) issued by [Microsoft Entra ID](https://docs.azure.cn/en-us/entra/fundamentals/what-is-entra) (formerly Azure Active Directory) in incoming HTTPS requests. This provides first-hop authentication enforcement for Web APIs or any protected resource without requiring custom code in your backend applications. This capability verifies the integrity and authenticity of tokens in incoming requests and determines whether to allow or deny access before forwarding traffic to backend services. Upon successful validation, the gateway injects the ``x-msft-entra-identity`` header into the request and forwards it to the backend, enabling downstream applications to securely consume verified identity information
14+
[Azure Application Gateway](/azure/application-gateway/) validates JSON Web Tokens (JWTs) issued by [Microsoft Entra ID](https://docs.azure.cn/en-us/entra/fundamentals/what-is-entra) (formerly Azure Active Directory) in incoming HTTPS requests. This capability provides first-hop authentication enforcement for web APIs or any protected resource without requiring custom code in your backend applications.
1515

16-
By performing token validation at the edge, Application Gateway simplifies application architecture and strengthens overall security posture. JWT validation is stateless, meaning each request must present a valid token for access to be granted. No session or cookie-based state is maintained, ensuring consistent validation across requests and alignment with [Zero Trust](/security/zero-trust/zero-trust-overview) principles.
16+
This capability verifies the integrity and authenticity of tokens in incoming requests. It then determines whether to allow or deny access before forwarding traffic to backend services. Upon successful validation, the gateway injects the `x-msft-entra-identity` header into the request and forwards it to the backend. Downstream applications can then securely consume verified identity information.
17+
18+
By performing token validation at the edge, Application Gateway simplifies application architecture and strengthens overall security posture. JWT validation is stateless. That is, each request must present a valid token for access to be granted.
19+
20+
Application Gateway doesn't maintain any session or cookie-based state. This approach helps ensure consistent validation across requests and alignment with [Zero Trust](/security/zero-trust/zero-trust-overview) principles.
1721

1822
> [!IMPORTANT]
19-
> JWT validation in Azure Application Gateway is currently in **Public Preview**. This preview version is provided without a service level agreement, and isn't recommended for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
23+
> JWT validation in Azure Application Gateway is currently in preview. This preview version is provided without a service-level agreement, and we don't recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
2024
2125
## Key capabilities
2226

23-
- Token Validation: Validates JWT signature, issuer, tenant, audience, and lifetime
24-
- Identity Propagation: Injects `x-msft-entra-identity` header with tenantId:oid to backend
25-
- Flexible Actions: Configure Deny (return 401) or Allow (forward without identity header) for invalid tokens
26-
- Multitenant Support: Supports common, organizations, and consumers tenant configurations
27-
- HTTPS Only: Feature requires HTTPS listeners (HTTP not supported)
28-
29-
> [!NOTE]
30-
> Tokens must be issued by Microsoft Entra ID
27+
- **Token validation**: Validates JWT signature, issuer, tenant, audience, and lifetime. Tokens must be issued by Microsoft Entra ID.
28+
- **Identity propagation**: Injects the `x-msft-entra-identity` header with `tenantId:oid` to the backend.
29+
- **Flexible actions**: Configures `Deny` (return 401 status) or `Allow` (forward without identity header) for invalid tokens.
30+
- **Multitenant support**: Supports common organizations and consumers' tenant configurations.
31+
- **HTTPS only**: Requires HTTPS listeners. HTTP isn't supported.
3132

3233
## Prerequisites
3334

34-
- **Application Gateway Requirements**
35-
- SKU: Standard_v2 or WAF_v2 (Basic SKU not supported)
36-
- Protocol: HTTPS listener required (TLS/SSL certificate is configured)
37-
- API Version: Azure Resource Manager API version 2025-03-01 or later
35+
- Application Gateway requirements:
36+
- Standard_v2 or WAF_v2 SKU. The Basic SKU isn't supported.
37+
- HTTPS listener, along with configuration of a TLS/SSL certificate.
38+
- Azure Resource Manager API version 2025-03-01 or later.
3839

39-
- **Network Requirements**
40-
- Outbound Connectivity from Application Gateway Subnet to login.microsoftonline.com over TCP port 443
40+
- Network requirements:
41+
- Outbound connectivity from the Application Gateway subnet to `login.microsoftonline.com` over TCP port 443.
4142

43+
- Microsoft Entra ID requirements:
44+
- Registration of your web API in Microsoft Entra ID.
45+
- A call to Microsoft Entra ID to request access to a service. Microsoft Entra ID responds with an access token.
4246

43-
- **Microsoft Entra ID Requirements**
44-
- Register your Web API in Microsoft Entra ID
45-
- Make a call to the Microsoft Entra ID to request access to a service. The Microsoft Entra ID responds with an access token.
47+
- Configuration of JWT validation in Application Gateway.
4648

47-
- **Configure JWT validation in Application Gateway**
48-
49-
49+
## Register an application in Microsoft Entra ID
5050

51-
## JSON Web Token (JWT) validation setup
51+
1. In the Azure portal, go to [App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade).
5252

53-
In this section, you learn how to configure JWT validation in Azure Application Gateway:
53+
1. Select **New registration**.
5454

55-
## Register an application in Microsoft Entra ID
55+
1. For **Name**, enter **MyWebAPI**.
5656

57-
1. Go to [Azure portal App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade).
58-
1. Select **New registration**.
59-
1. Enter:
60-
- **Name:** `MyWebAPI`
61-
- **Supported account types:** *Accounts in this organizational directory only* (Microsoft only - Single Tenant).
62-
1. Redirect URI: Not required for API scenarios
63-
1. Select **Register**.
64-
1. Note down:
65-
- **Application (client) ID** → `CLIENT_ID`
66-
- **Directory (tenant) ID** → `TENANT_ID`.
67-
1. **(Optional) Configure App ID URI**:
68-
- Go to **Expose an API** → **Set** Application ID URI
69-
- Use default `api://<ClientID>` or custom URI (for example, `https://api.contoso.com`)
70-
71-
1. **(Optional) Define API Scopes**:
72-
- Go to **Expose an API** → **Add a scope**
73-
- This is for future authorization features (not required for Public Preview)
74-
75-
> [!NOTE]
76-
> Supported account types:
77-
> Single tenant (This directory only)
78-
>
79-
> Multitenant (Any Azure AD directory)
80-
>
81-
> Accounts in any Azure AD directory + personal Microsoft accounts
57+
1. For **Supported account types**, select **Accounts in this organizational directory only (Microsoft only - Single tenant)**.
8258

59+
> [!NOTE]
60+
> Supported account types are:
61+
>
62+
> - Single tenant (this directory only)
63+
> - Multitenant (any Microsoft Entra ID directory)
64+
> - Accounts in any Microsoft Entra ID directory and personal Microsoft accounts
8365
84-
## Configure JWT validation in Application Gateway
66+
1. For **Redirect URI (optional)**, you can leave the boxes blank. This setting isn't required for API scenarios.
67+
68+
1. Select **Register**.
8569

86-
1. Open the preview configuration portal:
87-
[App Gateway JWT Config Portal](https://ms.portal.azure.com/?feature.applicationgatewayjwtvalidation=true#home)
70+
1. Note down the values for **Application (client) ID** and **Directory (tenant) ID**.
8871

89-
1. Open your Application Gateway, navigate to Settings in the left menu, and select the **JWT validation configuration** window.
72+
1. (Optional) Configure an application ID URI:
9073

91-
:::image type="content" source="media/json-web-token-overview/json-web-token-configuration.png" alt-text="Screenshot of JSON Web Token configuration window for Application Gateway.":::
74+
1. Go to **Expose an API** > **Set Application ID URI**.
75+
1. Use the default `api://<ClientID>` or a custom URI (for example, `https://api.contoso.com`).
9276

93-
1. Provide the following details:
77+
1. (Optional) Define API scopes:
9478

95-
| Field | Example | Description |
96-
| ------------------------ | ------------------------------ | ------------------------------------------------------------------------ |
97-
| **Name** | `jwt-policy-1` | Friendly name for the validation configuration |
98-
| **Unauthorized Request** | `Deny` | Reject requests with missing or invalid JWTs |
99-
| **Tenant ID** | `<your-tenant-id>` | Must be a valid GUID or one of `common`, `organizations`, or `consumers` |
100-
| **Client ID** | `<your-client-id>` | GUID of the app registered in Microsoft Entra |
101-
| **Audiences** | `<api://<client-id>` | (Optional) Additional valid aud claim values (max 5) |
79+
- Go to **Expose an API** > **Add a scope**.
10280

81+
This capability is for future authorization features. It's not required for the preview.
10382

104-
1. Associate the configuration with a **Routing rule** (see next section if new routing rule is needed).
83+
## Configure JWT validation in Application Gateway
84+
85+
1. Open the [preview configuration portal](https://ms.portal.azure.com/?feature.applicationgatewayjwtvalidation=true#home).
86+
87+
1. Open your Application Gateway instance, go to **Settings** on the left menu, and then select **JWT validation configurations** > **Add JWT validation configuration**.
88+
89+
:::image type="content" source="media/json-web-token-overview/json-web-token-configuration.png" alt-text="Screenshot of the pane for updating JSON Web Token configuration for Application Gateway.":::
10590

91+
1. Provide the following details:
10692

107-
## Create a routing rule (if needed)
93+
| Setting | Example | Description |
94+
| ------- | ------- | ----------- |
95+
| **Name** | `jwt-policy-1` | Friendly name for the validation configuration |
96+
| **Unauthorized Request** | `Deny` | Option to reject requests with missing or invalid JWTs |
97+
| **Tenant ID** | `<your-tenant-id>` | Valid GUID or one of `common`, `organizations`, or `consumers` |
98+
| **Client ID** | `<your-client-id>` | GUID of the app registered in Microsoft Entra |
99+
| **Audiences** | `<api://<client-id>` | (Optional) Additional valid audience claim values (maximum 5) |
108100

109-
1. Go to **Application Gateway -> Rules -> Add Routing rule**
101+
1. Associate the configuration with a routing rule as described in the following section, if you need a new routing rule.
110102

111-
1. Enter or select the following:
112-
- **Listener:** Protocol `HTTPS`, assign certificate, or Key Vault secret.
113-
- **Backend target:** Select or create a backend pool.
114-
- **Backend settings:** Use appropriate HTTP/HTTPS port.
115-
- **Rule name:** For example, `jwt-route-rule`.
103+
## Create a routing rule (if necessary)
116104

117-
1. Link this rule to your JWT validation configuration. Your JWT validation configuration is now attached to a secure HTTPS listener and routing rule.
105+
1. Go to **Application Gateway** > **Rules** > **Add Routing rule**.
118106

107+
1. Enter or select the following items:
108+
- **Listener**: Use the protocol `HTTPS`, an assigned certificate, or an Azure Key Vault secret.
109+
- **Backend target**: Select or create a backend pool.
110+
- **Backend settings**: Use an appropriate HTTP/HTTPS port.
111+
- **Rule name**: Enter a name such as `jwt-route-rule`.
119112

120-
## Send a JWT Access Token with Every Request to the Secure Application
113+
1. Link this rule to your JWT validation configuration.
121114

122-
To securely access an application protected by Application Gateway, the client must first obtain a JWT access token from the Microsoft Entra ID token endpoint. The client then includes this token in the Authorization header (for example, Authorization: Bearer TOKEN) on every request it sends to the Application Gateway. Application Gateway validates the token before forwarding the request to the backend application, ensuring that only authenticated and authorized traffic reaches the secure application.
115+
Your JWT validation configuration is now attached to a secure HTTPS listener and routing rule.
123116

124-
- Learn more about [Access tokens in the Microsoft identity platform](/entra/identity-platform/access-tokens)
117+
## Send a JWT access token with every request to the secure application
125118

119+
To securely access an application that Application Gateway helps protect, the client must first obtain a JWT access token from the Microsoft Entra ID token endpoint. The client then includes this token in the authorization header (for example, `Authorization: Bearer TOKEN`) on every request that it sends to Application Gateway.
126120

121+
Application Gateway validates the token before forwarding the request to the backend application. This validation ensures that only authenticated and authorized traffic reaches the secure application.
127122

128-
## Expected Outcomes of requests
123+
For more information, see [Access tokens in the Microsoft identity platform](/entra/identity-platform/access-tokens).
129124

130-
| Scenario | HTTP Status | Identity Header | Notes |
131-
| -------------------------------- | ----------- | --------------- | ----------------------------------- |
132-
| Valid token, action=Allow | 200 | Present | Token validated, identity forwarded |
133-
| Invalid token, action=Deny | 401 | Absent | Gateway blocks request |
134-
| Missing token, action=Deny | 401 | Absent | No Authorization header |
135-
| Missing `oid` claim, action=Deny | 403 | Absent | Critical claim missing |
125+
## Expected outcomes of requests
136126

137-
## Backend Verification
127+
| Scenario | HTTP status | Identity header | Notes |
128+
| -------- | ----------- | --------------- |------ |
129+
| Valid token, `action=Allow` | 200 | Present | Token validated, identity forwarded |
130+
| Invalid token, `action=Deny` | 401 | Absent | Gateway blocks request |
131+
| Missing token, `action=Deny` | 401 | Absent | No authorization header |
132+
| Missing `oid` claim, `action=Deny` | 403 | Absent | Critical claim missing |
138133

139-
Check ``x-msft-entra-identity`` header to confirm authentication.
134+
## Backend verification
135+
136+
Check the `x-msft-entra-identity` header to confirm authentication.
140137

141138
## Troubleshooting 401 and 403 responses
142139

143-
If requests return **401** or **403**, verify:
140+
If requests return a status of 401 or 403, verify:
144141

145142
- **Configuration**
146-
- Tenant ID / Issuer (`iss`) matches your Microsoft Entra tenant.
147-
- Audience (`aud`) matches the configured Client ID or audience list.
143+
- Tenant ID or issuer (`iss`) matches your Microsoft Entra tenant.
144+
- Audience (`aud`) matches the configured client ID or audience list.
148145
- **Token integrity**
149-
- Token isn't expired (`exp`) and `nbf` isn't in the future.
146+
- Token isn't expired (`exp`) and `nbf` isn't in the future.
150147
- **Request formatting**
151-
- `Authorization: Bearer <access_token>` header is present and intact.
148+
- `Authorization: Bearer <access_token>` header is present and intact.
152149
- **Gateway policy placement**
153-
- JWT validation is attached to the correct listener and routing rule.
150+
- JWT validation is attached to the correct listener and routing rule.
154151
- **Still failing?**
155-
- Acquire a new token for the correct audience.
156-
- Check Application Gateway access logs for detailed failure reason.
157-
158-
152+
- Acquire a new token for the correct audience.
153+
- Check Application Gateway access logs for a detailed failure reason.
159154

160-
## Next steps
155+
## Related content
161156

162157
To learn more about JWT validation and related identity features in Azure:
163158

164-
- [Understand JSON Web Tokens (JWT) in Microsoft Entra ID](/entra/identity-platform/security-tokens)
159+
- [Tokens and claims overview](/entra/identity-platform/security-tokens)
165160
- [Register an application in Microsoft Entra ID](/entra/identity-platform/quickstart-register-app)
166-
- [Azure Application Gateway overview](overview.md)
161+
- [Azure Application Gateway overview](overview.md)

0 commit comments

Comments
 (0)