Поделиться через


Манифест приложения 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 Int32, допускающий значение NULL

Указывает версию маркера доступа, ожидаемую ресурсом. Этот параметр меняет версию и формат 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",

Атрибут optionalClaims

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

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

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

Пример:

    "optionalClaims": null,

Атрибут identifierUris

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

Определяемые пользователем URI, которые однозначно определяют веб-приложение в клиенте Microsoft Entra или проверенном домене клиента. Когда приложение используется в качестве приложения ресурса, значение identifierUri используется для уникальной идентификации и доступа к ресурсу. Для общедоступного клиентского приложения он не может иметь значение для идентификаторов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://<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/00001111-aaaa-2222-bbbb-3333cccc4444",

Атрибут informationalUrls

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

Указывает ссылки на условия предоставления услуг и заявление о конфиденциальности приложения. Условия обслуживания и заявление о конфиденциальности отображаются в окне запроса согласия пользователя. Дополнительные сведения см. в статье "Практическое руководство. Добавление условий обслуживания и заявления о конфиденциальности для зарегистрированных приложений 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. Если в это значение ввести appID клиентского приложения, пользователю нужно будет только единожды предоставить согласие на использование клиентского приложения. Идентификатор 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 Строка

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

Пример:

    "name": "MyRegisteredApp",

Атрибут oauth2AllowImplicitFlow

Ключ Тип значения
oauth2AllowImplicitFlow Логический

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

Пример:

    "oauth2AllowImplicitFlow": false,

Атрибут oauth2AllowIdTokenImplicitFlow

Ключ Тип значения
oauth2AllowIdTokenImplicitFlow Логический

Определяет, может ли это веб-приложение запрашивать маркеры идентификатора неявного потока OAuth 2.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, 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"
      }
    ],

Атрибут preAuthorizedApplications

Ключ Тип значения
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

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

Пример:

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

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

Атрибут signInUrl

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

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

Пример:

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

Атрибут signInAudience

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

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

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

Пример:

    "signInAudience": "AzureADandPersonalMicrosoftAccount",

Атрибут tags

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

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

Пример:

    "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

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

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

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

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

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

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

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