Merge pull request #293643 from dlepow/keys

[APIM] Token validation and decryption key example

Author: prmerger-automator[bot]

articles/api-management/validate-azure-ad-token-policy.md

@@ -6,7 +6,7 @@ author: dlepow
 
 ms.service: azure-api-management
 ms.topic: article
-ms.date: 07/23/2024
+ms.date: 01/29/2025
 ms.author: danlep
 ---
 
@@ -17,7 +17,7 @@ ms.author: danlep
 The `validate-azure-ad-token` policy enforces the existence and validity of a JSON web token (JWT) that was provided by the Microsoft Entra (formerly called Azure Active Directory) service for a specified set of principals in the directory. The JWT can be extracted from a specified HTTP header, query parameter, or value provided using a policy expression or context variable.
 
 > [!NOTE]
-> To validate a JWT that was provided by an identity provider other than Microsoft Entra, API Management also provides the generic [`validate-jwt`](validate-jwt-policy.md) policy. 
+> Use the generic [`validate-jwt`](validate-jwt-policy.md) policy to validate a JWT that was provided by an identity provider other than Microsoft Entra. 
 
 [!INCLUDE [api-management-policy-generic-alert](../../includes/api-management-policy-generic-alert.md)]
 
@@ -33,24 +33,23 @@ The `validate-azure-ad-token` policy enforces the existence and validity of a JS
     failed-validation-httpcode="HTTP status code to return on failure"
     failed-validation-error-message="error message to return on failure"
     output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
-    <client-application-ids>
-        <application-id>Client application ID from Microsoft Entra</application-id>
-        <!-- If there are multiple client application IDs, then add additional application-id elements -->
-    </client-application-ids>
     <backend-application-ids>
         <application-id>Backend application ID from Microsoft Entra</application-id>
         <!-- If there are multiple backend application IDs, then add additional application-id elements -->
     </backend-application-ids>
+    <client-application-ids>
+        <application-id>Client application ID from Microsoft Entra</application-id>
+        <!-- If there are multiple client application IDs, then add additional application-id elements -->
+    </client-application-ids>
     <audiences>
         <audience>audience string</audience>
         <!-- if there are multiple possible audiences, then add additional audience elements -->
     </audiences>
     <required-claims>
-        <claim name="name of the claim as it appears in the token" match="all|any" separator="separator character in a multi-valued claim">
+        <claim name="name of the claim as it appears in the token" match="all | any" separator="separator character in a multi-valued claim">
             <value>claim value as it is expected to appear in the token</value>
             <!-- if there is more than one allowed value, then add additional value elements -->
         </claim>
-        <!-- if there are multiple possible allowed values, then add additional value elements -->
     </required-claims>
     <decryption-keys>
         <key certificate-id="mycertificate"/>
@@ -75,9 +74,9 @@ The `validate-azure-ad-token` policy enforces the existence and validity of a JS
 
 | Element             | Description                                                                                                                                                                                                                                                                                                                                           | Required |
 | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
-| audiences           | Contains a list of acceptable audience claims that can be present on the token. If multiple `audience` values are present, then each value is tried until either all are exhausted (in which case validation fails) or until one succeeds. Policy expressions are allowed.                                                                    | No       |
 | backend-application-ids | Contains a list of acceptable backend application IDs.  This is only required in advanced cases for the configuration of options and can generally be removed. Policy expressions aren't allowed. | No |
 | client-application-ids | Contains a list of acceptable client application IDs. If multiple `application-id` elements are present, then each value is tried until either all are exhausted (in which case validation fails) or until one succeeds. If a client application ID isn't provided, one or more `audience` claims should be specified. Policy expressions aren't allowed. | No |
