Ограничения на URI идентификаторов приложений Microsoft Entra

Свойство identifierUri, также называемое Application ID URI, типично настраивается для приложений ресурсов (API) в Microsoft Entra. Настройка этого свойства очень важна для безопасности ресурса.

Безопасные шаблоны

Поддерживаются следующие форматы URI идентификатора приложения на основе схемы HTTP и API. Замените значения заполнителей, как описано в списке, что находится под таблицей.

• <appId> — свойство идентификатора приложения (appId) объекта приложения.
• <string> — строковое значение для узла или сегмента пути к API.
• <tenantId> — идентификатор GUID, созданный Azure для представления клиента в Azure.
• <tenantInitialDomain> - <tenantInitialDomain>.onmicrosoft.com, где <tenantInitialDomain> — это исходное доменное имя, которое создатель клиента задает при создании клиента.
• <verifiedCustomDomain> — проверенный личный домен , настроенный для клиента Microsoft Entra.

Применение безопасных шаблонов с помощью политики

Корпорация Майкрософт представила параметр безопасности, который защищает от небезопасной конфигурации URI идентификаторов (также называемых URI идентификаторов приложений) в приложениях Microsoft Entra. Этот параметр безопасности гарантирует, что новые добавленные URI в приложениях версии 1 соответствуют приведенным выше безопасным шаблонам .

Поведение политики

Если этот параметр включен, безопасные шаблоны строго применяются. Когда включено, если кто-либо в вашей организации пытается добавить URI идентификатора, не соответствующий безопасным шаблонам, появится ошибка, например:

Failed to add identifier URI {uri}. All newly added URIs must contain a tenant verified domain, tenant ID, or app ID, as per the default tenant policy of your organization. See https://aka.ms/identifier-uri-addition-error for more information on this error.

Приложения, настроенные для использования токенов Entra ID версии 2.0, устанавливают для них свойство api.requestedAccessTokenVersion как 2, освобождаются по умолчанию. Приложения, которые настроены на использование протокола SAML для единого входа и имеют свойство служебного принципала, установленное на preferredSingleSignOnMode, также освобождаются по умолчанию.

Существующие URI идентификаторов, уже настроенные в приложении, не будут затронуты, и все приложения будут продолжать функционировать как обычные. Это повлияет только на новые обновления конфигураций приложений Microsoft Entra.

Если он не включен, некоторые небезопасные шаблоны по-прежнему можно использовать. Например, можно добавить URI формата api://{string} . Однако даже при отключении этого параметра проверенный или начальный домен может по-прежнему требоваться в некоторых сценариях, например, при использовании схемы https://.

Включение и управление политикой

Возможно, корпорация Майкрософт уже включила эту политику в вашей организации для повышения безопасности. Этот скрипт можно проверить, выполнив этот скрипт.

Даже если корпорация Майкрософт включила политику в вашей организации, администратор клиента по-прежнему имеет полный контроль над ней. Они могут предоставлять исключения конкретному приложению Microsoft Entra, себе, другому пользователю в организации или любому сервису или процессу, используемому организацией. Кроме того, администратор может отключить политику (не рекомендуется).

Корпорация Майкрософт не будет включать политику в вашей организации, если она обнаруживает, что у вашей организации есть процессы, которые могут быть нарушены изменением. Вместо этого администратор в организации может включить его самостоятельно (рекомендуется).

Руководство для разработчиков

Ознакомьтесь с этим разделом, если вы являетесь разработчиком, и вы пытаетесь добавить URI идентификатора (также известный как URI идентификатора приложения) в API Microsoft Entra, который вы владеете, но вы получили эту ошибку.

Существует три возможных способа добавления URI идентификатора в приложение. Мы рекомендуем их в следующем порядке:

1. Использование одного из безопасных шаблонов URI

