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

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

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

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

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

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

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

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

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

Атрибут идентификатора

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

Пример:

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

Атрибут acceptMappedClaims

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

Пример:

"acceptMappedClaims": true

запрошенный атрибутAccessTokenVersion

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

Используемая конечная точка версии 1.0 или 2.0 выбирается клиентом и влияет только на версию id_tokens. В ресурсах необходимо явным образом настраивать requestedAccessTokenVersion для указания поддерживаемого формата маркера доступа.

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

Если signInAudience — AzureADandPersonalMicrosoftAccount, значением должно быть 2.

Пример:

"requestedAccessTokenVersion": 2

Атрибут addIns

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

Пример:

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

Атрибут allowPublicClient

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

Пример:

"allowPublicClient": false

Атрибут appId

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

Пример:

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

Атрибут 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

Не поддерживается.

Атрибут groupMembershipClaims

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

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

Пример:

"groupMembershipClaims": "SecurityGroup"

Атрибут optionalClaims

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

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

Пример:

"optionalClaims": null

Атрибут identifierUris

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

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

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

Пример:

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

Атрибут informationalUrls

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

Пример:

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

Атрибут 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

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

Пример:

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

Атрибут logoUrl

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

Пример:

"logoUrl": "https://MyRegisteredAppLogo"

Атрибут logoutUrl

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

Пример:

"logoutUrl": "https://MyRegisteredAppLogout"

Атрибут name

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

Пример:

"name": "MyRegisteredApp"

Атрибут oauth2AllowImplicitFlow

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

Пример:

"oauth2AllowImplicitFlow": false

Атрибут oauth2AllowIdTokenImplicitFlow

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

Пример:

"oauth2AllowIdTokenImplicitFlow": false

Атрибут 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

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

Пример:

"oauth2RequirePostResponse": false

Атрибут parentalControlSettings

• countriesBlockedForMinors указывает страны или регионы, в которых приложение заблокировано для несовершеннолетних.
• legalAgeGroupRule определяет правило возрастной группы, применяемое к пользователям приложения. Можно установить Allow, RequireConsentForPrivacyServices, RequireConsentForMinors, RequireConsentForKids или BlockMinors.

Пример:

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

Атрибут 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": "{tenant}.onmicrosoft.com"

Атрибут replyUrlsWithType

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

• Web
• InstalledClient
• Spa

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

Пример:

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

Атрибут 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

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

Пример:

"samlMetadataUrl": "https://MyRegisteredAppSAMLMetadata"

Атрибут signInUrl

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

Пример:

"signInUrl": "https://MyRegisteredApp"

Атрибут signInAudience

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

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

Пример:

"signInAudience": "AzureADandPersonalMicrosoftAccount"

Атрибут tags

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

Отдельные теги должны быть от 1 до 256 символов (включительно). Пробелы или повторяющиеся теги не допускаются. Определенное ограничение на количество тегов, которые можно добавить, не ограничивается общими ограничениями размера манифеста.

Пример:

"tags": [
    "ProductionApp"
]

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

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

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

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

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

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

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

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

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

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

Следующие шаги

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

Оставляйте свои замечания и пожелания в разделе ниже. Ваши отзывы помогают нам улучшать содержимое веб-сайта.