Манифест приложения Microsoft Entra (формат Azure AD Graph)

  • Статья

Манифест приложения содержит определение всех атрибутов объекта приложения в платформа удостоверений Майкрософт. Он также служит механизмом обновления объекта приложения. Дополнительные сведения о сущности приложения и ее схеме см. в документации по сущностям приложения API Graph.

Атрибуты приложения можно настроить с помощью Центра администрирования Microsoft Entra или программно с помощью API Microsoft Graph или пакета SDK Microsoft Graph PowerShell. Однако существуют некоторые сценарии, в которых необходимо изменить манифест приложения для настройки атрибута приложения. К этим сценариям относятся:

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

Настройка манифеста приложения

Чтобы настроить манифест приложения, выполните следующие действия.

  1. Войдите в Центр администрирования Microsoft Entra как минимум разработчик приложений.
  2. Перейдите к приложениям> удостоверений>Регистрация приложений.
  3. Выберите приложение, которое нужно настроить.
  4. В разделе "Управление приложением" выберите "Манифест". Откроется редактор манифеста на основе веб-сайта, позволяющий редактировать манифест. При необходимости можно выбрать "Скачать", чтобы изменить манифест локально, а затем повторно применить его к приложению с помощью отправки.

Справочник по манифесту

В этом разделе описываются атрибуты, найденные в манифесте приложения.

Атрибут id

Ключ Тип значения
идентификатор Струна

Уникальный идентификатор приложения в каталоге. Этот идентификатор не является идентификатором, используемым для идентификации приложения в любой транзакции протокола. Используйте его для ссылки на объект в запросах каталога.

Пример:

    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",

Атрибут acceptMappedClaims

Ключ Тип значения
acceptMappedClaims Логическое значение, допускающее значение NULL

Как описано в типе apiApplicationресурса, это позволяет приложению использовать сопоставление утверждений без указания пользовательского ключа подписи. Приложения, получающие маркеры, полагаются на то, что значения утверждений достоверно выдаются идентификатором Microsoft Entra и не могут быть изменены. Однако при изменении содержимого маркера с помощью политик сопоставления утверждений эти предположения больше не могут быть правильными. Приложения должны явно признать, что маркеры были изменены создателем политики сопоставления утверждений, чтобы защитить себя от политик сопоставления утверждений, созданных вредоносными субъектами.

Предупреждение

Не устанавливайте acceptMappedClaims свойство true для мультитенантных приложений, что позволяет злоумышленникам создавать политики сопоставления утверждений для приложения.

Пример:

    "acceptMappedClaims": true,

атрибут accessTokenAcceptedVersion

Ключ Тип значения
accessTokenAcceptedVersion Nullable Int32

Указывает версию маркера доступа, ожидаемую ресурсом. Этот параметр изменяет версию и формат JWT, созданный независимо от конечной точки или клиента, используемого для запроса маркера доступа.

Используемая конечная точка версии 1.0 или версии 2.0 выбирается клиентом и влияет только на версию id_tokens. Ресурсы должны явно настроить accesstokenAcceptedVersion , чтобы указать поддерживаемый формат маркера доступа.

Возможные значения accesstokenAcceptedVersion : 1, 2 или NULL. Если значение равно NULL, этот параметр по умолчанию имеет значение 1, соответствующее конечной точке версии 1.0.

В противном signInAudience AzureADandPersonalMicrosoftAccountслучае значение должно быть 2.

Пример:

    "accessTokenAcceptedVersion": 2,

Атрибут addIns

Ключ Тип значения
addIns Коллекция

Определяет пользовательское поведение, которое может использовать потребляющая служба для вызова приложения в определенных контекстах. Например, приложения, которые могут отображать потоки файлов, могут задать addIns свойство для его функциональных возможностей FileHandler. Этот параметр позволяет службам, таким как Microsoft 365, вызывать приложение в контексте документа, над которым работает пользователь.

Пример:

    "addIns": [
       {
        "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
        "type":" FileHandler",
        "properties": [
           {
              "key": "version",
              "value": "2"
           }
        ]
       }
    ],

Атрибут allowPublicClient

Ключ Тип значения
allowPublicClient Булев

Указывает тип резервного приложения. Идентификатор Microsoft Entra определяет тип приложения из ответаUrlsWithType по умолчанию. Существуют определенные сценарии, в которых идентификатор Microsoft Entra не может определить тип клиентского приложения. Например, один из таких сценариев — поток ROPC , в котором http-запрос происходит без перенаправления URL-адреса. В этих случаях идентификатор Microsoft Entra интерпретирует тип приложения на основе значения этого свойства. Если для этого значения задано значение true, тип резервного приложения устанавливается как общедоступный клиент, например установленное приложение, работающее на мобильном устройстве. Значение по умолчанию — false, что означает, что тип резервного приложения является конфиденциальным клиентом, например веб-приложением.

