Microsoft Entra ID
Developer

Restrictions on identifier URIs of Microsoft Entra applications

In brief

The documentation updates guidance on secure identifier URI patterns, checking policy status, requesting exemptions, and configuring app management policies.

What Entra admins need to know

Administrators can use the linked script and policy guidance to review or manage identifier URI protection; no required action 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.

Enforcing secure patterns with policy

Microsoft has introduced a security setting that protects against insecure configuration of identifier URIs (also called 'App ID URIs') on Microsoft Entra applications. This security setting ensures that newly added URIs on v1 applications comply with the secure patterns outlined above.

Policy behavior

Enabling and managing the policy

Microsoft may have already enabled this policy in your organization to improve its security. You can check by running this script.

Even if Microsoft enabled the policy in your organization, a tenant administrator still has full control over it. They can grant exemptions to a specific Microsoft Entra application, to themselves, to another user in the organization, or to any service or process the organization uses. Or, an administrator can disable the policy (not recommended).

:::image type="content" source="media/identifier-uri-restrictions/update-access-token-version-cropped.png" alt-text="Screenshot of update token version experience." lightbox="media/identifier-uri-restrictions/update-access-token-version.png":::

However, you should **proceed with caution when making this change**. This is because once the app has been updated to the v2.0 token format, it won't be able to switch back to v1.0 tokens if it has noncompliant identifier URIs configured, unless it's been granted an exemption (see option 3).
  1. If you need to add a noncompliant identifier URI to your app before you're able to update to the v2.0 token format, you can request your administrator to grant your app an exemption.

Additional security settings

Once this protection is enabled, if anyone in your organization attempts to add a custom identifier URI to a v1 application, they'll receive an error like:

The newly added URI {uri} must comply with the format 'api://{appId}' or 'api://{tenantId}/{appId}' as per the default app management policy of your organization. If the requestedAccessTokenVersion is set to 2, this restriction may not apply. See https://aka.ms/identifier-uri-addition-error for more information on this error.

This more restrictive policy can help protect your organization from common token validation errors in the audience claim. We recommend enabling it if possible, but Microsoft won't enable it on your behalf.

How do these policies work?

The enforcements are turned on by configuring an organization's app management policies. A tenant administrator can turn it on or off. Microsoft is enabling it by default in some organizations during the months of June and July 2025.

Learn how to check if the protection has been enabled in your organization

Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…