2. Если возникла эта ошибка, это означает, что API в настоящее время использует токены версии 1.0. Вы можете разблокировать себя, обновив службу, чтобы принять токены версии 2.0. Маркеры версии 2.0 похожи на версии 1.0, но существуют некоторые различия. После того как служба сможет обрабатывать маркеры версии 2.0, можно обновить конфигурацию приложения, чтобы Microsoft Entra отправляла им маркеры версии 2.0. Это можно сделать с помощью редактора манифеста в интерфейсе регистрации приложений Центра администрирования Microsoft Entra:

   

   Однако при внесении этого изменения следует соблюдать осторожность. Это связано с тем, что после обновления приложения до формата маркера версии 2.0 он не сможет вернуться к маркерам версии 1.0, если он имеет несоответствующие URI идентификатора, если только не предоставлено исключение (см. вариант 3).

3. Если вам нужно добавить URI несоответствующего требованиям идентификатора в ваше приложение, прежде чем вы сможете обновить его до формата токена версии 2.0, вы можете запросить вашего администратора предоставить вашему приложению исключение.

Дополнительные параметры безопасности

Корпорация Майкрософт также предлагает более строгую политику безопасности для identifierUris свойства. Эта более строгая политика называется nonDefaultUriAddition.

Если эта защита включена, новые URI пользовательского идентификатора нельзя добавлять в любое приложение в этой организации, за исключением известных безопасных сценариев. В частности, если выполнены какие-либо из следующих условий, URI идентификатора все еще можно добавить.

• URI идентификатора, добавляемый в приложение, является одним из URI по умолчанию, то есть он находится в формате api://{appId} или api://{tenantId}/{appId}
• Приложение принимает токены v2.0 Entra. Это будет верно, если для свойства приложения api.requestedAccessTokenVersion установлено значение 2.
• Приложение использует протокол SAML для единого входа. Это верно, если для приложения субъект-служба имеет свойство preferredSingleSignOnMode, установленное на SAML.
• Освобождение было предоставлено администратором приложению, в которое добавляется URI, или пользователю либо службе, выполняющим добавление.

После включения этой защиты, если любой пользователь в вашей организации пытается добавить URI пользовательского идентификатора в приложение версии 1, он получит ошибку, например:

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.

Эта более строгая политика может помочь защитить вашу организацию от распространенных ошибок проверки токенов в утверждении audience. Мы рекомендуем включить его, если это возможно, но корпорация Майкрософт не будет включать ее от вашего имени.

Чтобы включить эту более строгую политику в организации, можно запустить этот сценарий.

Как и другая политика, администраторы также могут предоставлять исключения этой политике или отключать ее после включения.

Вопросы и ответы

Что такое URI идентификаторов?

URI идентификаторов (также называемые URI идентификаторов приложений) позволяют разработчику ресурса (API) указать строковое значение для приложения в качестве идентификатора. Клиенты, которые получают маркер для API, могут использовать это строковое значение во время запроса OAuth. Например, если API настроил URI https://api.contoso.comидентификатора, клиенты API могут указать это значение в запросах OAuth к Microsoft Entra. Этот URI идентификатора используется в качестве утверждения аудитории в токенах доступа v1.0.

URI идентификаторов настраиваются с помощью страницы "Предоставление API" в регистрациях приложений. В регистрациях приложений универсальный код ресурса (URI) называется URI идентификатора приложения; иначе говоря, URI идентификатора.

Как работают эти политики?

Принудительное применение включается путем настройки политик управления приложениями организации. Администратор клиента может включить или отключить его. Корпорация Майкрософт включает его по умолчанию в некоторых организациях в течение июня и июля 2025 г.

Узнайте, как проверить, включена ли защита в вашей организации

Несмотря на то, что корпорация Майкрософт включает этот параметр по умолчанию, администраторы клиентов сохраняют контроль над ним. Они могут включать, отключать или предоставлять исключения.

Почему при настройке приложения SAML возникает эта ошибка?

Приложения SAML исключаются из ограничений URI идентификатора по умолчанию. Однако они должны быть явно указаны как приложения SAML, чтобы применить исключение.

Если настройка SAML настроена с помощью страницы единого входа в "Корпоративные приложения", приложение автоматически будет указано как приложение SAML. Если нет, вы можете указать приложение в качестве приложения SAML, задав preferredSingleSignOn для свойства режима субъекта-службы значение SAML.

Для этого выполните следующий запрос. Идентификатор объекта субъекта-службы можно получить из интерфейса корпоративных приложений.

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/{objectIdOfServicePrincipal}

{
    "preferredSingleSignOnMode": "SAML"
}