Пример:

    "allowPublicClient": false,

Атрибут appId

Ключ Тип значения
appId Струна

Указывает уникальный идентификатор приложения, назначенного приложению идентификатором Microsoft Entra.

Пример:

    "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",

Атрибут appRoles

Ключ Тип значения
appRoles Коллекция

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

Пример:

    "appRoles": [
        {
           "allowedMemberTypes": [
               "User"
           ],
           "description": "Read-only access to device information",
           "displayName": "Read Only",
           "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
           "isEnabled": true,
           "value": "ReadOnly"
        }
    ],

Атрибут errorUrl

Ключ Тип значения
errorUrl Струна

Неподдерживаемые.

Атрибут groupMembershipClaims

Ключ Тип значения
groupMembershipClaims Струна

Настраивает groups утверждение, выданное пользователем или маркером доступа OAuth 2.0, которое ожидает приложение. Чтобы задать этот атрибут, используйте одно из следующих допустимых строковых значений:

  • "None"
  • "SecurityGroup" (для групп безопасности и ролей Microsoft Entra)
  • "ApplicationGroup" (этот параметр включает только группы, назначенные приложению)
  • "DirectoryRole" (получает роли каталога Microsoft Entra, в которые пользователь входит)
  • "All" (это возвращает все группы безопасности, группы рассылки и роли каталога Microsoft Entra, вошедшего в систему пользователя.

Пример:

    "groupMembershipClaims": "SecurityGroup",

Необязательный атрибутClaims

Ключ Тип значения
необязательныеClaims Струна

Необязательные утверждения, возвращаемые в маркере службой маркеров безопасности для этого конкретного приложения.

Приложения, поддерживающие как личная учетная запись, так и идентификатор Microsoft Entra, не могут использовать необязательные утверждения. Однако приложения, зарегистрированные только для идентификатора Microsoft Entra с помощью конечной точки версии 2.0, могут получить необязательные утверждения, запрошенные в манифесте. Дополнительные сведения см. в разделе "Необязательные утверждения".

Пример:

    "optionalClaims": null,

Атрибут identifierUris

Ключ Тип значения
identifierUris Массив строк

Определяемые пользователем URI, которые однозначно определяют веб-приложение в клиенте Microsoft Entra или проверенном домене клиента. Если приложение используется в качестве приложения-ресурса, значение идентификатораUri используется для уникальной идентификации и доступа к ресурсу. Для общедоступного клиентского приложения он не может иметь значение для идентификаторовUris.

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

Поддерживаемый идентификатор приложения
Форматы URI		 Пример URI идентификаторов приложения
<api:// appId> api://00001111-aaaa-2222-bbbb-3333cccc4444
<api:// tenantId>/<appId> api://aaaabbbb-0000-cccc-1111-dddd2222eeee/00001111-aaaa-2222-bbbb-3333cccc4444
<api:// tenantId>/<string> api://aaaabbbb-0000-cccc-1111-dddd2222eeee/api
<api:// строка>/<appId> api://productapi/00001111-aaaa-2222-bbbb-3333cccc4444
<https:// tenantInitialDomain.onmicrosoft.com/>< string> https://contoso.onmicrosoft.com/productsapi
<https:// verifiedCustomDomain>/<string> https://contoso.com/productsapi
<https:// строка>.<verifiedCustomDomain> https://product.contoso.com
<https:// строка>.<verifiedCustomDomain>/<string> https://product.contoso.com/productsapi
  • <appId> — свойство идентификатора приложения (appId) объекта приложения.
  • <string> — строковое значение для узла или сегмента пути api.
  • <tenantId> — GUID, созданный Azure для представления клиента в Azure.
  • <tenantInitialDomain tenantInitialDomain.onmicrosoft.com, где <tenantInitialDomain>>< - > — это начальное доменное имя, указанное создателем клиента при создании клиента.
  • <verifiedCustomDomain> — проверенный личный домен , настроенный для клиента Microsoft Entra.

Заметка

Если вы используете схему api:// , добавьте строковое значение непосредственно после api://. Например, api://< строка>. Это строковое значение может быть GUID или произвольной строкой. Если вы добавляете значение GUID, оно должно соответствовать идентификатору приложения или идентификатору клиента. Значение URI идентификатора приложения должно быть уникальным для клиента. Если вы добавляете api://< tenantId> в качестве URI идентификатора приложения, никто другой не сможет использовать этот URI в любом другом приложении. Рекомендуется использовать вместо этого api://< appId> или схему HTTP.

Важный

Значение URI идентификатора приложения не должно заканчиваться символом косой черты /.

Пример:

    "identifierUris": "https://contoso.onmicrosoft.com/00001111-aaaa-2222-bbbb-3333cccc4444",

атрибут информационныхUrls

Ключ Тип значения
информационныеUrls Струна

Указывает ссылки на условия обслуживания и заявление о конфиденциальности приложения. Условия обслуживания и заявление о конфиденциальности предоставляются пользователям с помощью интерфейса согласия пользователя. Дополнительные сведения см. в статье "Практическое руководство. Добавление условий обслуживания и заявления о конфиденциальности для зарегистрированных приложений Microsoft Entra".

Пример:

    "informationalUrls": {
        "termsOfService": "https://MyRegisteredApp/termsofservice",
        "support": "https://MyRegisteredApp/support",
        "privacy": "https://MyRegisteredApp/privacystatement",
        "marketing": "https://MyRegisteredApp/marketing"
    },

Атрибут keyCredentials

Ключ Тип значения
keyCredentials Коллекция

Содержит ссылки на учетные данные, назначенные приложением, общие секреты на основе строк и сертификаты X.509. Эти учетные данные используются при запросе маркеров доступа (если приложение выступает в качестве клиента, а не как ресурс).

Пример:

    "keyCredentials": [
        {
           "customKeyIdentifier":null,
           "endDateTime":"2018-09-13T00:00:00Z",
           "keyId":"<guid>",
           "startDateTime":"2017-09-12T00:00:00Z",
           "type":"AsymmetricX509Cert",
           "usage":"Verify",
           "value":null
        }
    ],

Атрибут knownClientApplications

Ключ Тип значения
knownClientApplications Массив строк

Используется для предоставления согласия, если у вас есть решение, содержащее две части: клиентское приложение и пользовательское веб-ПРИЛОЖЕНИЕ API. Если вы вводите идентификатор приложения клиента в это значение, пользователь должен будет предоставить согласие только один раз клиентскому приложению. Идентификатор Microsoft Entra будет знать, что согласие клиента означает неявное согласие на веб-API. Он автоматически подготавливает субъекты-службы как для клиента, так и для веб-API одновременно. Клиент и веб-ПРИЛОЖЕНИЕ API должны быть зарегистрированы в одном клиенте.

Пример:

    "knownClientApplications": ["00001111-aaaa-2222-bbbb-3333cccc4444"],

Атрибут logoUrl

Ключ Тип значения
logoUrl Струна

Значение только для чтения, указывающее URL-адрес CDN на логотип, который был отправлен.

Пример:

    "logoUrl": "https://MyRegisteredAppLogo",

Атрибут logoutUrl

Ключ Тип значения
logoutUrl Струна

URL-адрес для выхода из приложения.

Пример:

    "logoutUrl": "https://MyRegisteredAppLogout",

атрибут name

Ключ Тип значения
имя Струна

Отображаемое имя приложения.

Пример:

    "name": "MyRegisteredApp",

атрибут oauth2AllowImplicitFlow

Ключ Тип значения
oauth2AllowImplicitFlow Булев

Указывает, может ли веб-приложение запрашивать неявные маркеры доступа к потоку OAuth2.0. Значение по умолчанию — false. Этот флаг используется для приложений на основе браузера, таких как одностраничные приложения JavaScript. Чтобы узнать больше, введите OAuth 2.0 implicit grant flow оглавление и просмотрите разделы о неявном потоке. Однако мы не рекомендуем использовать неявное предоставление даже в spAs и рекомендуем использовать поток кода авторизации с PKCE.

Пример:

    "oauth2AllowImplicitFlow": false,

атрибут oauth2AllowIdTokenImplicitFlow

Ключ Тип значения
oauth2AllowIdTokenImplicitFlow Булев

Указывает, может ли веб-приложение запрашивать неявные маркеры идентификатора потока OAuth2.0. Значение по умолчанию — false. Этот флаг используется для приложений на основе браузера, таких как одностраничные приложения JavaScript. Однако мы не рекомендуем использовать неявное предоставление даже в spAs и рекомендуем использовать поток кода авторизации с PKCE.

Пример:

    "oauth2AllowIdTokenImplicitFlow": false,

Атрибут oauth2Permissions

Ключ Тип значения
oauth2Permissions Коллекция

Указывает коллекцию областей разрешений OAuth 2.0, предоставляемых клиентским приложениям веб-API (ресурс). Эти области разрешений могут быть предоставлены клиентским приложениям во время согласия.

Пример:

    "oauth2Permissions": [
       {
          "adminConsentDescription": "Allow the app to access resources on behalf of the signed-in user.",
          "adminConsentDisplayName": "Access resource1",
          "id": "<guid>",
          "isEnabled": true,
          "type": "User",
          "userConsentDescription": "Allow the app to access resource1 on your behalf.",
          "userConsentDisplayName": "Access resources",
          "value": "user_impersonation"
        }
    ],

атрибут oauth2RequiredPostResponse

Ключ Тип значения
oauth2RequiredPostResponse Булев

Указывает, разрешено ли в рамках запросов маркеров OAuth 2.0 идентификатор Microsoft Entra разрешить запросы POST, а не запросы GET. Значение по умолчанию равно false, указывающее, что разрешены только запросы GET.

Пример:

    "oauth2RequirePostResponse": false,

атрибут parentalControlSettings

Ключ Тип значения
parentalControlSettings Струна
  • countriesBlockedForMinors указывает страны и регионы, в которых приложение блокируется для несовершеннолетних.
  • legalAgeGroupRule указывает правило группы юридических возрастов, применимое к пользователям приложения. Можно задать значение Allow, , RequireConsentForPrivacyServices, RequireConsentForMinorsRequireConsentForKidsили BlockMinors.

Пример:

    "parentalControlSettings": {
        "countriesBlockedForMinors": [],
        "legalAgeGroupRule": "Allow"
    },

Атрибут passwordCredentials

Ключ Тип значения
passwordCredentials Коллекция

См. описание keyCredentials свойства.

Пример:

    "passwordCredentials": [
      {
        "customKeyIdentifier": null,
        "displayName": "Generated by App Service",
        "endDateTime": "2022-10-19T17:59:59.6521653Z",
        "hint": "Nsn",
        "keyId": "<guid>",
        "secretText": null,        
        "startDateTime":"2022-10-19T17:59:59.6521653Z"
      }
    ],

Атрибут preAuthorizedApplications

Ключ Тип значения
PreAuthorizedApplications Коллекция

Выводит список приложений и запрашиваемых разрешений для неявного согласия. Требуется, чтобы администратор предоставил согласие приложению. Предавторизованные приложения не требуют от пользователя согласия на запрошенные разрешения. Разрешения, перечисленные в preAuthorizedApplications, не требуют согласия пользователя. Однако любые дополнительные запрошенные разрешения, не перечисленные в preAuthorizedApplications, требуют согласия пользователя.

Пример:

    "preAuthorizedApplications": [
       {
          "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
          "permissionIds": [
             "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
            ]
        }
    ],

Атрибут publisherDomain

Ключ Тип значения
publisherDomain Струна

Проверенный домен издателя для приложения. Только для чтения.

Пример:

    "publisherDomain": "{tenant}.onmicrosoft.com",

Атрибут replyUrlsWithType

Ключ Тип значения
replyUrlsWithType Коллекция

Это свойство с несколькими значениями содержит список зарегистрированных redirect_uri значений, которые идентификатор Microsoft Entra принимает в качестве назначений при возврате маркеров. Каждое значение URI должно содержать связанное значение типа приложения. Поддерживаемые значения типов:

  • Web
  • InstalledClient
  • Spa

Дополнительные сведения см. в разделе "Ограничения и ограничения ответа".

Пример:

    "replyUrlsWithType": [
       {
          "url": "https://localhost:4400/services/office365/redirectTarget.html",
          "type": "InstalledClient"
       }
    ],

атрибут requiredResourceAccess

Ключ Тип значения
requiredResourceAccess Коллекция

С динамическим согласием requiredResourceAccess обеспечивает взаимодействие с согласием администратора и взаимодействие с согласием пользователей, использующих статическое согласие. Однако этот параметр не приводит к общему варианту предоставления согласия пользователя.

  • resourceAppId — уникальный идентификатор ресурса, к которому требуется доступ к приложению. Это значение должно быть равно идентификатору appId, объявленному в целевом приложении ресурсов.
  • resourceAccess — это массив, который содержит области разрешений OAuth2.0 и роли приложения, необходимые приложению из указанного ресурса. Содержит id и type значения указанных ресурсов.

Пример:

    "requiredResourceAccess": [
        {
            "resourceAppId": "00000002-0000-0000-c000-000000000000",
            "resourceAccess": [
                {
                    "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
                    "type": "Scope"
                }
            ]
        }
    ],

атрибут samlMetadataUrl

Ключ Тип значения
samlMetadataUrl Струна

URL-адрес метаданных SAML для приложения.

Пример:

    "samlMetadataUrl": "https://MyRegisteredAppSAMLMetadata",

Атрибут signInUrl

Ключ Тип значения
signInUrl Струна

Указывает URL-адрес домашней страницы приложения.

Пример:

    "signInUrl": "https://MyRegisteredApp",

Атрибут signInAudience

Ключ Тип значения
signInAudience Струна

Указывает, какие учетные записи Майкрософт поддерживаются для текущего приложения. Поддерживаемые значения:

  • AzureADMyOrg — Пользователи с рабочей или учебной учетной записью Майкрософт в клиенте Microsoft Entra организации (например, один клиент)
  • AzureADMultipleOrgs — Пользователи с рабочей или учебной учетной записью Майкрософт в клиенте Microsoft Entra любой организации (например, мультитенантный)
  • AzureADandPersonalMicrosoftAccount — Пользователи с личной учетной записью Майкрософт или рабочей или учебной учетной записью в клиенте Microsoft Entra любой организации
  • PersonalMicrosoftAccount — Личные учетные записи, используемые для входа в такие службы, как Xbox и Skype.

Пример:

    "signInAudience": "AzureADandPersonalMicrosoftAccount",

Атрибут тегов

Ключ Тип значения
Теги Массив строк

Пользовательские строки, которые можно использовать для классификации и идентификации приложения.

Пример:

    "tags": [
       "ProductionApp"
    ],

Распространенные проблемы

Ограничения манифеста

Манифест приложения имеет несколько атрибутов, которые называются коллекциями; например, appRoles, keyCredentials, knownClientApplications, identifierUris, redirectUris, requiredResourceAccess и oauth2Permissions. В полном манифесте приложения для любого приложения общее количество записей во всех коллекциях, объединенных, было ограничено 1200. Если вы ранее указали 100 URI перенаправления в манифесте приложения, то осталось только 1100 оставшихся записей для использования во всех остальных коллекциях, объединенных в манифест.

Заметка

Если вы попытаетесь добавить более 1200 записей в манифест приложения, может появиться сообщение об ошибке "Не удалось обновить приложение xxxxxxx. Сведения об ошибке: размер манифеста превысил его предел. Уменьшите количество значений и повторите запрос".

Неподдерживаемые атрибуты

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

Регистрация приложений (устаревшая версия) Регистрация приложений
availableToOtherTenants signInAudience
displayName name
errorUrl -
homepage signInUrl
objectId Id
publicClient allowPublicClient
replyUrls replyUrlsWithType

Описание этих атрибутов см. в разделе справочника по манифесту.

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

  • "Не удалось обновить приложение xxxxxxx. Сведения об ошибке: недопустимый идентификатор объекта "не определен". []."
  • "Не удалось обновить приложение xxxxxxx. Сведения об ошибке: указано одно или несколько значений свойств, недопустимы. []."
  • "Не удалось обновить приложение xxxxxxx. Сведения об ошибке: не разрешено задать availableToOtherTenants в этой версии API для обновления. []."
  • "Не удалось обновить приложение xxxxxxx. Сведения об ошибке. Обновления свойства "replyUrls" не разрешены для этого приложения. Используйте вместо этого свойство "replyUrlsWithType". []."
  • "Не удалось обновить приложение xxxxxxx. Сведения об ошибке: значение без имени типа найдено, и ожидаемый тип недоступен. При указании модели каждое значение в полезных данных должно иметь тип, который может быть указан в полезных данных, явным образом вызывающим объектом или неявно выводим из родительского значения. []"

При появлении одной из этих ошибок рекомендуется выполнить следующие действия:

  1. Измените атрибуты отдельно в редакторе манифеста вместо отправки ранее скачаемого манифеста. Используйте таблицу ссылок манифеста, чтобы понять синтаксис и семантику старых и новых атрибутов, чтобы можно было успешно редактировать интересующие вас атрибуты.
  2. Если рабочий процесс требует сохранения манифестов в исходном репозитории для последующего использования, мы рекомендуем повторно использовать сохраненные манифесты в репозитории с тем, который вы видите в интерфейсе Регистрация приложений.

Дальнейшие действия

  • Дополнительные сведения о связи между приложениями и объектами субъекта-службы см. в разделе "Объекты приложения и субъекта-службы" в идентификаторе Microsoft Entra.
  • См. глоссарий разработчика платформа удостоверений Майкрософт для определений некоторых основных концепций разработчиков платформа удостоверений Майкрософт.

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