+| audiences           | Contains a list of acceptable audience claims that can be present on the token. If multiple `audience` values are present, then each value is tried until either all are exhausted (in which case validation fails) or until one succeeds. Policy expressions are allowed.                                                                    | No       |
 | required-claims     | Contains a list of `claim` elements for claim values expected to be present on the token for it to be considered valid. When the `match` attribute is set to `all`, every claim value in the policy must be present in the token for validation to succeed. When the `match` attribute is set to `any`, at least one claim must be present in the token for validation to succeed. Policy expressions are allowed. | No       |
 | decryption-keys     | A list of [`key`](#key-attributes) subelements, used to decrypt a token signed with an asymmetric key. If multiple keys are present, then each key is tried until either all keys are exhausted (in which case validation fails) or a key succeeds.<br/><br/>Specify the public key using a `certificate-id` attribute with value set to the identifier of a certificate uploaded to API Management.         | No       |
 
@@ -109,7 +108,7 @@ The `validate-azure-ad-token` policy enforces the existence and validity of a JS
 
 ### Simple token validation
 
-The following policy is the minimal form of the `validate-azure-ad-token` policy.  It expects the JWT to be provided in the default `Authorization` header using the `Bearer` scheme. In this example, the Microsoft Entra tenant ID and client application ID are provided using named values.
+The following policy is the minimal form of the `validate-azure-ad-token` policy. It expects the JWT to be provided in the default `Authorization` header using the `Bearer` scheme. In this example, the Microsoft Entra tenant ID and client application ID are provided using named values.
 
 ```xml
 <validate-azure-ad-token tenant-id="{{aad-tenant-id}}">
@@ -119,6 +118,21 @@ The following policy is the minimal form of the `validate-azure-ad-token` policy
 </validate-azure-ad-token>
 ```
 
+### Token validation using decryption key
+
+This example shows how to use the `validate-azure-ad-token` policy to validate a token that is decrypted using a decryption key. The Microsoft Entra tenant ID and client application ID are provided using named values. The key is specified using the ID of an uploaded certificate (in PFX format) that contains the public key.
+
+```xml
+<validate-azure-ad-token tenant-id="{{aad-tenant-id}}">
+    <client-application-ids>
+        <application-id>{{aad-client-application-id}}</application-id>
+    </client-application-ids>
+    <decryption-keys>
+        <key certificate-id="mycertificate"/>
+    </decryption-keys>
+</validate-azure-ad-token>
+```
+
 ### Validate that audience and claim are correct
 
 The following policy checks that the audience is the hostname of the API Management instance and that the `ctry` claim is `US`. The Microsoft tenant ID is the well-known `organizations` tenant, which allows tokens from accounts in any organizational directory. The hostname is provided using a policy expression, and the client application ID is provided using a named value. The decoded JWT is provided in the `jwt` variable after validation.

articles/api-management/validate-jwt-policy.md

@@ -6,18 +6,18 @@ author: dlepow
 
 ms.service: azure-api-management
 ms.topic: article
-ms.date: 09/27/2024
+ms.date: 01/27/2025
 ms.author: danlep
 ---
 
 # Validate JWT
 
 [!INCLUDE [api-management-availability-all-tiers](../../includes/api-management-availability-all-tiers.md)]
 
-The `validate-jwt` policy enforces existence and validity of a supported JSON web token (JWT) extracted from a specified HTTP header, extracted from a specified query parameter, or matching a specific value.
+The `validate-jwt` policy enforces existence and validity of a supported JSON web token (JWT) that was provided by an identity provider. The JWT can be extracted from a specified HTTP header, extracted from a specified query parameter, or matching a specific value.
 
 > [!NOTE]
->  To validate a JWT that was provided by the Microsoft Entra service, API Management also provides the [`validate-azure-ad-token`](validate-azure-ad-token-policy.md) policy. 
+>  Use the [`validate-azure-ad-token`](validate-azure-ad-token-policy.md) policy to validate a JWT that was provided by Microsoft Entra. 
 
 [!INCLUDE [api-management-policy-form-alert](../../includes/api-management-policy-form-alert.md)]
 
@@ -206,6 +206,32 @@ The `validate-jwt` policy enforces existence and validity of a supported JSON we
 </validate-jwt>
 ```
 
+### Token validation using decryption key
+
+This example shows how to use the `validate-jwt` policy to validate a token that is decrypted using a decryption key. The key is specified using the ID of an uploaded certificate (in PFX format) that contains the public key.
+
+```xml
+<validate-jwt header-name="Authorization" require-scheme="Bearer" output-token-variable-name="jwt">
+    <issuer-signing-keys>
+        <key>{{jwt-signing-key}}</key> <!-- signing key is stored in a named value -->
+    </issuer-signing-keys>
+    <audiences>
+        <audience>@(context.Request.OriginalUrl.Host)</audience>
+    </audiences>
+    <issuers>
+        <issuer>contoso.com</issuer>
+    </issuers>
+    <required-claims>
+        <claim name="group" match="any">
+            <value>finance</value>
+            <value>logistics</value>
+        </claim>
+    </required-claims>
+    <decryption-keys>
+        <key certificate-id="my-certificate-in-api-management" /> <!-- decryption key specified as certificate ID -->
+    </decryption-keys>
+</validate-jwt>
+```
 
 ### Authorize access to operations based on token claims