Skip to content

Commit 5df8698

Browse files
ShawnJacksonShawnJackson
committed
edit pass: jwt-validation-azure-application-gateway
1 parent 636d868 commit 5df8698

1 file changed

Lines changed: 47 additions & 45 deletions

File tree

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

Lines changed: 47 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,9 @@ Application Gateway doesn't maintain any session or cookie-based state. This app
2626

2727
- **Token validation**: Validates JWT signature, issuer, tenant, audience, and lifetime. Tokens must be issued by Microsoft Entra ID.
2828
- **Identity propagation**: Injects the `x-msft-entra-identity` header with `tenantId:oid` to the backend.
29-
- **Flexible actions**: Configures `Deny` (return 401) or `Allow` (forward without identity header) for invalid tokens.
29+
- **Flexible actions**: Configures `Deny` (return 401 status) or `Allow` (forward without identity header) for invalid tokens.
3030
- **Multitenant support**: Supports common organizations and consumers' tenant configurations.
31-
- **HTTPS only**: Requires HTTPS listeners. (HTTP isn't supported.)
31+
- **HTTPS only**: Requires HTTPS listeners. HTTP isn't supported.
3232

3333
## Prerequisites
3434

@@ -41,8 +41,8 @@ Application Gateway doesn't maintain any session or cookie-based state. This app
4141
- Outbound connectivity from the Application Gateway subnet to `login.microsoftonline.com` over TCP port 443.
4242

4343
- Microsoft Entra ID requirements:
44-
- Register your web API in Microsoft Entra ID.
45-
- Make a call to Microsoft Entra ID to request access to a service. Microsoft Entra ID responds with an access token.
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.
4646

4747
- Configuration of JWT validation in Application Gateway.
4848

@@ -56,6 +56,13 @@ Application Gateway doesn't maintain any session or cookie-based state. This app
5656

5757
1. For **Supported account types**, select **Accounts in this organizational directory only (Microsoft only - Single tenant)**.
5858

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
65+
5966
1. For **Redirect URI (optional)**, you can leave the boxes blank. This setting isn't required for API scenarios.
6067

6168
1. Select **Register**.
@@ -71,75 +78,70 @@ Application Gateway doesn't maintain any session or cookie-based state. This app
7178

7279
- Go to **Expose an API** > **Add a scope**.
7380

74-
This is for future authorization features (not required for Public Preview)
75-
76-
> [!NOTE]
77-
> Supported account types are:
78-
>
79-
> Single tenant (This directory only)
80-
>
81-
> Multitenant (Any Azure AD directory)
82-
>
83-
> Accounts in any Azure AD directory + personal Microsoft accounts
81+
This capability is for future authorization features. It's not required for the preview.
8482

8583
## Configure JWT validation in Application Gateway
8684

8785
1. Open the [preview configuration portal](https://ms.portal.azure.com/?feature.applicationgatewayjwtvalidation=true#home).
8886

89-
1. Open your Application Gateway, navigate to Settings in the left menu, and select the **JWT validation configuration** window.
87+
1. Open your Application Gateway instance, go to **Settings** on the left menu, and then select **JWT validation configurations**.
9088

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.":::
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.":::
9290

9391
1. Provide the following details:
9492

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) |
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) |
102100

103-
1. Associate the configuration with a **Routing rule** (see next section if new routing rule is needed).
101+
1. Associate the configuration with a routing rule as described in the following section, if you need a new routing rule.
104102

105-
## Create a routing rule (if needed)
103+
## Create a routing rule (if necessary)
106104

107105
1. Go to **Application Gateway** > **Rules** > **Add Routing rule**.
108106

109-
1. Enter or select the following:
110-
- **Listener:** Protocol `HTTPS`, assign certificate, or Key Vault secret.
111-
- **Backend target:** Select or create a backend pool.
112-
- **Backend settings:** Use appropriate HTTP/HTTPS port.
113-
- **Rule name:** For example, `jwt-route-rule`.
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`.
114112

115-
1. Link this rule to your JWT validation configuration. Your JWT validation configuration is now attached to a secure HTTPS listener and routing rule.
113+
1. Link this rule to your JWT validation configuration.
114+
115+
Your JWT validation configuration is now attached to a secure HTTPS listener and routing rule.
116116

117117
## Send a JWT access token with every request to the secure application
118118

119-
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 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.
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.
120+
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.
120122

121-
Learn more about [Access tokens in the Microsoft identity platform](/entra/identity-platform/access-tokens).
123+
For more information, see [Access tokens in the Microsoft identity platform](/entra/identity-platform/access-tokens).
122124

123125
## Expected outcomes of requests
124126

125-
| Scenario | HTTP Status | Identity Header | Notes |
126-
| -------------------------------- | ----------- | --------------- | ----------------------------------- |
127-
| Valid token, action=Allow | 200 | Present | Token validated, identity forwarded |
128-
| Invalid token, action=Deny | 401 | Absent | Gateway blocks request |
129-
| Missing token, action=Deny | 401 | Absent | No Authorization header |
130-
| Missing `oid` claim, action=Deny | 403 | Absent | Critical claim missing |
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 |
131133

132134
## Backend verification
133135

134-
Check ``x-msft-entra-identity`` header to confirm authentication.
136+
Check the `x-msft-entra-identity` header to confirm authentication.
135137

136138
## Troubleshooting 401 and 403 responses
137139

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

140142
- **Configuration**
141-
- Tenant ID / Issuer (`iss`) matches your Microsoft Entra tenant.
142-
- 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.
143145
- **Token integrity**
144146
- Token isn't expired (`exp`) and `nbf` isn't in the future.
145147
- **Request formatting**
@@ -148,12 +150,12 @@ If requests return **401** or **403**, verify:
148150
- JWT validation is attached to the correct listener and routing rule.
149151
- **Still failing?**
150152
- Acquire a new token for the correct audience.
151-
- Check Application Gateway access logs for detailed failure reason.
153+
- Check Application Gateway access logs for a detailed failure reason.
152154

153155
## Related content
154156

155157
To learn more about JWT validation and related identity features in Azure:
156158

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

0 commit comments

Comments
 (0)