Общие сведения о манифесте приложения (формат Microsoft Graph)
Манифест приложения содержит все атрибуты и их значения регистрации приложения в платформа удостоверений Майкрософт.
Манифест приложения Microsoft Graph — это объект JSON, представляющий регистрацию приложения. Он также называется типом ресурса приложения Microsoft Graph или объектом приложения Microsoft Graph (объектом приложения). Он содержит все атрибуты и их значения регистрации приложения.
Объект приложения, полученный с помощью метода Get Application Microsoft Graph, является тем же объектом JSON, который отображается на странице манифеста регистрации приложений в Центре администрирования Microsoft Entra.
Примечание.
Для приложений, зарегистрированных в вашей личной учетной записи Майкрософт (учетная запись MSA), вы будете продолжать просматривать манифесты приложений в формате Azure AD Graph в Центре администрирования Microsoft Entra до дальнейшего уведомления. Дополнительные сведения см. в манифесте приложения Microsoft Entra (формат Azure AD Graph).
Настройка манифеста приложения Microsoft Graph
Если вы хотите программно настроить манифест приложения Microsoft Graph, вы можете использовать API Microsoft Graph или пакет SDK Для Microsoft Graph PowerShell.
Манифест приложения можно также настроить в Центре администрирования Microsoft Entra. Большинство атрибутов можно настроить с помощью элемента пользовательского интерфейса в Регистрация приложений. Однако некоторые атрибуты необходимо настроить, изменив манифест приложения непосредственно на странице манифеста манифеста.
Настройка манифеста приложения в Центре администрирования Microsoft Entra
Чтобы настроить манифест приложения Microsoft Graph, выполните следующие действия.
Войдите в Центр администрирования Microsoft Entra как минимум разработчик приложений.
Перейдите к >
Выберите приложение, которое вам нужно настроить.
На странице Обзор выберите раздел Манифест. Откроется веб-редактор манифеста, в котором можно изменить манифест. Также здесь можно выбрать команду Скачать, чтобы изменить манифест локально и применить к приложению обновленную версию с помощью команды Отправить.
Справка по манифесту
В этом разделе описываются атрибуты, найденные в манифесте приложения Microsoft Graph.
Атрибут идентификатора
Ключ | Тип значения |
---|---|
id | Строка |
Это свойство называется идентификатором объекта в Центре администрирования Microsoft Entra. Это уникальный идентификатор объекта приложения в каталоге.
Этот идентификатор не является идентификатором, используемым для идентификации приложения в любой транзакции протокола. Он используется для ссылки на объект в запросах к каталогу.
Это непустимый и доступный только для чтения атрибут.
Пример:
"id": "f7f9acfc-ae0c-4d6c-b489-0a81dc1652dd",
Атрибут appId
Ключ | Тип значения |
---|---|
appId | Строка |
Это свойство называется идентификатором приложения (клиента) в Центре администрирования Microsoft Entra. Это уникальный идентификатор объекта приложения в каталоге.
Этот идентификатор используется для идентификации приложения в любой транзакции протокола.
Это непустимый и доступный только для чтения атрибут.
Пример:
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
Атрибут addIns
Ключ | Тип значения |
---|---|
addIns | Коллекция |
Определяет пользовательское поведение, которое может использоваться службой для вызова приложения в конкретных контекстах. Например, приложения, которые могут визуализировать файловые потоки, могут задавать свойство addIns
для функции "FileHandler". Этот параметр позволяет службам, таким как Microsoft 365, вызывать приложение в контексте документа, над которым работает пользователь.
Пример:
"addIns": [
{
"id": "968A844F-7A47-430C-9163-07AE7C31D407",
"type":" FileHandler",
"properties": [
{
"key": "version",
"value": "2"
}
]
}
],
appRoles
Ключ | Тип значения |
---|---|
appRoles | Коллекция |
Указывает коллекцию ролей, которые может объявить приложение. Эти роли могут назначаться пользователям, группам или субъектам-службам. Ознакомьтесь с дополнительными сведениями и примерами в статье Добавление ролей приложения в приложение и их получение в токене.
Пример:
"appRoles": [
{
"allowedMemberTypes": [
"User"
],
"description": "Read-only access to device information",
"displayName": "Read Only",
"id": "00001111-aaaa-2222-bbbb-3333cccc4444",
"isEnabled": true,
"value": "ReadOnly"
}
],
groupMembershipClaims
Ключ | Тип значения |
---|---|
groupMembershipClaims | Строка |
Настраивает утверждение groups
, выданное в маркере пользователя или маркере доступа OAuth 2.0, которого ожидает приложение. Чтобы задать этот атрибут, используйте одно из следующих допустимых строковых значений.
None
-
SecurityGroup
(для групп безопасности и ролей Microsoft Entra) -
ApplicationGroup
(этот параметр включает только группы, которые назначены приложению). -
DirectoryRole
(получает роли каталога Microsoft Entra, в которые пользователь входит) -
All
(это возвращает все группы безопасности, группы рассылки и роли каталога Microsoft Entra, вошедшего в систему пользователя.
Пример:
"groupMembershipClaims": "SecurityGroup",
Атрибут optionalClaims
Ключ | Тип значения |
---|---|
optionalClaims | Строка |
Необязательные утверждения, возвращаемые в токене службы токенов безопасности для этого конкретного приложения.
Приложения, поддерживающие как личная учетная запись, так и идентификатор Microsoft Entra, не могут использовать необязательные утверждения. Однако приложения, зарегистрированные только для идентификатора Microsoft Entra с помощью конечной точки версии 2.0, могут получить необязательные утверждения, запрошенные в манифесте. Дополнительные сведения см. в статье Необязательные утверждения.
Пример:
"optionalClaims":{
"idToken": [{"@odata.type": "microsoft.graph.optionalClaim"}],
"accessToken": [{"@odata.type": "microsoft.graph.optionalClaim"}],
"saml2Token": [{"@odata.type": "microsoft.graph.optionalClaim"}]
}
Атрибут identifierUris
Ключ | Тип значения |
---|---|
identifierUris | Массив строк |
Определяемые пользователем URI, которые однозначно определяют веб-приложение в клиенте Microsoft Entra или проверенном домене клиента. Когда приложение используется в качестве приложения ресурса, значение identifierUri используется для уникальной идентификации и доступа к ресурсу.
Поддерживаются следующие форматы 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://<string>.<verifiedCustomDomain> | https://product.contoso.com |
https://<string>.<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/fc4d2d73-d05a-4a9b-85a8-4f2b3a5f38ed",
Атрибут 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
}
],
Атрибут displayName
Ключ | Тип значения |
---|---|
displayName | Строка |
Отображаемое имя приложения.
Пример:
" displayName": "MyRegisteredApp",
Атрибут oauth2RequiredPostResponse
Ключ | Тип значения |
---|---|
oauth2RequiredPostResponse | Логический |
Указывает, разрешено ли в рамках запросов маркеров OAuth 2.0 идентификатор Microsoft Entra разрешить запросы POST, а не запросы GET. Значение по умолчанию — false. В таком случае будут разрешены только запросы GET.
Пример:
"oauth2RequirePostResponse": false,
Атрибут parentalControlSettings
Ключ | Тип значения |
---|---|
parentalControlSettings | Строка |
-
countriesBlockedForMinors
указывает страны или регионы, в которых приложение заблокировано для несовершеннолетних. -
legalAgeGroupRule
определяет правило возрастной группы, применяемое к пользователям приложения. Можно установитьAllow
,RequireConsentForPrivacyServices
,RequireConsentForMinors
,RequireConsentForKids
или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"
}
],
Атрибут publisherDomain
Ключ | Тип значения |
---|---|
publisherDomain | Строка |
Домен проверенного издателя для приложения. Только чтение. Чтобы изменить домен издателя регистрации приложения, выполните действия, описанные в разделе "Настройка домена издателя приложения".
Пример:
"publisherDomain": "{tenant}.onmicrosoft.com",
Атрибут requiredResourceAccess
Ключ | Тип значения |
---|---|
requiredResourceAccess | Коллекция |
При динамическом согласии requiredResourceAccess
обеспечивает процедуру использования согласия администратора и согласия пользователя для пользователей, которые используют статическое согласие. Однако этот параметр не предоставляет процедуру использования согласия пользователя для общего случая.
-
resourceAppId
— уникальный идентификатор для ресурса, доступ к которому нужен приложению. Это значение должно соответствовать appId, который был объявлен в целевом приложении ресурса. -
resourceAccess
— массив, в котором перечислены области разрешений OAuth 2.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",
Атрибут signInAudience
Ключ | Тип значения |
---|---|
signInAudience | Строка |
Указывает, какие учетные записи Майкрософт поддерживаются для текущего приложения. Поддерживаются значения:
-
AzureADMyOrg
— Пользователи с рабочей или учебной учетной записью Майкрософт в клиенте Microsoft Entra организации (например, один клиент) -
AzureADMultipleOrgs
— Пользователи с рабочей или учебной учетной записью Майкрософт в клиенте Microsoft Entra любой организации (например, мультитенантный) -
AzureADandPersonalMicrosoftAccount
— Пользователи с личной учетной записью Майкрософт или рабочей или учебной учетной записью в клиенте Microsoft Entra любой организации -
PersonalMicrosoftAccount
. Личные учетные записи, которые используются для входа в службы, такие как Xbox и Skype.
Пример:
"signInAudience": "AzureADandPersonalMicrosoftAccount",
Атрибут tags
Ключ | Тип значения |
---|---|
tags | Массив строк |
Пользовательские строки, которые могут использоваться для классификации и идентификации приложения.
Отдельные теги должны быть от 1 до 256 символов (включительно). Пробелы или повторяющиеся теги не допускаются. Определенное ограничение на количество тегов, которые можно добавить, не ограничивается общими ограничениями размера манифеста.
Пример:
"tags": [
"ProductionApp"
],
Атрибут isFallbackPublicClient
Ключ | Тип значения |
---|---|
isFallbackPublicClient | Логический |
Указывает резервный тип приложения как общедоступный клиент, например установленное приложение, работающее на мобильном устройстве. Значение по умолчанию этого атрибута равно false, что означает, что резервный тип приложения является конфиденциальным клиентом, например веб-приложением. Существуют определенные сценарии, в которых идентификатор Microsoft Entra не может определить тип клиентского приложения. Например, поток ROPC, в котором он настроен, без указания URI перенаправления. В этих случаях идентификатор Microsoft Entra интерпретирует тип приложения на основе значения этого свойства.
Пример:
"isFallbackPublicClient ": "false",
атрибут сведений
Ключ | Тип значения |
---|---|
info | информационныйUrl |
Указывает основные сведения о профиле приложения, включая маркетинг, поддержку приложения, условия обслуживания, заявление о конфиденциальности и URL-адреса логотипа.
Обратите внимание на следующие условия.
"logoUrl" — это свойство только для чтения. Его нельзя изменить в манифесте приложения. Перейдите на страницу фирменной символики и свойства в нужной регистрации приложения и используйте команду "Отправить новый логотип" для отправки нового логотипа.
Условия обслуживания и заявление о конфиденциальности отображаются в окне запроса согласия пользователя. Дополнительные сведения см. в статье "Практическое руководство. Добавление условий обслуживания и заявления о конфиденциальности для зарегистрированных приложений Microsoft Entra".
Пример:
Info: {
"termsOfService": "https://MyRegisteredApp/termsofservice",
"support": "https://MyRegisteredApp/support",
"privacy": "https://MyRegisteredApp/privacystatement",
"marketing": "https://MyRegisteredApp/marketing"
"logoUrl": "https://MyRegisteredApp/logoUrl",
}
Атрибут API
Ключ | Тип значения |
---|---|
api | Тип ресурса apiApplication |
Задает параметры для приложения, реализующего веб-API. Он включает пять свойств:
Свойство | Type | Описание |
---|---|---|
acceptMappedClaims | Логический | Если задано значение true, приложение может использовать сопоставление утверждений без указания пользовательского ключа подписи. Приложения, получающие маркеры, полагаются на то, что значения утверждений достоверно выдаются идентификатором Microsoft Entra и не могут быть изменены. Но при изменении содержимого маркера с помощью политик сопоставления утверждений эти предположения могут стать неверными. Приложения должны явным образом подтвердить то, что маркеры были изменены создателем политики сопоставления утверждений, чтобы защитить себя от политик сопоставления утверждений, созданных злоумышленниками. Предупреждение. Не устанавливайте свойство AcceptMappedClaims значение true для мультитенантных приложений, что позволяет злоумышленникам создавать политики сопоставления утверждений для приложения. |
knownClientApplications | коллекция | Используется для объединения согласия, если у вас есть решение, которое содержит две части: клиентское приложение и пользовательское приложение веб-API. Если для этого значения задан идентификатор приложения клиента, пользователь будет давать согласие только один раз клиентскому приложению. Идентификатор Microsoft Entra знает, что согласие клиента означает неявное согласие на веб-API и автоматически подготавливает субъекты-службы для обоих API одновременно. И клиентское приложение, и веб-API должны быть зарегистрированы в одном и том же клиенте. |
oauth2PermissionScopes | Коллекция permissionScope | Определение делегированных разрешений, предоставляемых веб-API, представленных этой регистрацией приложения. Эти делегированные разрешения могут запрашиваться клиентским приложением и могут предоставляться пользователями или администраторами во время согласия. Делегированные разрешения иногда называются областями OAuth 2.0. |
preAuthorizedApplications | Коллекция preAuthorizedApplication | Выводит список клиентских приложений, которые предварительно несанкционированны с указанными делегированными разрешениями для доступа к API этого приложения. Пользователям не требуется предоставить согласие на любое предварительно несанкционированное приложение (для указанных разрешений). Однако любые другие разрешения, не перечисленные в preAuthorizedApplications (запрошенные с помощью добавочного согласия, например), потребуют согласия пользователя. |
requestedAccessTokenVersion | Int32 | Указывает версию маркера доступа, ожидаемую этим ресурсом. В результате изменяются версия и формат JWT, созданного независимо от конечной точки или клиента, используемых для запроса маркера доступа. Используемая конечная точка версии 1.0 или 2.0 выбирается клиентом и влияет только на версию id_tokens. Ресурсы должны явно настроить запрошенныйAccessTokenVersion , чтобы указать поддерживаемый формат маркера доступа. Возможные значения для запрошенногоAccessTokenVersion : 1, 2 или NULL. Если значение равно null, по умолчанию используется значение 1, соответствующее конечной точке версии 1.0. Если signInAudience в приложении настроен как AzureADandPersonalMicrosoftAccount или PersonalMicrosoftAccount, значение этого свойства должно иметь значение 2. |
Пример:
Api:{
"acceptMappedClaims": true,
"knownClientApplications": ["f7f9acfc-ae0c-4d6c-b489-0a81dc1652dd"],
"oauth2PermissionScopes": [
{
"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"
}
],
"preAuthorizedApplications": [{
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"permissionIds": [
"8748f7db-21fe-4c83-8ab5-53033933c8f1"
]
}],
"requestedAccessTokenVersion": 2
}
веб-атрибут
Ключ | Тип значения |
---|---|
web | Тип ресурса webApplication |
Задает параметры для веб-приложения. Он включает четыре свойства.
Свойство | Type | Описание |
---|---|---|
homePageUrl | Строка | Домашняя страница или целевая страница приложения. |
implicitGrantSettings | implicitGrantSettings | Указывает, может ли веб-приложение запрашивать маркеры с помощью неявного потока OAuth 2.0. |
logoutUrl | Строка | Указывает URL-адрес, используемый службой авторизации Майкрософт для выхода пользователя с помощью интерфейсного канала, внутреннего канала или протокола выхода SAML. |
redirectUris | Коллекция строк | Указывает URL-адреса, в которых маркеры пользователей отправляются для входа или URI перенаправления, в которых коды авторизации OAuth 2.0 и маркеры доступа отправляются на веб-платформе. |
Пример:
web: {
"homePageUrl": "String",
"implicitGrantSettings": {
"enableIdTokenIssuance": "Boolean",
"enableAccessTokenIssuance": "Boolean"}
"logoutUrl": "String",
"redirectUris": ["String"]
}
Атрибут spa
Ключ | Тип значения |
---|---|
минеральный источник | Тип ресурса spaApplication |
Задает параметры для одностраничного приложения, включая URL-адреса выхода и перенаправления URI для кодов авторизации и маркеров доступа.
Свойство | Type | Описание |
---|---|---|
redirectUris | Коллекция строк | Указывает URL-адреса, в которых маркеры пользователей отправляются для входа или URI перенаправления, в которых отправляются коды авторизации OAuth 2.0 и маркеры доступа. |
Пример:
spa: {
"redirectUris": ["String"]
}
Атрибут publicClient
Ключ | Тип значения |
---|---|
publicClient | Тип ресурса publicClientApplication |
Задает параметры для приложений, отличных от веб-приложений или неweb API (например, iOS, Android, mobile или других общедоступных клиентов, таких как установленное приложение, работающее на настольном устройстве).
Свойство | Type | Описание |
---|---|---|
redirectUris | Коллекция строк | Указывает URL-адреса, в которых маркеры пользователей отправляются для входа или URI перенаправления, в которых отправляются коды авторизации OAuth 2.0 и маркеры доступа. |
Пример:
publicClient: {
"redirectUris": ["String"]
}
Распространенные проблемы
Ограничения манифеста
Манифест приложения имеет несколько атрибутов, которые называются коллекциями; например, appRoles, keyCredentials, knownClientApplications, identifierUris, redirectUris, requiredResourceAccess и oauth2PermissionScopes. В полном манифесте приложения для любого приложения общее число записей во всех коллекциях вместе не может составлять более 1200. Если вы ранее указали 100 appRoles в манифесте приложения, то осталось только 1100 оставшихся записей для использования во всех остальных коллекциях, объединенных в манифест.
Примечание.
Если вы попытаетесь добавить более 1200 записей в манифест приложения, может появиться сообщение об ошибке "Не удалось обновить приложение xxxxxxx. Сведения об ошибке: размер манифеста превысил его предел. Уменьшите количество значений и повторите запрос".
Устранение неполадок при миграции манифеста из формата Azure AD Graph в формат Microsoft Graph
При отправке ранее скачаированного манифеста приложения в формате Azure AD Graph может появиться следующая ошибка:
Не удалось обновить приложение {имя приложения}. Сведения об ошибке: недопустимое свойство "{имя свойства}".**
Это может произойти из-за миграции из Azure AD Graph в манифест приложения Microsoft Graph. Во-первых, следует проверить, находится ли манифест приложения в формате Graph Azure AD. Если это так, необходимо преобразовать манифест приложения в формат Microsoft Graph.
Не удается найти атрибут TrustedCertificateSubjects
Атрибут trustedCertificateSubjects является внутренним свойством Майкрософт. Центр администрирования Microsoft Entra отображает версию 1.0 манифеста приложения Microsoft Graph, атрибут trustedCertificateSubjects присутствует только в бета-версии манифеста приложения (формат Microsoft Graph). Продолжайте изменять это свойство с помощью манифеста приложения (формат Azure AD Graph) в Центре администрирования Microsoft Entra.
ОШИБКА: приложение не найдено. Если приложение было создано, подождите несколько минут и обновите страницу.**
Если приложение не было создано, может возникнуть эта ошибка, так как вы добавили недопустимый атрибут в манифест приложения Microsoft Graph. Просмотрите различия атрибутов между форматами Azure AD Graph и Microsoft Graph и проверьте, добавлены ли атрибуты, которые не поддерживаются в формате Microsoft Graph версии 1.0, показанной на портале.
Следующие шаги
Дополнительные сведения о связи между приложениями и объектами субъекта-службы см. в разделе "Объекты приложения и субъекта-службы" в идентификаторе Microsoft Entra.
Определения основных концепций разработчика платформы идентификации Майкрософт см. в разделе Глоссарий разработчика платформы удостоверений Майкрософт.
Оставляйте свои замечания и пожелания в разделе ниже. Ваши отзывы помогают нам улучшать содержимое веб-сайта.