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


Общие сведения о манифесте приложения (формат 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, выполните следующие действия.

  1. Войдите в Центр администрирования Microsoft Entra как минимум разработчик приложений.

  2. Перейдите к >

  3. Выберите приложение, которое вам нужно настроить.

  4. На странице Обзор выберите раздел Манифест. Откроется веб-редактор манифеста, в котором можно изменить манифест. Также здесь можно выбрать команду Скачать, чтобы изменить манифест локально и применить к приложению обновленную версию с помощью команды Отправить.

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

В этом разделе описываются атрибуты, найденные в манифесте приложения 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-адреса логотипа.

Обратите внимание на следующие условия.

Пример:

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.

Определения основных концепций разработчика платформы идентификации Майкрософт см. в разделе Глоссарий разработчика платформы удостоверений Майкрософт.

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