Manage Client Id Metadata Document Clients
In brief
The documentation now describes default, strict, and open tenant consent postures for CIMD clients, including their approval and OAuth-scope behavior. It also warns that unrestricted consent can enable consent phishing and unauthorized data access.
What Entra admins need to know
Review the documented consent posture for your organization and use the strict posture where client onboarding requires administrative review. No mandatory action or deadline is stated.
This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.
Documentation change
The comparison below shows only the changed extract. Use the full-page view for complete context.
#customer-intent: As an Entra administrator, I want to control and monitor CIMD clients in my tenant so that users can connect approved MCP clients without bypassing organizational consent and security policies.
Before enabling CIMD scenarios, review Client ID Metadata Documents in Microsoft Entra ID, including the limitations and governance considerations.
Prerequisites
To manage CIMD clients, you need:In this article
A Microsoft Entra tenant in which CIMD support is available.Choose a tenant posture- Understand the default posture
The CIMD URL supplied by the client owner.Configure the strict postureAn account with a role that can create agent identities, such asGlobal Administrator,Agent ID Administrator,AI Administrator, orAgent ID Developer.Administrator consent for the Microsoft Graph permissions used by any automation:AgentIdentity.Create.Allto create a CIMD-backed agent identity.AgentIdentity.Read.Allto read and list agent identities.Configure the open posture
To change consent policy programmatically:Add a CIMD clientThePrivileged Role Administratorrole.Add via Admin CenterPolicy.ReadWrite.PermissionGrantto create or update a permission grant policy.Policy.ReadWrite.Authorizationto assign a permission grant policy to the default user role.Add via Microsoft Graph
- List CIMD clients
Use the least-privileged role and permissions that meet your requirements. - Monitor a CIMD client
Choose a tenant posture
Before you configure CIMD, decide whoTenant consent policy determines whether users can add CIMD clients to a tenant and which delegated permissions they can grant. Review the default behavior, then choose a strict or open posture for your organization. Prefer the strict posture when your organization requires review before a newCIMDclientto your tenant.can access its data.ApproachPostureBehavior Consider when Administrator-curatedDefaultDisable user-initiatedUsers can add CIMDuse.clients and grant a limited set of scopes, such asopenidand Microsoft GraphUser.Read. Risk-based step-up consent requires administrator approval for other permissions.Your organization allows self-service onboarding for basic scopes but requires administrator approval for additional permissions. Strict An administrator reviewsadds eachclient, createsapproved CIMD client through consent, the admin center, or Microsoft Graph, then grants itsagent identity, and grants therequiredpermissions.OAuth scopes for all users. Users don't approve new CIMD clients or additional scopes.Your organization requires a security or application-onboarding review before creating an identity.review.Policy-controlledOpenAn administrator enables user consent Let users addfor selected OAuth permissions, including for unverified clients, and disables risk-based step-up consent. The policy applies to CIMD and non-CIMD clientswhen the client and requested delegated permissions satisfy consent policy. Permissions outside the policy still require an administrator.that match its conditions. Each user consents for their own access.Your organization permits low-riskaccepts self-serviceintegrations and monitors newly created identities.onboarding of unverified clients within a reviewed permission boundary.Both postures use consent policy to control user-initiated creation. Neither posture automatically grants a CIMD client access to every resource. Consent grants and tenant policy continue to determine which delegated permissions the client can use.Disable user-initiated CIMD useTo prevent users from adding CIMD clients:Sign in to the Microsoft Entra admin centerUnderstand the default posture
Under the default consent policy, users can sign in to any CIMD client and create an agent identity in the tenant. They can grant only a limited set of OAuth scopes, such as
openidand Microsoft GraphUser.Read. Risk-based step-up consent is enabled by default and prevents users from granting other permissions to CIMD clients without administrator approval.Configure the strict posture
To prevent users from adding CIMD clients to a tenant, update your tenant's consent settings to block user consent to unverified apps. Entra treats CIMD clients as unverified apps. Use one of the following two approaches:
Consent settings: Sign in to the Microsoft Entra admin center
- Browse to Entra ID > Enterprise apps > Consent and permissions > User consent settings.
DisableSelectAllowDo not allow user consent, then select Save. This blocks user consentfor unregistered appsto all apps, including verified apps. See Configure user consent.Consent policy: As a Privileged Role Administrator, configure and
agents using Client ID Metadata Documents.SelectSave.
Whenassign a custom user consentforpolicy that requiresclientApplicationsFromVerifiedPublisherOnlyto betrue. CIMD clientsis disabled, userscan'tapprove a new CIMD client themselves. During preview, the admin consent request workflow is disabled for Agent ID, including CIMD clients. Arrange a manual handoff: the user or client owner supplies the CIMD URL, target resource, and requested delegated scopes to an administrator, who adds the client and grants the required permissions before the user retries.Disablingbe publisher verified, so this blocks user consent to CIMD and other unverified apps while allowing verified apps that meet the policy's other conditions. See Manage app consent policies.
Review all assigned user consent policies: a verified-publisher requirement doesn't delete existing CIMD-backed agent identities oroverride another policy that allows unverified apps. These settings don't revoke existing consent grants.grants or delete existing identities. Review and revoke thoseexisting grants separately if you wantneed to stop use of clients that are already approved.previously approved access.
Enable user-initiated CIMD use with a custom consent policyConfigure the open posture
Use a custom permission grant policy when you wantTo enable users to add CIMD clients to your tenant and grant them specific permissions, update your tenant's consent policy:
Define a custom consent policy. Limit consent to
a controlled set of permissions. The following Microsoft Graph PowerShell example:Creates a CIMD-specificpermission grant policy.Adds an include condition that allowsresource applications and reviewed delegated permissionsclassified as low impact.that allow user consent. SetclientApplicationsFromVerifiedPublisherOnlytofalseso CIMD clients can qualify. See Manage app consent policies.AssignsApply the policy to all users. Assign it to the default user role
without removing existing policy assignments.
The CIMD condition is available onusing theMicrosoft Graph beta endpoint.Connect-MgGraph -Scopes @( "Policy.ReadWrite.PermissionGrant", "Policy.ReadWrite.Authorization" ) $policyId = "contoso-user-consent-cimd-low" # Create a custom permission grant policy for CIMD clients. $policy = @{ id = $policyId displayName = "Allow low-impactsteps in Configure user consent. Review other assigned policies and remove broader user consentfor CIMD clients" description = "Users can consent to delegatedpermissionsclassified as low impact for CIMD clients." } Invoke-MgGraphRequest ` -Method POST ` -Uri "https://graph.microsoft.com/beta/policies/permissionGrantPolicies" ` -Body ($policy | ConvertTo-Json) # Add an include conditionthatmatches only CIMD clients. $condition = @{ permissionType = "delegated" permissionClassification = "low" resourceApplication = "any" permissions = @("all") clientApplicationIds = @("all") clientApplicationTenantIds = @("all") clientApplicationPublisherIds = @("all") clientApplicationsFromVerifiedPublisherOnly = $false cimdClientApplications = @{ "@odata.type" = "#microsoft.graph.allCimdClientApplications" } } Invoke-MgGraphRequest ` -Method POST ` -Uri "https://graph.microsoft.com/beta/policies/permissionGrantPolicies/$policyId/includes" ` -Body ($condition | ConvertTo-Json -Depth 4) # Preserve existing assignments and add the CIMD-specific policy. $authorizationPolicy = Invoke-MgGraphRequest ` -Method GET ` -Uri "https://graph.microsoft.com/v1.0/policies/authorizationPolicy" $assignments = @( $authorizationPolicy.defaultUserRolePermissions.permissionGrantPoliciesAssigned ) $assignmentId = "managePermissionGrantsForSelf.$policyId" if ($assignments -notcontains $assignmentId) { $assignments += $assignmentId } $update = @{ defaultUserRolePermissions = @{ permissionGrantPoliciesAssigned = $assignments } } Invoke-MgGraphRequest ` -Method PATCH ` -Uri "https://graph.microsoft.com/v1.0/policies/authorizationPolicy" ` -Body ($update | ConvertTo-Json -Depth 4)If you already have a custom policy for user consent, add the CIMD include condition to that policy instead of creating another policy. Don't edit a Microsoft-managed policy; built-in policies can't be changed.would bypass your restrictions.The example usespermissionClassification = "low". Only permissions classified as low impact can be granted under this condition. Review your tenant's permission classifications before assigning the policy.To verify the update, listTurn off risk-based step-up consent. After verifying the policy's include conditions and confirmrestrictions, follow Configure risk-based step-up consent to disable the check thatthe authorization policy contains the assignment:otherwise requires administrator approval for nonbasic CIMD permissions.GET https://graph.microsoft.com/beta/policies/permissionGrantPolicies/contoso-user-consent-cimd-low/includes GET https://graph.microsoft.com/v1.0/policies/authorizationPolicyTo disable this custom CIMD policy later, removemanagePermissionGrantsForSelf.contoso-user-consent-cimd-lowfrompermissionGrantPoliciesAssignedand update the authorization policy again. Preserve every unrelated assignment in the collection.For more information about how include and exclude condition sets are evaluated, see Manage app consent policies.Add a CIMD client in the admin centerIn the administrator-curated posture, review a client and create its agent identity before users connect.
Add a CIMD client
In the strict posture, review a client and create its agent identity before users connect.
Add via Admin Center
Before you begin, obtain the CIMD URL from the client owner. Use an account in your Microsoft Entra tenant with a role that can create agent identities, such as Global Administrator, Agent ID Administrator, or AI Administrator.
To add a trusted client before a user connects:
- Sign in to the Microsoft Entra admin center.
- Browse to Entra ID > Agents > Agent identities.
- Select Add
CIMD client (Preview)agent identity. - Enter the client's CIMD URL and continue.
Review the metadata retrieved from the document.- Complete the creation process.
- Grant only the delegated permissions required by the protected resource.
During preview, use the sign-in and consent endpoints or Microsoft Graph, not the portal permissions experience.
Add via Microsoft Graph
CreatingBefore you begin, obtain the identity doesn't by itself authorize access to every resource. Consent grants and tenant policy continue to determine which delegated permissionsCIMD URL from the client owner. Use an account in your Microsoft Entra tenant with a role that can use.create agent identities, such as Global Administrator, Agent ID Administrator, or AI Administrator.
Add a CIMD client with Microsoft Graph
You can create the tenant-local agent identity by using the Microsoft Graph beta endpoint. Administrator-created identities require at least one owner or sponsor. This example binds a sponsor user from the target tenant; replace <sponsor-user-object-id> with the user's object-ID GUID.
POST https://graph.microsoft.com/beta/servicePrincipals/microsoft.graph.agentIdentity
{
"displayName": "Contoso Agent",
"clientIdMetadataDocumentUrl": "https://client.contoso.com/oauth/client-metadata.json",
"[email protected]": [
"https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>"
]
}
Microsoft Entra ID retrieves and validates the document before creating the identity. A successful response resembles:
{
"agentIdentityBlueprintId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"displayName": "Contoso Agent",
"clientIdMetadataDocumentUrl": "https://client.contoso.com/oauth/client-metadata.json",
"isClientIdMetadataDocumenthasClientIdMetadataDocument": true
}
List CIMD clients
The agentIdentityBlueprintId value is derived for identity and correlation purposes. CreatingCIMD clients appear alongside other agent identities in your tenant. Use the admin center to browse identities or Microsoft Graph to retrieve a CIMD client doesn't createCIMD-only list.
List via Admin Center
Sign in with a separately manageable agent identity blueprint.
The request fails if the URL isn't HTTPS, the document can't be retrieved or validated, its client_id doesn't exactly match the URL, or the canonical URL already identifies another agent identityMicrosoft Entra user account in the tenant.tenant you want to inspect.
Find CIMD clients with- Sign in to the Microsoft Entra admin center.
- Browse to Entra ID > Agents > Agent identities.
- Add the filter Has Client ID Metadata Document.
- Select the identity to review its details, owners, sponsors, granted permissions, and sign-in logs.
List via Microsoft Graph
To list all CIMD-backed agent identities, use an advanced query:
GET https://graph.microsoft.com/beta/servicePrincipals/microsoft.graph.agentIdentity?$filter=isClientIdMetadataDocumenthasClientIdMetadataDocument eq true&$count=true
Authorization: Bearer {token}
ConsistencyLevel: eventual
The app ID shown in logs is derived from the CIMD URL. The client has no home application tenant. For more information, see Microsoft Entra Agent ID logs.
Respond to a compromised or untrusted client
If a CIMD client, its signing material, or its domain might be compromised:
Disable the agent identity to stop new token issuance.Revoke its delegated permission grants.Revoke affected user sessions when required by your incident-response process.Review sign-in and audit logs for unexpected activity.Delete the agent identity when you no longer need investigation data or a disabled record.Contact the client owner through a trusted channel.
If the publisher loses control of the CIMD URL or moves the document, don't update the existing identity to a new URL. The URL is immutable. Review and onboard the new URL as a new client, then grant permissions again.
Understand governance gaps
The external CIMD document remains the source of truth for OAuth client configuration. Microsoft Entra ID doesn't copy the complete configuration to an application object.
Consider the following governance gaps:
App management policy doesn't evaluate configuration that exists only in the CIMD document.Inventory and recommendations that inspect stored application credentials or redirect URIs might not include CIMD metadata.CIMD clients can't be publisher verified or Microsoft 365 certified.There is no tenant-managed domain allowlist or blocklist for CIMD URLs.CIMD clients can't be used for app-only authentication or as protected resources.
Maintain an independent inventory of approved CIMD URLs and review it regularly.
Related content
@@ -3,7 +3,7 @@ title: Manage CIMD clients in Microsoft Entra ID titleSuffix: Microsoft Entra Agent ID description: Add, approve, find, monitor, and remove Client ID Metadata Document clients in Microsoft Entra ID. ms.topic: how-to-ms.date: 09/21/2026+ms.date: 10/30/2026 ai-usage: ai-assisted #customer-intent: As an Entra administrator, I want to control and monitor CIMD clients in my tenant so that users can connect approved MCP clients without bypassing organizational consent and security policies.@@ -18,161 +18,82 @@ Microsoft Entra ID represents a client discovered through a Client ID Metadata D Before enabling CIMD scenarios, review [Client ID Metadata Documents in Microsoft Entra ID](client-id-metadata-documents.md), including the limitations and governance considerations. -## Prerequisites+**In this article** -To manage CIMD clients, you need:--- A Microsoft Entra tenant in which CIMD support is available.-- The CIMD URL supplied by the client owner.-- An account with a role that can create agent identities, such as **Global Administrator**, **Agent ID Administrator**, **AI Administrator**, or **Agent ID Developer**.-- Administrator consent for the Microsoft Graph permissions used by any automation:- - `AgentIdentity.Create.All` to create a CIMD-backed agent identity.- - `AgentIdentity.Read.All` to read and list agent identities.-- To change consent policy programmatically:- - The **Privileged Role Administrator** role.- - `Policy.ReadWrite.PermissionGrant` to create or update a permission grant policy.- - `Policy.ReadWrite.Authorization` to assign a permission grant policy to the default user role.--Use the least-privileged role and permissions that meet your requirements.+- [Choose a tenant posture](#choose-a-tenant-posture)+ - [Understand the default posture](#understand-the-default-posture)+ - [Configure the strict posture](#configure-the-strict-posture)+ - [Configure the open posture](#configure-the-open-posture)+- [Add a CIMD client](#add-a-cimd-client)+ - [Add via Admin Center](#add-via-admin-center)+ - [Add via Microsoft Graph](#add-via-microsoft-graph)+- [List CIMD clients](#list-cimd-clients)+ - [List via Admin Center](#list-via-admin-center)+ - [List via Microsoft Graph](#list-via-microsoft-graph)+- [Monitor a CIMD client](#monitor-a-cimd-client) ## Choose a tenant posture -Before you configure CIMD, decide who can add a new CIMD client to your tenant.+Tenant consent policy determines whether users can add CIMD clients to a tenant and which delegated permissions they can grant. Review the default behavior, then choose a strict or open posture for your organization. Prefer the strict posture when your organization requires review before a new client can access its data. -| Approach | Behavior | Consider when |+| Posture | Behavior | Consider when | | --- | --- | --- |-| Administrator-curated | Disable user-initiated CIMD use. An administrator reviews each client, creates its agent identity, and grants the required permissions. | Your organization requires a security or application-onboarding review before creating an identity. |-| Policy-controlled user consent | Let users add CIMD clients when the client and requested delegated permissions satisfy consent policy. Permissions outside the policy still require an administrator. | Your organization permits low-risk self-service integrations and monitors newly created identities. |--Both postures use consent policy to control user-initiated creation. Neither posture automatically grants a CIMD client access to every resource. Consent grants and tenant policy continue to determine which delegated permissions the client can use.--### Disable user-initiated CIMD use--To prevent users from adding CIMD clients:+| Default | Users can add CIMD clients and grant a limited set of scopes, such as `openid` and Microsoft Graph `User.Read`. Risk-based step-up consent requires administrator approval for other permissions. | Your organization allows self-service onboarding for basic scopes but requires administrator approval for additional permissions. |+| Strict | An administrator adds each approved CIMD client through consent, the admin center, or Microsoft Graph, then grants its required OAuth scopes for all users. Users don't approve new CIMD clients or additional scopes. | Your organization requires a security or application-onboarding review. |+| Open | An administrator enables user consent for selected OAuth permissions, including for unverified clients, and disables risk-based step-up consent. The policy applies to CIMD and non-CIMD clients that match its conditions. Each user consents for their own access. | Your organization accepts self-service onboarding of unverified clients within a reviewed permission boundary. | -1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as a **Global Administrator**.-1. Browse to **Entra ID** > **Enterprise apps** > **Consent and permissions** > **User consent settings**.-1. Disable **Allow user consent for unregistered apps and agents using Client ID Metadata Documents**.-1. Select **Save**.+> [!WARNING]+> Don't allow users to consent to all CIMD clients for any OAuth scope. Anyone can publish a CIMD document; control of a URL doesn't establish trustworthiness. Unrestricted consent exposes your tenant to consent phishing attacks and unauthorized access to organizational data. The open posture must limit user consent to specific, reviewed permissions. Its consent policy also permits matching non-CIMD clients, including unverified apps; it can't be limited to CIMD clients. -When user consent for CIMD clients is disabled, users can't approve a new CIMD client themselves. During preview, the admin consent request workflow is disabled for Agent ID, including CIMD clients. Arrange a manual handoff: the user or client owner supplies the CIMD URL, target resource, and requested delegated scopes to an administrator, who adds the client and grants the required permissions before the user retries.+### Understand the default posture -Disabling user consent doesn't delete existing CIMD-backed agent identities or revoke existing consent grants. Review and revoke those grants separately if you want to stop use of clients that are already approved.+Under the default consent policy, users can sign in to any CIMD client and create an agent identity in the tenant. They can grant only a limited set of OAuth scopes, such as `openid` and Microsoft Graph `User.Read`. Risk-based step-up consent is enabled by default and prevents users from granting other permissions to CIMD clients without administrator approval. -### Enable user-initiated CIMD use with a custom consent policy+### Configure the strict posture -Use a custom permission grant policy when you want users to add CIMD clients and consent to a controlled set of permissions. The following Microsoft Graph PowerShell example:+To prevent users from adding CIMD clients to a tenant, update your tenant's consent settings to block user consent to unverified apps. Entra treats CIMD clients as unverified apps. Use one of the following two approaches: -1. Creates a CIMD-specific permission grant policy.-1. Adds an include condition that allows delegated permissions classified as low impact.-1. Assigns the policy to the default user role without removing existing policy assignments.+- **Consent settings:** Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as a **Global Administrator**. Browse to **Entra ID** > **Enterprise apps** > **Consent and permissions** > **User consent settings**. Select **Do not allow user consent**, then select **Save**. This blocks user consent to all apps, including verified apps. See [Configure user consent](/entra/identity/enterprise-apps/configure-user-consent). -The CIMD condition is available on the Microsoft Graph beta endpoint.+- **Consent policy:** As a **Privileged Role Administrator**, configure and assign a custom user consent policy that requires `clientApplicationsFromVerifiedPublisherOnly` to be `true`. CIMD clients can't be publisher verified, so this blocks user consent to CIMD and other unverified apps while allowing verified apps that meet the policy's other conditions. See [Manage app consent policies](/entra/identity/enterprise-apps/manage-app-consent-policies). -```powershell-Connect-MgGraph -Scopes @(- "Policy.ReadWrite.PermissionGrant",- "Policy.ReadWrite.Authorization"-)+Review all assigned user consent policies: a verified-publisher requirement doesn't override another policy that allows unverified apps. These settings don't revoke existing consent grants or delete existing identities. Review and revoke existing grants separately if you need to stop previously approved access. -$policyId = "contoso-user-consent-cimd-low"+### Configure the open posture -# Create a custom permission grant policy for CIMD clients.-$policy = @{- id = $policyId- displayName = "Allow low-impact user consent for CIMD clients"- description = "Users can consent to delegated permissions classified as low impact for CIMD clients."-}+To enable users to add CIMD clients to your tenant and grant them specific permissions, update your tenant's consent policy: -Invoke-MgGraphRequest `- -Method POST `- -Uri "https://graph.microsoft.com/beta/policies/permissionGrantPolicies" `- -Body ($policy | ConvertTo-Json)--# Add an include condition that matches only CIMD clients.-$condition = @{- permissionType = "delegated"- permissionClassification = "low"- resourceApplication = "any"- permissions = @("all")- clientApplicationIds = @("all")- clientApplicationTenantIds = @("all")- clientApplicationPublisherIds = @("all")- clientApplicationsFromVerifiedPublisherOnly = $false- cimdClientApplications = @{- "@odata.type" = "#microsoft.graph.allCimdClientApplications"- }-}+1. **Define a custom consent policy.** Limit consent to specific resource applications and reviewed delegated permissions that allow user consent. Set `clientApplicationsFromVerifiedPublisherOnly` to `false` so CIMD clients can qualify. See [Manage app consent policies](/entra/identity/enterprise-apps/manage-app-consent-policies). -Invoke-MgGraphRequest `- -Method POST `- -Uri "https://graph.microsoft.com/beta/policies/permissionGrantPolicies/$policyId/includes" `- -Body ($condition | ConvertTo-Json -Depth 4)+1. **Apply the policy to all users.** Assign it to the default user role using the steps in [Configure user consent](/entra/identity/enterprise-apps/configure-user-consent). Review other assigned policies and remove broader user consent permissions that would bypass your restrictions. -# Preserve existing assignments and add the CIMD-specific policy.-$authorizationPolicy = Invoke-MgGraphRequest `- -Method GET `- -Uri "https://graph.microsoft.com/v1.0/policies/authorizationPolicy"+1. **Turn off risk-based step-up consent.** After verifying the policy restrictions, follow [Configure risk-based step-up consent](/entra/identity/enterprise-apps/configure-risk-based-step-up-consent) to disable the check that otherwise requires administrator approval for nonbasic CIMD permissions. -$assignments = @(- $authorizationPolicy.defaultUserRolePermissions.permissionGrantPoliciesAssigned-)-$assignmentId = "managePermissionGrantsForSelf.$policyId"+> [!WARNING]+> Choosing the open posture can put your users at risk of consent phishing attacks from malicious clients. The consent policy also applies to matching non-CIMD clients, including unverified apps. Disabling risk-based step-up consent is tenant-wide and removes automatic administrator step-up for risky consent requests. Don't combine it with unrestricted user consent. -if ($assignments -notcontains $assignmentId) {- $assignments += $assignmentId-}--$update = @{- defaultUserRolePermissions = @{- permissionGrantPoliciesAssigned = $assignments- }-}--Invoke-MgGraphRequest `- -Method PATCH `- -Uri "https://graph.microsoft.com/v1.0/policies/authorizationPolicy" `- -Body ($update | ConvertTo-Json -Depth 4)-```--If you already have a custom policy for user consent, add the CIMD include condition to that policy instead of creating another policy. Don't edit a Microsoft-managed policy; built-in policies can't be changed.--The example uses `permissionClassification = "low"`. Only permissions classified as low impact can be granted under this condition. Review your tenant's [permission classifications](/entra/identity/enterprise-apps/configure-permission-classifications) before assigning the policy.--To verify the update, list the policy's include conditions and confirm that the authorization policy contains the assignment:--```http-GET https://graph.microsoft.com/beta/policies/permissionGrantPolicies/contoso-user-consent-cimd-low/includes--GET https://graph.microsoft.com/v1.0/policies/authorizationPolicy-```+## Add a CIMD client -To disable this custom CIMD policy later, remove `managePermissionGrantsForSelf.contoso-user-consent-cimd-low` from `permissionGrantPoliciesAssigned` and update the authorization policy again. Preserve every unrelated assignment in the collection.+In the strict posture, review a client and create its agent identity before users connect. -For more information about how include and exclude condition sets are evaluated, see [Manage app consent policies](/entra/identity/enterprise-apps/manage-app-consent-policies).+### Add via Admin Center -## Add a CIMD client in the admin center--In the administrator-curated posture, review a client and create its agent identity before users connect.--> [!IMPORTANT]-> CIMD verifies control of a URL. It doesn't establish that the client is trustworthy. Review the client owner, document URL, redirect URIs, requested permissions, and business purpose before approval.+Before you begin, obtain the CIMD URL from the client owner. Use an account in your Microsoft Entra tenant with a role that can create agent identities, such as **Global Administrator**, **Agent ID Administrator**, or **AI Administrator**. To add a trusted client before a user connects: 1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com). 1. Browse to **Entra ID** > **Agents** > **Agent identities**.-1. Select **Add CIMD client (Preview)**.+1. Select **Add agent identity**. 1. Enter the client's CIMD URL and continue.-1. Review the metadata retrieved from the document. 1. Complete the creation process.-1. [Grant only the delegated permissions required by the protected resource](grant-agent-access-microsoft-365.md). During preview, use the sign-in and consent endpoints or Microsoft Graph, not the portal permissions experience.+1. [Grant only the delegated permissions required by the protected resource](grant-agent-access-microsoft-365.md). -Creating the identity doesn't by itself authorize access to every resource. Consent grants and tenant policy continue to determine which delegated permissions the client can use.+### Add via Microsoft Graph -## Add a CIMD client with Microsoft Graph+Before you begin, obtain the CIMD URL from the client owner. Use an account in your Microsoft Entra tenant with a role that can create agent identities, such as **Global Administrator**, **Agent ID Administrator**, or **AI Administrator**. -You can create the tenant-local agent identity by using the Microsoft Graph beta endpoint.+You can create the tenant-local agent identity by using the Microsoft Graph beta endpoint. Administrator-created identities require at least one owner or sponsor. This example binds a sponsor user from the target tenant; replace `<sponsor-user-object-id>` with the user's object-ID GUID. ```http POST https://graph.microsoft.com/beta/servicePrincipals/microsoft.graph.agentIdentity@@ -181,11 +102,14 @@ Content-Type: application/json { "displayName": "Contoso Agent",- "clientIdMetadataDocumentUrl": "https://client.contoso.com/oauth/client-metadata.json"+ "clientIdMetadataDocumentUrl": "https://client.contoso.com/oauth/client-metadata.json",+ "[email protected]": [+ "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>"+ ] } ``` -Microsoft Entra ID retrieves and validates the document before creating the identity. A successful response resembles:+A successful response resembles: ```json {@@ -194,20 +118,29 @@ Microsoft Entra ID retrieves and validates the document before creating the iden "agentIdentityBlueprintId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "displayName": "Contoso Agent", "clientIdMetadataDocumentUrl": "https://client.contoso.com/oauth/client-metadata.json",- "isClientIdMetadataDocument": true+ "hasClientIdMetadataDocument": true } ``` -The `agentIdentityBlueprintId` value is derived for identity and correlation purposes. Creating a CIMD client doesn't create a separately manageable agent identity blueprint.+## List CIMD clients++CIMD clients appear alongside other agent identities in your tenant. Use the admin center to browse identities or Microsoft Graph to retrieve a CIMD-only list. -The request fails if the URL isn't HTTPS, the document can't be retrieved or validated, its `client_id` doesn't exactly match the URL, or the canonical URL already identifies another agent identity in the tenant.+### List via Admin Center++Sign in with a Microsoft Entra user account in the tenant you want to inspect.++1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com).+1. Browse to **Entra ID** > **Agents** > **Agent identities**.+1. Add the filter **Has Client ID Metadata Document**.+1. Select the identity to review its details, owners, sponsors, granted permissions, and sign-in logs. -## Find CIMD clients with Microsoft Graph+### List via Microsoft Graph To list all CIMD-backed agent identities, use an advanced query: ```http-GET https://graph.microsoft.com/beta/servicePrincipals/microsoft.graph.agentIdentity?$filter=isClientIdMetadataDocument eq true&$count=true+GET https://graph.microsoft.com/beta/servicePrincipals/microsoft.graph.agentIdentity?$filter=hasClientIdMetadataDocument eq true&$count=true Authorization: Bearer {token} ConsistencyLevel: eventual ```@@ -236,34 +169,7 @@ Monitor: The app ID shown in logs is derived from the CIMD URL. The client has no home application tenant. For more information, see [Microsoft Entra Agent ID logs](sign-in-audit-logs-agents.md). -## Respond to a compromised or untrusted client--If a CIMD client, its signing material, or its domain might be compromised:--1. Disable the agent identity to stop new token issuance.-1. Revoke its delegated permission grants.-1. Revoke affected user sessions when required by your incident-response process.-1. Review sign-in and audit logs for unexpected activity.-1. Delete the agent identity when you no longer need investigation data or a disabled record.-1. Contact the client owner through a trusted channel.--If the publisher loses control of the CIMD URL or moves the document, don't update the existing identity to a new URL. The URL is immutable. Review and onboard the new URL as a new client, then grant permissions again.--## Understand governance gaps--The external CIMD document remains the source of truth for OAuth client configuration. Microsoft Entra ID doesn't copy the complete configuration to an application object.--Consider the following governance gaps:--- App management policy doesn't evaluate configuration that exists only in the CIMD document.-- Inventory and recommendations that inspect stored application credentials or redirect URIs might not include CIMD metadata.-- CIMD clients can't be publisher verified or Microsoft 365 certified.-- There is no tenant-managed domain allowlist or blocklist for CIMD URLs.-- CIMD clients can't be used for app-only authentication or as protected resources.--Maintain an independent inventory of approved CIMD URLs and review it regularly.--## Related content+**Related content** - [Client ID Metadata Documents in Microsoft Entra ID](client-id-metadata-documents.md) - [Configure a client to use a Client ID Metadata Document](configure-client-id-metadata-document.md) 