feat: entra ID

santiagxf · santiagxf · commit b3761f3cad3c · 2025-01-23T16:47:06.000-05:00
diff --git a/articles/ai-foundry/model-inference/how-to/configure-entra-id.md b/articles/ai-foundry/model-inference/how-to/configure-entra-id.md
@@ -0,0 +1,32 @@
+---
+title: Configure key-less access with Microsoft Entra ID
+titleSuffix: Azure AI Foundry
+description: Learn how to configure key-less authorization to use Azure AI model inference with Microsoft Entra ID.
+ms.service: azure-ai-model-inference
+ms.topic: how-to
+ms.date: 10/01/2024
+ms.custom: ignite-2024, github-universe-2024
+manager: nitinme
+author: mrbullwinkle
+ms.author: fasantia 
+recommendations: false
+zone_pivot_groups: azure-ai-models-deployment
+---
+
+# Configure key-less access with Microsoft Entra ID
+
+::: zone pivot="ai-foundry-portal"
+[!INCLUDE [portal](../includes/configure-entra-id/portal.md)]
+::: zone-end
+
+::: zone pivot="programming-language-cli"
+[!INCLUDE [cli](../includes/configure-entra-id/cli.md)]
+::: zone-end
+
+::: zone pivot="programming-language-bicep"
+[!INCLUDE [bicep](../includes/configure-entra-id/bicep.md)]
+::: zone-end
+
+## Next steps
+
+* [Develop applications using Azure AI model inference service in Azure AI services](../supported-languages.md)
diff --git a/articles/ai-foundry/model-inference/includes/configure-entra-id/bicep.md b/articles/ai-foundry/model-inference/includes/configure-entra-id/bicep.md
@@ -0,0 +1,92 @@
+---
+manager: nitinme
+author: mrbullwinkle
+ms.author: fasantia 
+ms.service: azure-ai-model-inference
+ms.date: 12/15/2024
+ms.topic: include
+zone_pivot_groups: azure-ai-models-deployment
+---
+
+[!INCLUDE [Header](intro.md)]
+
+* Install the [Azure CLI](/cli/azure/).
+
+* Identify the following information:
+
+  * Your Azure subscription ID.
+
+## About this tutorial
+
+The example in this article is based on code samples contained in the [Azure-Samples/azureai-model-inference-bicep](https://github.com/Azure-Samples/azureai-model-inference-bicep) repository. To run the commands locally without having to copy or paste file content, use the following commands to clone the repository and go to the folder for your coding language:
+
+```azurecli
+git clone https://github.com/Azure-Samples/azureai-model-inference-bicep
+```
+
+The files for this example are in:
+
+```azurecli
+cd azureai-model-inference-bicep/infra
+```
+
+## Understand the resources
+
+The tutorial helps you create:
+
+> [!div class="checklist"]
+> * An Azure AI Services resource with key access disabled. For simplicity, this template doesn't deploy models.
+> * A role-assignment for a given security principal with the role **Cognitive Services User**.
+
+You are using the following assets to create those resources:
+
+1. Use the template `modules/ai-services-template.bicep` to describe your Azure AI Services resource:
+
+    __modules/ai-services-template.bicep__
+
+    :::code language="bicep" source="~/azureai-model-inference-bicep/infra/modules/ai-services-template.bicep":::
+
+    > [!TIP]
+    > Notice that this template can take the parameter `allowKeys` which, when `false` will disable the use of keys in the resource. This configuration is optional.
+
+2. Use the template `modules/role-assignment-template.bicep` to describe a role assignment in Azure:
+
+    __modules/role-assignment-template.bicep__
+
+    :::code language="bicep" source="~/azureai-model-inference-bicep/infra/modules/role-assignment-template.bicep":::
+
+## Create the resources
+
+In your console, follow these steps:
+
+1. Define the main deployment:
+
+    __deploy-simple-entra-id.bicep__
+
+    :::code language="bicep" source="~/azureai-model-inference-bicep/infra/deploy-simple-entra-id.bicep":::
+
+2. Log into Azure:
+
+    ```azurecli
+    az login
+    ```
+
+3. Ensure you are in the right subscription:
+
+    ```azurecli
+    az account set --subscription "<subscription-id>"
+    ```
+
+4. Run the deployment:
+
+    ```azurecli
+    RESOURCE_GROUP="<resource-group-name>"
+    SECURITY_PRINCIPAL_ID="<your-security-principal-id>"
+    
+    az deployment group create \
+      --resource-group $RESOURCE_GROUP \
+      --securityPrincipalId $SECURITY_PRINCIPAL_ID
+      --template-file deploy-simple-entra-id.bicep
+    ```
+
+7. The template outputs the Azure AI model inference endpoint that you can use to consume any of the model deployments you have created.
diff --git a/articles/ai-foundry/model-inference/includes/configure-entra-id/cli.md b/articles/ai-foundry/model-inference/includes/configure-entra-id/cli.md
@@ -0,0 +1,90 @@
+---
+manager: nitinme
+author: mrbullwinkle
+ms.author: fasantia 
+ms.service: azure-ai-model-inference
+ms.date: 12/15/2024
+ms.topic: include
+zone_pivot_groups: azure-ai-models-deployment
+---
+
+[!INCLUDE [Header](intro.md)]  
+
+* Install the [Azure CLI](/cli/azure/).
+
+* Identify the following information:
+
+  * Your Azure subscription ID.
+
+  * Your Azure AI Services resource name.
+
+  * The resource group where the Azure AI Services resource is deployed.
+
+
+## Configure Microsoft Entra ID for inference
+
+Follow these steps to configure Microsoft Entra ID for inference in you Azure AI Services resource:
+
+
+1. Log in into your Azure subscription:
+
+    ```azurecli
+    az login
+    ```
+
+2. If you have more than 1 subscription, select the subscription where your resource is located:
+
+    ```azurecli
+    az account set --subscription "<subscription-id>"
+    ```
+
+3. Set the following environment variables with the name of the Azure AI Services resource you plan to use and resource group.
+
+    ```azurecli
+    ACCOUNT_NAME="<ai-services-resource-name>"
+    RESOURCE_GROUP="<resource-group>"
+    ```
+
+4. Get the full name of your resource:
+
+    ```azurecli
+    RESOURCE_ID=$(az resource show -g $RESOURCE_GROUP -n $ACCOUNT_NAME --resource-type "Microsoft.CognitiveServices/accounts")
+    ```
+
+5. Get the object ID of the security principal you want to assign permissions to. The following example shows how to get the object ID associated with:
+    
+    __Your own logged in account__
+
+    ```azurecli
+    OBJECT_ID=$(az ad signed-in-user show --query id --output tsv)
+    ```
+
+    __A security group__
+
+    ```azurecli
+    OBJECT_ID=$(az ad group show --group "<group-name>" --query id --output tsv)
+    ```
+
+    __A service principal__
+
+    ```azurecli
+    OBJECT_ID=$(az ad sp show --id "<service-principal-guid>" --query id --output tsv)
+    ```
+    
+6. Assign the **Cognitive Services User** role to the service principal (scoped to the resource). By assigning a role, you're granting service principal access to this resource.
+
+    ```azurecli
+    az role assignment create --assignee-object-id $OBJECT_ID --role "Cognitive Services User" --scope $RESOURCE_ID
+    ```
+
+8.  The selected user can now use Microsoft Entra ID for inference.
+
+    > [!TIP]
+    > Keep in mind that Azure role assignments may take up to five minutes to propagate. When working with security groups, adding or removing users from the security group propagates immediately.
+
+
+## Use Microsoft Entra ID in your code
+
+Once Microsoft Entra ID has been configured 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:
+
+[!INCLUDE [code](../code-create-chat-client-entra.md)]
diff --git a/articles/ai-foundry/model-inference/includes/configure-entra-id/intro.md b/articles/ai-foundry/model-inference/includes/configure-entra-id/intro.md
@@ -0,0 +1,33 @@
+[!INCLUDE [Feature preview](../../../../ai-studio/includes/feature-preview.md)]
+
+Models deployed to Azure AI model inference in Azure AI Services support key-less authorization using Microsoft Entra ID. It enhances security, simplifies the user experience, reduces operational complexity, and provides robust compliance support for modern development. This makes it a strong choice for organizations adopting secure and scalable identity management solutions. You can [configure Microsoft Entra ID authorization in the resource](#configure-microsoft-entra-id-for-inferenced) and, optionally, [disable key-based authentication to prevent any user to still use keys to access the service](#disable-key-based-authentication-in-the-resource).
+
+This article explains how to configure Microsoft Entra ID for inference in Azure AI model inference.
+
+## Understand roles in the context of resource in Azure
+
+Microsoft Entra ID uses the idea of Role-based Access Control (RBAC) for authorization. Roles are central to managing access to your cloud resources. A role is essentially a collection of permissions that define what actions can be performed on specific Azure resources. By assigning roles to users, groups, service principals, or managed identities—collectively known as security principals—you control their access within your Azure environment to specific resources.
+
+When you assign a role, you specify the security principal, the role definition, and the scope. This combination is known as a role assignment. Azure AI model inference is a capability of the Azure AI Services resources, and hence, access to the service is controlled by the roles assigned to that particular resource.
+
+You identify two different types of access to the resources:
+
+* **Administration access**: The actions that are related with the administration of the resources. These type of operations usually change the state of the resource and its configuration. In Azure, those operations are usually considered control-plane operations and can be executed using the Azure Portal, the Azure CLI, or with infrastructure as code. Examples of these are create new model deployments, change content filtering configurations, change the version of the model served, change SKU of a deployment.
+* **Developer access**: The actions that are related with the consumption of the resources. These type of operations consumes the capabilities of the resource. For example, invoking the chat completions API. However, the user can't change the state of the resource and its configuration.
+
+In Azure, administration operations are always performed using Microsoft Entra ID. Roles like **Cognitive Services Contributor** allow you to perform those operations. On the other hand, developer operations can be performed using either access keys or/and Microsoft Entra ID. Roles like **Cognitive Services User** allow you to perform those operations.
+
+> [!IMPORTANT]
+> Having administration access to a resource doesn't necessarily grants developer access to it. Explicit access by granting roles is still required. This is analogous to how database servers work. Having administrator access to the database server doesn't mean you can read the data inside of a database.
+
+Follow these steps to configure developer access to Azure AI model inference in the Azure AI Services resource.
+
+## Prerequisites
+
+To complete this article, you need:
+
+* An Azure subscription. If you are using [GitHub Models](https://docs.github.com/en/github-models/), you can upgrade your experience and create an Azure subscription in the process. Read [Upgrade from GitHub Models to Azure AI model inference](../../how-to/quickstart-github-models.md) if it's your case.
+
+* An Azure AI services resource. For more information, see [Create an Azure AI Services resource](/articles/ai-foundry/model-inference/how-to/quickstart-create-resources.md).
+
+* Administrator roles for the scope of the Azure AI Services resource or the resource group where it's deployed.
diff --git a/articles/ai-foundry/model-inference/includes/configure-entra-id/portal.md b/articles/ai-foundry/model-inference/includes/configure-entra-id/portal.md
@@ -0,0 +1,84 @@
+---
+manager: nitinme
+author: mrbullwinkle
+ms.author: fasantia 
+ms.service: azure-ai-model-inference
+ms.date: 12/15/2024
+ms.topic: include
+zone_pivot_groups: azure-ai-models-deployment
+---
+
+[!INCLUDE [Header](intro.md)]
+
+## Configure Microsoft Entra ID for inference
+
+Follow these steps to configure Microsoft Entra ID for inference if you are using **projects or hubs** in Azure AI Foundry. If your are not using them, Start from step 5 using the Azure portal.
+
+1. Go to the [Azure portal](https://portal.azure.com) and locate the Azure AI Services resource you are using. If you are using Azure AI Foundry with projects or hubs, you can navigate to it by:
+
+   1. Go to [Azure AI Foundry portal](https://ai.azure.com).
+
+   2. On the landing page, select **Open management center**.
+
+   3. Go to the section **Connected resources** and select the connection to the Azure AI Services resource that you want to configure. If it's not listed, select **View all** to see the full list.
+
+   4. On the **Connection details** section, under **Resource**, select the name of the Azure resource. A new page opens.
+
+   5. You are now in [Azure portal](https://portal.azure.com) where you can manage all the aspects of the resource itself.
+
+2. On the left navigation bar, select **Access control (IAM)**.
+
+   > [!TIP]
+   > Use the **View my access** option to verify which roles are already assigned to you.
+
+3. Select **Role assignments** and then select **Add** > **Add role assignment**.
+
+4. On **Job function roles**, type **Cognitive Services User**. The list of roles is filtered out.
+
+5.  Select the role and select **Next**.
+
+6.  On **Members**, select the user or group you want to grant access to. We recommend using security groups whenever possible as they are easier to manage and maintain. 
+
+7.  Select **Next** and finish the wizard.
+
+8.  The selected user can now use Microsoft Entra ID for inference.
+
+    > [!TIP]
+    > Keep in mind that Azure role assignments may take up to five minutes to propagate. When working with security groups, adding or removing users from the security group propagates immediately.
+
+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 Microsoft Entra ID has been configured 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:
+
+[!INCLUDE [code](../code-create-chat-client-entra.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. To change this behavior, you have to update the connections from your projects to use Microsoft Entra ID. Follow these steps:
+
+1. Go to [Azure AI Foundry portal](https://ai.azure.com).
+
+2. Navigate to the projects or hubs that are using the Azure AI Services resource through a connection.
+
+3. Select **Management center**.
+
+3. Go to the section **Connected resources** and select the connection to the Azure AI Services resource that you want to configure. If it's not listed, select **View all** to see the full list.
+
+4. On the **Connection details** section, next to **Access details**, select the edit icon.
+
+5. Under **Authentication**, change the value to **Microsoft Entra ID**.
+
+6. Select **Update**.
+
+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’ve implemented Microsoft Entra ID and fully addressed compatibility or fallback concerns in all the applications that consume the service.
+
+
diff --git a/articles/ai-foundry/model-inference/toc.yml b/articles/ai-foundry/model-inference/toc.yml
@@ -54,6 +54,8 @@ items:
         href: ./how-to/configure-content-filters.md
       - name: Use blocklists
         href: ./how-to/use-blocklists.md
+  - name: Configure key-less authentication with Microsoft Entra ID
+    href: ./how-to/configure-entra-id.md
   - name: Manage cost
     href: ./how-to/manage-costs.md
   - name: Quotas and limits
