Merge branch 'main' into reliability-az-latency

Author: johndowns

.openpublishing.redirection.json

@@ -422,7 +422,7 @@ Upon an application sign-out request, Azure AD B2C attempts to sign out from you
 
 ## Debug SAML protocol
 
-To help configure and debug federation with a SAML identity provider, you can use a browser extension for the SAML protocol, such as [SAML DevTools extension](https://chrome.google.com/webstore/detail/saml-devtools-extension/jndllhgbinhiiddokbeoeepbppdnhhio) for Chrome, [SAML-tracer](https://addons.mozilla.org/es/firefox/addon/saml-tracer/) for FireFox, or [Microsoft Edge or Internet Explorer developer tools](https://techcommunity.microsoft.com/t5/microsoft-sharepoint-blog/gathering-a-saml-token-using-edge-or-ie-developer-tools/ba-p/320957).
+To help configure and debug federation with a SAML identity provider, you can use a browser extension for the SAML protocol, such as [SAML DevTools extension](https://chrome.google.com/webstore/detail/saml-devtools-extension/jndllhgbinhiiddokbeoeepbppdnhhio) for Chrome, [SAML-tracer](https://addons.mozilla.org/es/firefox/addon/saml-tracer/) for Firefox, or [Microsoft Edge or Internet Explorer developer tools](https://techcommunity.microsoft.com/t5/microsoft-sharepoint-blog/gathering-a-saml-token-using-edge-or-ie-developer-tools/ba-p/320957).
 
 Using these tools, you can check the integration between Azure AD B2C and your SAML identity provider. For example:
 

articles/active-directory-b2c/identity-provider-generic-saml-options.md

@@ -165,7 +165,7 @@ Use **Run now** and `https://jwt.ms` to test your policies independently of your
 
 ## Troubleshoot SAML protocol
 
-To help configure and debug the integration with your service provider, you can use a browser extension for the SAML protocol, for example, [SAML DevTools extension](https://chrome.google.com/webstore/detail/saml-devtools-extension/jndllhgbinhiiddokbeoeepbppdnhhio) for Chrome, [SAML-tracer](https://addons.mozilla.org/es/firefox/addon/saml-tracer/) for FireFox, or [Edge or Internet Explorer developer tools](https://techcommunity.microsoft.com/t5/microsoft-sharepoint-blog/gathering-a-saml-token-using-edge-or-ie-developer-tools/ba-p/320957).
+To help configure and debug the integration with your service provider, you can use a browser extension for the SAML protocol, for example, [SAML DevTools extension](https://chrome.google.com/webstore/detail/saml-devtools-extension/jndllhgbinhiiddokbeoeepbppdnhhio) for Chrome, [SAML-tracer](https://addons.mozilla.org/es/firefox/addon/saml-tracer/) for Firefox, or [Edge or Internet Explorer developer tools](https://techcommunity.microsoft.com/t5/microsoft-sharepoint-blog/gathering-a-saml-token-using-edge-or-ie-developer-tools/ba-p/320957).
 
 The following screenshot demonstrates how the SAML DevTools extension presents the SAML request Azure AD B2C sends to the identity provider, and the SAML response.
 

articles/active-directory-b2c/troubleshoot.md

@@ -127,6 +127,7 @@ Configure the following policies to enable semantic caching for Azure OpenAI API
     <azure-openai-semantic-cache-lookup
         score-threshold="0.8"
         embeddings-backend-id="embeddings-deployment"
+        embeddings-backend-auth="system-assigned"
         ignore-system-messages="true"
         max-message-count="10">
         <vary-by>@(context.Subscription.Id)</vary-by>

articles/api-management/azure-openai-enable-semantic-caching.md

@@ -34,6 +34,7 @@ Use the `azure-openai-semantic-cache-lookup` policy to perform cache lookup of r
 <azure-openai-semantic-cache-lookup
     score-threshold="similarity score threshold"
     embeddings-backend-id ="backend entity ID for embeddings API"
+    embeddings-backend-auth ="system-assigned"             
     ignore-system-messages="true | false"      
     max-message-count="count" >
     <vary-by>"expression to partition caching"</vary-by>
@@ -46,6 +47,7 @@ Use the `azure-openai-semantic-cache-lookup` policy to perform cache lookup of r
 | ----------------- | ------------------------------------------------------ | -------- | ------- |
 | score-threshold	| Similarity score threshold used to determine whether to return a cached response to a prompt. Value is a decimal between 0.0 and 1.0. [Learn more](../azure-cache-for-redis/cache-tutorial-semantic-cache.md#change-the-similarity-threshold). | Yes |	N/A |
 | embeddings-backend-id | [Backend](backends.md) ID for OpenAI embeddings API call. |	Yes |	N/A |
+| embeddings-backend-auth | Authentication used for Azure OpenAI embeddings API backend. | Yes. Must be set to `system-assigned`. | N/A |
 | ignore-system-messages | Boolean. If set to `true`, removes system messages from a GPT chat completion prompt before assessing cache similarity. | No | false |
 | max-message-count | If specified, number of remaining dialog messages after which caching is skipped. | No | N/A |
                                              

articles/api-management/azure-openai-semantic-cache-lookup-policy.md

@@ -15,8 +15,6 @@ ms.date: 12/17/2021
 
 This article describes the steps for deploying the self-hosted gateway component of Azure API Management to a Kubernetes cluster and automatically send all metrics to an [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/).
 
-[!INCLUDE [preview](./includes/preview/preview-callout-self-hosted-gateway-opentelemetry.md)]
-
 You learn how to:
 
 > [!div class="checklist"]
@@ -35,8 +33,6 @@ You learn how to:
 
 [OpenTelemetry](https://opentelemetry.io/) is a set of open-source tools and frameworks for logging, metrics, and tracing in a vendor-neutral way.
 
-[!INCLUDE [preview](./includes/preview/preview-callout-self-hosted-gateway-opentelemetry.md)]
-
 The self-hosted gateway can be configured to automatically collect and send metrics to an [OpenTelemetry Collector](https://opentelemetry.io/docs/concepts/components/#collector). This allows you to bring your own metrics collection and reporting solution for the self-hosted gateway.
 
 > [!NOTE]

articles/api-management/how-to-deploy-self-hosted-gateway-kubernetes-opentelemetry.md

@@ -34,6 +34,7 @@ Use the `llm-semantic-cache-lookup` policy to perform cache lookup of responses
 <llm-semantic-cache-lookup
     score-threshold="similarity score threshold"
     embeddings-backend-id ="backend entity ID for embeddings API"
+    embeddings-backend-auth ="system-assigned"             
     ignore-system-messages="true | false"      
     max-message-count="count" >
     <vary-by>"expression to partition caching"</vary-by>
@@ -46,6 +47,7 @@ Use the `llm-semantic-cache-lookup` policy to perform cache lookup of responses
 | ----------------- | ------------------------------------------------------ | -------- | ------- |
 | score-threshold	| Similarity score threshold used to determine whether to return a cached response to a prompt. Value is a decimal between 0.0 and 1.0. [Learn more](../azure-cache-for-redis/cache-tutorial-semantic-cache.md#change-the-similarity-threshold). | Yes |	N/A |
 | embeddings-backend-id | [Backend](backends.md) ID for OpenAI embeddings API call. |	Yes |	N/A |
+| embeddings-backend-auth | Authentication used for Azure OpenAI embeddings API backend. | Yes. Must be set to `system-assigned`. | N/A |
 | ignore-system-messages | Boolean. If set to `true`, removes system messages from a GPT chat completion prompt before assessing cache similarity. | No | false |
 | max-message-count | If specified, number of remaining dialog messages after which caching is skipped. | No | N/A |
                                              

articles/api-management/includes/preview/preview-callout-self-hosted-gateway-opentelemetry.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/llm-semantic-cache-lookup-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