Skip to main content
This article explains how to configure keyless authentication with Microsoft Entra ID for Microsoft Foundry Models. Keyless authentication enhances security by eliminating the need for API keys, simplifies the user experience with role-based access control (RBAC), and reduces operational complexity while providing robust compliance support.

​
Prerequisites

To complete this article, you need:

​
Required Azure roles and permissions

Microsoft Entra ID uses role-based access control (RBAC) to manage access to Azure resources. You need different roles, depending on whether you’re setting up authentication (administrator) or using it to make API calls (developer).

​
For setting up authentication

  • Subscription owner or administrator: An account with Microsoft.Authorization/roleAssignments/write and Microsoft.Authorization/roleAssignments/delete permissions, such as the Owner or User Access Administrator role, required to assign the Cognitive Services User role to developers.

​
For making authenticated API calls

  • Cognitive Services User role: Required for developers to authenticate and make inference API calls using Microsoft Entra ID. This role must be assigned at the scope of your Foundry resource.

​
Role assignment requirements

When assigning roles, specify these three elements:
  • Security principal: Your user account, service principal, or security group (recommended for managing multiple users)
  • Role definition: The Cognitive Services User role
  • Scope: Your specific Foundry resource
Azure role assignments can take up to 5 minutes to propagate. When using security groups, changes to group membership propagate immediately.

​
Custom role (optional)

If you prefer a custom role instead of Cognitive Services User, make sure it includes these permissions: 
{
  "permissions": [
    {
      "dataActions": [
        "Microsoft.CognitiveServices/accounts/MaaS/*"
      ]
    }
  ]
}
For more context on how roles work with Azure resources, see Understand roles in the context of resource in Azure.

​
Understand roles in the context of resource in Azure

Microsoft Entra ID uses role-based access control (RBAC) for authorization, which controls what actions users can perform on Azure resources. Roles are central to managing access to cloud resources. A role is 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, role definition, and scope. This combination is known as a role assignment. Foundry Models is a capability of the Foundry Tools resources, therefore, roles assigned to that particular resource control the access for inference. There are two types of access to the resources:
  • Administration access: Actions related to the administration of the resource. These actions usually change the resource state and its configuration. In Azure, these operations are control-plane operations that you can execute using the Azure portal, Azure CLI, or infrastructure as code. Examples include creating new model deployments, changing content filtering configurations, changing the version of the model served, or changing the SKU of a deployment.
  • Developer access: Actions related to consuming the resources, such as invoking the chat completions API. However, the user can’t change the resource state and its configuration.
In Azure, Microsoft Entra ID always performs administration operations. Roles like Cognitive Services Contributor allow you to perform those operations. Developer operations can be performed using either access keys or Microsoft Entra ID. Roles like Cognitive Services User allow you to perform those operations.
Having administration access to a resource doesn’t grant 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.

​
Troubleshooting

Before you troubleshoot, verify that you have the right permissions assigned:
  1. Go to the Azure portal and locate the Microsoft Foundry resource that you’re using.
  2. On the left pane, select Access control (IAM) and then select Check access.
  3. Type the name of the user or identity you’re using to connect to the service.
  4. Verify that the role Cognitive Services User is listed (or a role that contains the required permissions, as explained in the Prerequisites section).
Roles like Owner or Contributor don’t provide access via Microsoft Entra ID.
  1. If the role isn’t listed, follow the steps in this guide before you continue.
The following table contains multiple scenarios that can help you troubleshoot Microsoft Entra ID:
Error / ScenarioRoot causeSolution
You’re using an SDKKnown issuesBefore you troubleshoot further, install the latest version of the software you’re using to connect to the service. Authentication bugs might already be fixed in a newer version of the software you’re using.
401 Principal does not have access to API/OperationThe request indicates authentication in the correct way, but the user principal doesn’t have the required permissions to use the inference endpoint.Ensure you have:
1. Assigned the role Cognitive Services User to your principal to the Foundry resource. Notice that Cognitive Services OpenAI User grants only access to OpenAI models. Owner or Contributor don’t provide access either.
1. Waited at least 5 minutes before making the first call.
401 HTTP/1.1 401 PermissionDeniedThe request indicates authentication in the correct way, but 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 Foundry resource. Roles like Administrator or Contributor don’t grant 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 fails to authenticate with Microsoft Entra ID.Ensure the Authentication header contains a valid token with a scope https://ai.azure.com/.default.

​
Next step