Merge pull request #2721 from MicrosoftDocs/main

Publish to live, Tuesday 4 AM PST, 2/4

Author: ttorble

articles/ai-foundry/model-inference/includes/configure-entra-id/bicep.md

@@ -100,6 +100,10 @@ Once you configured Microsoft Entra ID in your resource, you need to update your
 
 [!INCLUDE [about-credentials](about-credentials.md)]
 
+## Troubleshooting
+
+[!INCLUDE [troubleshooting](troubleshooting.md)]
+
 ## Disable key-based authentication in the resource
 
 Disabling key-based authentication is advisable when you implemented Microsoft Entra ID and fully addressed compatibility or fallback concerns in all the applications that consume the service. You can achieve it by changing the property `disableLocalAuth`:

articles/ai-foundry/model-inference/includes/configure-entra-id/cli.md

@@ -89,4 +89,8 @@ Once Microsoft Entra ID is configured in your resource, you need to update your
 
 [!INCLUDE [code](../code-create-chat-client-entra.md)]
 
-[!INCLUDE [about-credentials](about-credentials.md)]
+[!INCLUDE [about-credentials](about-credentials.md)]
+
+## Troubleshooting
+
+[!INCLUDE [troubleshooting](troubleshooting.md)]

articles/ai-foundry/model-inference/includes/configure-entra-id/portal.md

@@ -48,7 +48,6 @@ Follow these steps to configure Microsoft Entra ID for inference:
 
 Notice that key-based access is still possible for users that already have keys available to them. If you want to revoke the keys, in the Azure portal, on the left navigation, select **Resource Management** > **Keys and Endpoints** > **Regenerate Key1** and **Regenerate Key2**.
 
-
 ## Use Microsoft Entra ID in your code
 
 Once you configured Microsoft Entra ID in your resource, you need to update your code to use it when consuming the inference endpoint. The following example shows how to use a chat completions model:
@@ -57,6 +56,10 @@ Once you configured Microsoft Entra ID in your resource, you need to update your
 
 [!INCLUDE [about-credentials](about-credentials.md)]
 
+## Troubleshooting
+
+[!INCLUDE [troubleshooting](troubleshooting.md)]
+
 ## Use Microsoft Entra ID in your project
 
 Even when your resource has Microsoft Entra ID configured, your projects may still be using keys to consume predictions from the resource. When using the Azure AI Foundry playground, the credentials associated with the connection your project has are used. 
@@ -79,7 +82,6 @@ To change this behavior, you have to update the connections from your projects t
 
 7. Your connection is configured to work with Microsoft Entra ID now.
 
-
 ## Disable key-based authentication in the resource
 
 Disabling key-based authentication is advisable when you implemented Microsoft Entra ID and fully addressed compatibility or fallback concerns in all the applications that consume the service.

articles/ai-foundry/model-inference/includes/configure-entra-id/troubleshooting.md

@@ -0,0 +1,20 @@
+---
+manager: nitinme
+author: santiagxf
+ms.author: fasantia 
+ms.service: azure-ai-model-inference
+ms.date: 01/23/2025
+ms.topic: include
+---
+
+The following table contains multiple scenarios that can help troubleshooting Microsoft Entra ID:
+
+| Error / Scenario     | Root cause    | Solution |
+| -------------------- | ------------- | -------- |
+| You're using an SDK. | Known issues. | Before making further troubleshooting, it's advisable to install the latest version of the software you are using to connect to the service. Authentication bugs may have been fixed in a newer version of the software you're using. |
+| `401 Principal does not have access to API/Operation` | The request indicates authentication in the correct way, however, the user principal doesn't have the required permissions to use the inference endpoint. | Ensure you have: <br /> 1. Assigned the role **Cognitive Services User** to your principal to the Azure AI Services resource. <br /> 2. Wait at least 5 minutes before making the first call. |
+| `401 HTTP/1.1 401 PermissionDenied` | The request indicates authentication in the correct way, however, the user principal doesn't have the required permissions to use the inference endpoint. | Assigned the role **Cognitive Services User** to your principal in the Azure AI Services resource. Roles like **Administrator** or **Contributor** don't grand inference access. Wait at least 5 minutes before making the first call. |
+| You're using REST API calls and you get `401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired.` | The request is failing to perform authentication with Entra ID. | Ensure the `Authentication` header contains a valid token with a scope `https://cognitiveservices.azure.com/.default`. |
+| You're using `AzureOpenAI` class and you get `401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired.` | The request is failing to perform authentication with Entra ID. | Ensure that you are using an **OpenAI model** connected to the endpoint `https://<resource>.openai.azure.com`. You can't use `OpenAI` class or a Models-as-a-Service model. If your model is not from OpenAI, use the Azure AI Inference SDK. |
+| You're using the Azure AI Inference SDK and you get `401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired.` | The request is failing to perform authentication with Entra ID. | Ensure you're connected to the endpoint `https://<resource>.services.ai.azure.com/model` and that you indicated the right scope for Entra ID (`https://cognitiveservices.azure.com/.default`). |
+| `404 Not found` | The endpoint URL is incorrect based on the SDK you are using, or the model deployment doesn't exist. | Ensure you are using the right SDK connected to the right endpoint: <br /> 1. If you are using the Azure AI inference SDK, ensure the endpoint is `https://<resource>.services.ai.azure.com/model` with `model="<model-deployment-name>"` in the payloads, or endpoint is `https://<resource>.openai.azure.com/deployments/<model-deployment-name>`. <br /> If you are using the `AzureOpenAI` class, ensure the endpoint is `https://<resource>.openai.azure.com`. |