Как предоставить приложению необязательные утвержденияHow to: Provide optional claims to your app

Разработчики приложений могут использовать дополнительные утверждения в своих приложениях Azure AD, чтобы указать утверждения, которые нужно поместить в токены, отправляемые в приложение.Application developers can use optional claims in their Azure AD applications to specify which claims they want in tokens sent to their application.

Необязательные утверждения можно использовать, чтобы:You can use optional claims to:

  • выбрать дополнительные утверждения для включения в токены для приложения;Select additional claims to include in tokens for your application.
  • Изменение поведения определенных утверждений, которые платформа Microsoft Identity возвращает в токенах.Change the behavior of certain claims that Microsoft identity platform returns in tokens.
  • добавлять пользовательские утверждения для приложения и обращаться к ним.Add and access custom claims for your application.

Список стандартных утверждений см. в документации по утверждениям маркера доступа и id_token.For the lists of standard claims, see the access token and id_token claims documentation.

Несмотря на то, что необязательные утверждения поддерживаются в маркерах формата версии 1.0 и 2.0, а также в маркерах SAML, большую ценность они предоставляют при переходе с версии 1.0 на версию 2.0.While optional claims are supported in both v1.0 and v2.0 format tokens, as well as SAML tokens, they provide most of their value when moving from v1.0 to v2.0. Одна из целей конечной точки платформы удостоверений Майкрософт версии 2.0 — уменьшение размеров маркеров для обеспечения оптимальной производительности для клиентов.One of the goals of the v2.0 Microsoft identity platform endpoint is smaller token sizes to ensure optimal performance by clients. В результате нескольких утверждений, ранее включенных в маркеры доступа и идентификаторов, больше нет в токенах версии 2.0 и их нужно запрашивать специально для каждого приложения.As a result, several claims formerly included in the access and ID tokens are no longer present in v2.0 tokens and must be asked for specifically on a per-application basis.

Таблица 1. ПрименимостьTable 1: Applicability

Тип учетной записиAccount Type маркеры версии 1.0;v1.0 tokens маркеры версии 2.0.v2.0 tokens
Личная учетная запись МайкрософтPersonal Microsoft account НедоступноN/A ПоддерживаетсяSupported
Учетная запись Azure ADAzure AD account ПоддерживаетсяSupported ПоддерживаетсяSupported

Набор необязательных утверждений версий 1.0 и 2.0v1.0 and v2.0 optional claims set

Набор необязательных утверждений доступен по умолчанию для использования приложениями, перечисленными ниже.The set of optional claims available by default for applications to use are listed below. Чтобы добавить настраиваемые необязательные утверждения для приложения, ознакомьтесь с разделом Расширения каталога ниже.To add custom optional claims for your application, see Directory Extensions, below. При добавлении утверждений в маркер доступа утверждения применяются к маркерам доступа, запрошенным для приложения (веб-API), а не к утверждениям, запрошенным самим приложением.When adding claims to the access token, the claims apply to access tokens requested for the application (a web API), not claims requested by the application. Независимо от того, получил ли клиент доступ к вашему API, в маркере доступа, используемом при аутентификации с помощью API, будут присутствовать правильные данные.No matter how the client accesses your API, the right data is present in the access token that is used to authenticate against your API.

Примечание

Большую часть этих утверждений можно включить в JWT для токенов версии 1.0 и 2.0, кроме токенов SAML, за исключением оговоренных в столбце типов токенов.The majority of these claims can be included in JWTs for v1.0 and v2.0 tokens, but not SAML tokens, except where noted in the Token Type column. Учетные записи пользователей-получателей поддерживают подмножество этих утверждений, отмеченных в столбце "Тип пользователя".Consumer accounts support a subset of these claims, marked in the "User Type" column. Многие из перечисленных утверждений не применяются к пользователям-получателям (у них нет клиента, поэтому tenant_ctry не имеет значения).Many of the claims listed do not apply to consumer users (they have no tenant, so tenant_ctry has no value).

Таблица 2. Набор необязательных утверждений версий 1.0 и 2.0Table 2: v1.0 and v2.0 optional claim set

ИмяName ОписаниеDescription Тип маркераToken Type Тип пользователяUser Type ПримечанияNotes
auth_time Время, когда пользователь последний раз проходил аутентификацию.Time when the user last authenticated. Ознакомьтесь со спецификацией OpenID Connect.See OpenID Connect spec. JWTJWT
tenant_region_scope Регион клиента ресурсаRegion of the resource tenant JWTJWT
sid ИД сеанса, используемый для выхода пользователя из конкретного сеанса.Session ID, used for per-session user sign-out. JWTJWT Личные учетные записи и учетные записи Azure AD.Personal and Azure AD accounts.
platf Платформа устройстваDevice platform JWTJWT Только для управляемых устройств, которые могут проверить тип устройства.Restricted to managed devices that can verify device type.
verified_primary_email Источник: PrimaryAuthoritativeEmail пользователяSourced from the user's PrimaryAuthoritativeEmail JWTJWT
verified_secondary_email Источник: SecondaryAuthoritativeEmail пользователяSourced from the user's SecondaryAuthoritativeEmail JWTJWT
vnet Сведения об описателе виртуальной сети.VNET specifier information. JWTJWT
fwd IP-адрес.IP address. JWTJWT Добавляет исходный IPv4-адрес запрашивающего клиента (при использовании внутри виртуальной сети)Adds the original IPv4 address of the requesting client (when inside a VNET)
ctry Страна/регион пользователяUser's country/region JWTJWT Azure AD возвращает необязательное утверждение ctry, если оно имеется, и значением утверждения является стандартный двухбуквенный код страны/региона, например FR, JP, SZ и т. д.Azure AD returns the ctry optional claim if it's present and the value of the claim is a standard two-letter country/region code, such as FR, JP, SZ, and so on.
tenant_ctry Страна/регион ресурса клиентаResource tenant's country/region JWTJWT
xms_pdl Предпочтительное расположение данныхPreferred data location JWTJWT Для клиентов с несколькими регионами предпочтительным расположением данных является трехбуквенный код, показывающий, в каком географическом регионе находится пользователь.For Multi-Geo tenants, the preferred data location is the three-letter code showing the geographic region the user is in. Дополнительные сведения см. в документации по Azure AD Connect, посвященной предпочтительному расположению данных.For more info, see the Azure AD Connect documentation about preferred data location.
Например: APC для Азиатско-Тихоокеанского региона.For example: APC for Asia Pacific.
xms_pl Предпочитаемый язык пользователяUser preferred language JWTJWT Предпочитаемый язык пользователя, если задан.The user's preferred language, if set. Источник: домашний клиент пользователя в сценариях гостевого доступа.Sourced from their home tenant, in guest access scenarios. Формат: ЯЯ-СС ("en-us").Formatted LL-CC ("en-us").
xms_tpl Предпочитаемый язык клиентаTenant preferred language JWTJWT Предпочитаемый язык клиента ресурса, если задан.The resource tenant's preferred language, if set. Формат: ЯЯ ("en").Formatted LL ("en").
ztdid Идентификатор развертывания без участия пользователяZero-touch Deployment ID JWTJWT Идентификатор устройства, используемый для Windows AutoPilotThe device identity used for Windows AutoPilot
email Доступный адрес электронной почты для этого пользователя (если имеется).The addressable email for this user, if the user has one. JWT, SAMLJWT, SAML MSA, Azure ADMSA, Azure AD Это значение добавляется по умолчанию, если пользователь является гостем в клиенте.This value is included by default if the user is a guest in the tenant. Для управляемых пользователей (в клиенте) это значение должно запрашиваться посредством необязательного утверждения или, в версии 2.0, с использованием области OpenID.For managed users (the users inside the tenant), it must be requested through this optional claim or, on v2.0 only, with the OpenID scope. Адреса электронной почты для управляемых пользователей должны быть заданы на портале администрирования Office.For managed users, the email address must be set in the Office admin portal.
acct Состояние учетной записи пользователей в клиентеUsers account status in tenant JWT, SAMLJWT, SAML Если пользователь является членом клиента, это значение равно 0.If the user is a member of the tenant, the value is 0. Если он является гостем, это значение равно 1.If they are a guest, the value is 1.
groups Необязательный формат для утверждений группOptional formatting for group claims JWT, SAMLJWT, SAML Используется в сочетании с параметром GroupMembershipClaims в манифесте приложения, который также должен быть установлен.Used in conjunction with the GroupMembershipClaims setting in the application manifest, which must be set as well. Дополнительные сведения см. в разделе утверждения групп ниже.For details see Group claims below. Дополнительные сведения об утверждениях групп см. в разделе Настройка утверждений групп.For more information about group claims, see How to configure group claims
upn UserPrincipalNameUserPrincipalName JWT, SAMLJWT, SAML Несмотря на то, что это утверждение автоматически включается, можно указать его в качестве необязательного утверждения для присоединения дополнительных свойств, чтобы изменить его поведение в варианте использования гостевым пользователем.Although this claim is automatically included, you can specify it as an optional claim to attach additional properties to modify its behavior in the guest user case.
idtyp Тип токенаToken type Маркеры доступа JWTJWT access tokens Специальный: только в маркерах доступа "только приложение"Special: only in app-only access tokens Значение, app Если маркер является маркером только для приложения.Value is app when the token is an app-only token. Это наиболее точный способ, с помощью которого API определяет, является ли маркер маркером приложения или маркером приложения и пользователя.This is the most accurate way for an API to determine if a token is an app token or an app+user token.

Набор необязательных утверждений для версии 2.0v2.0-specific optional claims set

Эти утверждения всегда включаются в маркеры Azure AD версии 1.0, но не включаются в маркеры версии 2.0, если они не запрошены.These claims are always included in v1.0 Azure AD tokens, but not included in v2.0 tokens unless requested. Эти утверждения применяются только для JWT (маркеры идентификации и маркер доступа).These claims are only applicable for JWTs (ID tokens and Access Tokens).

Таблица 3. Необязательные утверждения, предназначенные только для версии 2.0Table 3: v2.0-only optional claims

Утверждение JWTJWT Claim ИмяName ОписаниеDescription ПримечанияNotes
ipaddr IP-адресIP Address IP-адрес, с которого клиент вошел в систему.The IP address the client logged in from.
onprem_sid Локальный идентификатор безопасностиOn-Premises Security Identifier
pwd_exp Срок действия пароляPassword Expiration Time Дата и время истечения срока действия пароля.The datetime at which the password expires.
pwd_url Изменить URL-адрес пароляChange Password URL URL-адрес, перейдя по которому пользователь может изменить свой пароль.A URL that the user can visit to change their password.
in_corp В корпоративной сетиInside Corporate Network Посылает сигнал, если клиент входит в корпоративную сеть.Signals if the client is logging in from the corporate network. В противном случае это утверждение не добавляется.If they're not, the claim isn't included. На основе параметров надежных IP-адресов в MFA.Based off of the trusted IPs settings in MFA.
family_name ФамилияLast Name Предоставляет фамилию пользователя, как определено в объекте пользователя.Provides the last name, surname, or family name of the user as defined in the user object.
"family_name":"Miller""family_name":"Miller"
Поддерживается в MSA и Azure AD.Supported in MSA and Azure AD. Требуется область profile.Requires the profile scope.
given_name ИмяFirst name Указывает личное имя пользователя, которое задано в объекте пользователя.Provides the first or "given" name of the user, as set on the user object.
"given_name": "Frank""given_name": "Frank"
Поддерживается в MSA и Azure AD.Supported in MSA and Azure AD . Требуется область profile.Requires the profile scope.
upn Имя участника-пользователяUser Principal Name Идентификатор пользователя, который можно использовать с параметром username_hint.An identifer for the user that can be used with the username_hint parameter. Не является долговременным идентификатором для пользователя и не должен использоваться для ключевых данных.Not a durable identifier for the user and should not be used to key data. См. в разделе Дополнительные свойства необязательных утверждений указанном ниже для конфигурации утверждения.See additional properties below for configuration of the claim. Требуется область profile.Requires the profile scope.

Дополнительные свойства необязательных утвержденийAdditional properties of optional claims

Некоторые необязательные утверждения можно настроить так, чтобы изменить способ возврата утверждения.Some optional claims can be configured to change the way the claim is returned. Эти дополнительные свойства используются в основном для переноса локальных приложений с различными требованиями к данным (например, include_externally_authenticated_upn_without_hash помогает при работе с клиентами, которые не обрабатывают метки хэширования (#) в имени участника-пользователя).These additional properties are mostly used to help migration of on-premises applications with different data expectations (for example, include_externally_authenticated_upn_without_hash helps with clients that cannot handle hash marks (#) in the UPN)

Таблица 4. Значения для настройки необязательных утвержденийTable 4: Values for configuring optional claims

Имя свойстваProperty name Имя дополнительного свойстваAdditional Property name ОписаниеDescription
upn Может использоваться для ответов SAML и JWT и для токенов v1.0 и v2.0.Can be used for both SAML and JWT responses, and for v1.0 and v2.0 tokens.
include_externally_authenticated_upn Включает гостевое имя участника-пользователя, сохраненное в клиенте ресурса.Includes the guest UPN as stored in the resource tenant. Например foo_hometenant.com#EXT#@resourcetenant.com.For example, foo_hometenant.com#EXT#@resourcetenant.com
include_externally_authenticated_upn_without_hash Аналогично предыдущему примеру, за исключением того, что метки хэширования (#) будут заменены символами нижнего подчеркивания (_), например foo_hometenant.com_EXT_@resourcetenant.comSame as above, except that the hash marks (#) are replaced with underscores (_), for example foo_hometenant.com_EXT_@resourcetenant.com

Пример дополнительных свойств:Additional properties example

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ]
}

Этот объект OptionalClaims вызывает маркер идентификатора, возвращаемый клиенту, для включения утверждения upn с дополнительными сведениями о домашнем клиенте и клиенте ресурса.This OptionalClaims object causes the ID token returned to the client to include a upn claim with the additional home tenant and resource tenant information. Он может изменить утверждение upn в маркере, только если пользователь является гостем в клиенте (который использует другой поставщик удостоверений для проверки подлинности).The upn claim is only changed in the token if the user is a guest in the tenant (that uses a different IDP for authentication).

Настройка необязательных утвержденийConfiguring optional claims

Важно!

Маркеры доступа всегда создаются с помощью манифеста ресурса, а не клиента.Access tokens are always generated using the manifest of the resource, not the client. Поэтому в запросе ...scope=https://graph.microsoft.com/user.read... ресурсом является API Microsoft Graph.So in the request ...scope=https://graph.microsoft.com/user.read... the resource is the Microsoft Graph API. Таким же маркер доступа создается с помощью манифеста API Microsoft Graph, а не манифеста клиента.Thus, the access token is created using the Microsoft Graph API manifest, not the client's manifest. Изменение манифеста для приложения никогда не приведет к тому, что маркеры для API Microsoft Graph будут выглядеть иначе.Changing the manifest for your application will never cause tokens for the Microsoft Graph API to look different. Чтобы проверить, применяются ли изменения в accessToken, запросите маркер для своего приложения, а не для другого приложения.In order to validate that your accessToken changes are in effect, request a token for your application, not another app.

Настроить необязательные утверждения для приложения можно с помощью пользовательского интерфейса или манифеста приложения.You can configure optional claims for your application through the UI or application manifest.

  1. Перейдите на портал Azure.Go to the Azure portal. Найдите и выберите Azure Active Directory.Search for and select Azure Active Directory.
  2. В разделе Управление выберите Регистрация приложений.From the Manage section, select App registrations.
  3. Выберите в списке приложение, для которого нужно настроить необязательные утверждения.Select the application you want to configure optional claims for in the list.

Настройка необязательных утверждений с помощью пользовательского интерфейсаConfiguring optional claims through the UI:

Настройка необязательных утверждений с помощью пользовательского интерфейсаShows how to configure optional claims using the UI

  1. В разделе Управление выберите Конфигурация токена.From the Manage section, select Token configuration.
  2. Выберите Добавить необязательное утверждение.Select Add optional claim.
  3. Выберите тип токена, который нужно настроить.Select the token type you want to configure.
  4. Выберите необязательные утверждения для добавления.Select the optional claims to add.
  5. Выберите Добавить.Select Add.

Настройка необязательных утверждений с помощью манифеста приложенияConfiguring optional claims through the application manifest:

Настройка необязательных утверждений с помощью манифеста приложенияShows how to configure optional claims using the app manifest

  1. В разделе Управление выберите Манифест.From the Manage section, select Manifest. Откроется веб-редактор манифеста, в котором можно изменить манифест.A web-based manifest editor opens, allowing you to edit the manifest. При необходимости можно выбрать Скачать и изменить манифест локально, а затем повторно применить его для приложения с помощью команды Отправить.Optionally, you can select Download and edit the manifest locally, and then use Upload to reapply it to your application. Дополнительные сведения о манифесте приложения см. в статье Манифест приложения Azure Active Directory.For more information on the application manifest, see the Understanding the Azure AD application manifest article.

    Следующая запись в манифесте приложения добавляет дополнительные утверждения auth_time, ipaddr и upn в маркеры идентификации, доступа и SAML.The following application manifest entry adds the auth_time, ipaddr, and upn optional claims to ID, access, and SAML tokens.

    "optionalClaims": {
        "idToken": [
            {
                "name": "auth_time",
                "essential": false
            }
        ],
        "accessToken": [
            {
                "name": "ipaddr",
                "essential": false
            }
        ],
        "saml2Token": [
            {
                "name": "upn",
                "essential": false
            },
            {
                "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
                "source": "user",
                "essential": false
            }
        ]
    }
    
  2. По завершении нажмите Сохранить.When finished, select Save. Теперь указанные необязательные утверждения будут включаться в маркеры для вашего приложения.Now the specified optional claims will be included in the tokens for your application.

Тип OptionalClaimsOptionalClaims type

Объявляет необязательные утверждения, запрошенные приложением.Declares the optional claims requested by an application. В приложении можно настроить необязательные утверждения, которые должны возвращаться в каждый из трех типов токенов (токен идентификации, маркер доступа, токен SAML 2), которые оно может получить из службы токенов безопасности.An application can configure optional claims to be returned in each of three types of tokens (ID token, access token, SAML 2 token) it can receive from the security token service. Приложение может настроить различные наборы необязательных утверждений, которые будут возвращаться в каждый тип токена.The application can configure a different set of optional claims to be returned in each token type. Свойство optionalClaims сущности приложения — это объект optionalClaims.The OptionalClaims property of the Application entity is an OptionalClaims object.

Таблица 5. Свойства типа OptionalClaimsTable 5: OptionalClaims type properties

ИмяName ТипType ОписаниеDescription
idToken Коллекция (OptionalClaim)Collection (OptionalClaim) Необязательные утверждения, возвращаемые в токен идентификации JWT.The optional claims returned in the JWT ID token.
accessToken Коллекция (OptionalClaim)Collection (OptionalClaim) Необязательные утверждения, возвращаемые в маркер доступа JWT.The optional claims returned in the JWT access token.
saml2Token Коллекция (OptionalClaim)Collection (OptionalClaim) Необязательные утверждения, возвращаемые в токен SAML.The optional claims returned in the SAML token.

Тип OptionalClaimOptionalClaim type

Содержит необязательное утверждение, связанное с приложением или субъект-службой.Contains an optional claim associated with an application or a service principal. Свойства idToken, accessToken и saml2Token типа OptionalClaims являются коллекцией OptionalClaim.The idToken, accessToken, and saml2Token properties of the OptionalClaims type is a collection of OptionalClaim. С помощью поля AdditionalProperties можно изменить поведение OptionalClaim, если это поддерживается определенным утверждением.If supported by a specific claim, you can also modify the behavior of the OptionalClaim using the AdditionalProperties field.

Таблица 6. Свойства типа OptionalClaimsTable 6: OptionalClaim type properties

ИмяName ТипType ОписаниеDescription
name Edm.StringEdm.String Имя необязательного утверждения.The name of the optional claim.
source Edm.StringEdm.String Источник утверждения (объект каталога).The source (directory object) of the claim. Существуют стандартные утверждения и определяемые пользователем утверждения из свойств расширения.There are predefined claims and user-defined claims from extension properties. Если исходное значение равно null, утверждение будет являться предопределенным необязательным утверждением.If the source value is null, the claim is a predefined optional claim. Если исходное значение — user, значение в имени свойства будет свойством расширения из объекта пользователя.If the source value is user, the value in the name property is the extension property from the user object.
essential Edm.BooleanEdm.Boolean Если значение равно true, утверждение, указанное клиентом, необходимо для обеспечения плавной авторизации конкретной задачи, запрашиваемой пользователем.If the value is true, the claim specified by the client is necessary to ensure a smooth authorization experience for the specific task requested by the end user. Значение по умолчанию — false.The default value is false.
additionalProperties Коллекция (Edm.String)Collection (Edm.String) Дополнительные свойства утверждений.Additional properties of the claim. Если свойство существует в коллекции, оно изменяет поведение дополнительного утверждения, указанного в свойстве имени.If a property exists in this collection, it modifies the behavior of the optional claim specified in the name property.

Настройка необязательных утверждений для расширения каталогаConfiguring directory extension optional claims

Помимо стандартного набора необязательных утверждений, маркеры также можно настроить для включения расширений.In addition to the standard optional claims set, you can also configure tokens to include extensions. Дополнительные сведения см. в документации по Microsoft Graph extensionProperty.For more info, see the Microsoft Graph extensionProperty documentation.

Схемы и открытые расширения не поддерживаются необязательными утверждениями, а только расширениями каталогов в стиле AAD-Graph.Schema and open extensions are not supported by optional claims, only the AAD-Graph style directory extensions. Эта возможность полезна при присоединении дополнительных сведений о пользователях, которые может использовать приложение, например, дополнительный идентификатор или важный параметр конфигурации, заданный пользователем.This feature is useful for attaching additional user information that your app can use – for example, an additional identifier or important configuration option that the user has set. Пример см. внизу этой страницы.See the bottom of this page for an example.

Примечание

Расширения схемы каталога — это возможность, предназначенная только для Azure AD,Directory schema extensions are an Azure AD-only feature. поэтому если ваш манифест приложения запрашивает пользовательское расширение, а пользователь MSA регистрируется в вашем приложении, эти расширения не будут возвращены.If your application manifest requests a custom extension and an MSA user logs in to your app, these extensions will not be returned.

Форматирование расширения каталогаDirectory extension formatting

При настройке дополнительных утверждений для расширения каталога с помощью манифеста приложения используйте полное имя расширения (в формате: extension_<appid>_<attributename>).When configuring directory extension optional claims using the application manifest, use the full name of the extension (in the format: extension_<appid>_<attributename>). <appid> должен совпадать с идентификатором приложения, запрашивающего утверждение.The <appid> must match the ID of the application requesting the claim.

В рамках JWT эти утверждения будут передаваться с помощью следующего формата имени: extn.<attributename>.Within the JWT, these claims will be emitted with the following name format: extn.<attributename>.

В рамках токенов SAML эти утверждения будут передаваться с помощью следующего формата URI: http://schemas.microsoft.com/identity/claims/extn.<attributename>Within the SAML tokens, these claims will be emitted with the following URI format: http://schemas.microsoft.com/identity/claims/extn.<attributename>

Настройка необязательных утверждений группConfiguring groups optional claims

Примечание

Возможность создавать имена групп для пользователей и групп, синхронизированных из локальной среды, — это общедоступная предварительная версия.The ability to emit group names for users and groups synced from on-premises is Public Preview.

Далее описываются параметры конфигурации в разделе необязательных утверждений для изменения атрибутов группы, используемых в утверждениях группы, из группы по умолчанию для атрибутов, синхронизированных из локальной Active Directory Windows.This section covers the configuration options under optional claims for changing the group attributes used in group claims from the default group objectID to attributes synced from on-premises Windows Active Directory. Настроить необязательные утверждения групп для приложения можно с помощью пользовательского интерфейса или манифеста приложения.You can configure groups optional claims for your application through the UI or application manifest.

Важно!

Дополнительные сведения, включая важные предостережения, касающиеся общедоступной предварительной версии утверждений групп из локальных атрибутов, см. в разделе Настройка утверждений групп для приложений с помощью Azure AD.For more details including important caveats for the public preview of group claims from on-premises attributes, see Configure group claims for applications with Azure AD.

Настройка необязательных утверждений групп с помощью пользовательского интерфейсаConfiguring groups optional claims through the UI:

  1. Войдите на портал AzureSign in to the Azure portal
  2. Пройдя аутентификацию, выберите клиент Azure AD, щелкнув его в правом верхнем углу страницы.After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page
  3. В меню слева выберите Azure Active Directory.Select Azure Active Directory from the left-hand menu
  4. В разделе Управление выберите Регистрация приложений.Under the Manage section, select App registrations
  5. Выберите в списке приложение, для которого нужно настроить необязательные утверждения.Select the application you want to configure optional claims for in the list
  6. В разделе Управление выберите Конфигурация токена.Under the Manage section, select Token configuration
  7. Выберите Добавить утверждение группы.Select Add groups claim
  8. Выберите типы для возвращения (Все группы, SecurityGroup или DirectoryRole).Select the group types to return (All Groups, SecurityGroup, or DirectoryRole). Параметр Все группы включает SecurityGroup, DirectoryRole и DistributionList.The All Groups option includes SecurityGroup, DirectoryRole, and DistributionList
  9. Необязательно. Выберите свойства определенного типа маркера, чтобы изменить значение утверждения групп, чтобы оно содержало атрибуты локальной группы или чтобы изменить тип утверждения на роль.Optional: select the specific token type properties to modify the groups claim value to contain on premises group attributes or to change the claim type to a role
  10. Нажмите кнопку Сохранить.Select Save

Настройка необязательных утверждений групп с помощью манифеста приложения.Configuring groups optional claims through the application manifest:

  1. Войдите на портал AzureSign in to the Azure portal

  2. Пройдя аутентификацию, выберите клиент Azure AD, щелкнув его в правом верхнем углу страницы.After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page

  3. В меню слева выберите Azure Active Directory.Select Azure Active Directory from the left-hand menu

  4. Выберите в списке приложение, для которого нужно настроить необязательные утверждения.Select the application you want to configure optional claims for in the list

  5. В разделе Управление выберите Манифест.Under the Manage section, select Manifest

  6. Добавьте следующую запись с помощью редактора манифеста:Add the following entry using the manifest editor:

    Допустимые значения:The valid values are:

    • "Все" (этот параметр включает SecurityGroup, DirectoryRole и DistributionList)"All" (this option includes SecurityGroup, DirectoryRole, and DistributionList)
    • "SecurityGroup""SecurityGroup"
    • "DirectoryRole""DirectoryRole"

    Пример:For example:

    "groupMembershipClaims": "SecurityGroup"
    

    По умолчанию группы ObjectID будут выдаваться в значении утверждения группы.By default Group ObjectIDs will be emitted in the group claim value. Чтобы изменить значение утверждения в соответствии с атрибутами локальной группы или изменить тип утверждения на роль, используйте конфигурацию OptionalClaims следующим образом.To modify the claim value to contain on premises group attributes, or to change the claim type to role, use OptionalClaims configuration as follows:

  7. Задайте необязательные утверждения для конфигурации имени группы.Set group name configuration optional claims.

    Если вы хотите, чтобы группы в токене содержали атрибуты локальной группы AD, в разделе необязательных утверждений укажите, к какому типу маркера следует применить обязательное утверждение, имя запрошенного необязательного утверждения и дополнительные свойства.If you want to groups in the token to contain the on premises AD group attributes in the optional claims section specify which token type optional claim should be applied to, the name of optional claim requested and any additional properties desired. В списке можно указать несколько типов маркеров:Multiple token types can be listed:

    • idToken для маркера идентификатора OIDC;idToken for the OIDC ID token
    • accessToken для маркера доступа OAuth;accessToken for the OAuth access token
    • Saml2Token для маркеров SAML.Saml2Token for SAML tokens.

    Примечание

    Тип Saml2Token применяется к маркерам формата SAML1.1 и SAML2.0.The Saml2Token type applies to both SAML1.1 and SAML2.0 format tokens

    Для каждого соответствующего типа токена измените утверждение групп, чтобы в манифесте использовался раздел OptionalClaims.For each relevant token type, modify the groups claim to use the OptionalClaims section in the manifest. Схема OptionalClaims выглядит следующим образом:The OptionalClaims schema is as follows:

    {
        "name": "groups",
        "source": null,
        "essential": false,
        "additionalProperties": []
    }
    
    Схема необязательного утвержденияOptional claims schema ЗначениеValue
    name:name: Должно быть "groups"Must be "groups"
    source:source: Не используется.Not used. Пропустите или укажите "null"Omit or specify null
    essential:essential: Не используется.Not used. Пропустите или укажите "false"Omit or specify false
    additionalProperties:additionalProperties: Список дополнительных свойств.List of additional properties. Допустимые значения: "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name", "emit_as_roles".Valid options are "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name", "emit_as_roles"

    В additionalProperties требуется только один из них: "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name".In additionalProperties only one of "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name" are required. Если указано более одного, используется первый, а остальные игнорируются.If more than one is present, the first is used and any others ignored.

    Некоторым приложениям требуются сведения о группе пользователя в утверждении роли.Some applications require group information about the user in the role claim. Чтобы изменить тип утверждения с утверждения группы на утверждение роли, добавьте "emit_as_roles" к дополнительным свойствам.To change the claim type to from a group claim to a role claim, add "emit_as_roles" to additional properties. Значения группы будут выдаваться в утверждении роли.The group values will be emitted in the role claim.

    Примечание

    Если используется "emit_as_roles", все роли приложения, настроенные для назначения пользователя, не будут отображаться в утверждении роли.If "emit_as_roles" is used any Application Roles configured that the user is assigned will not appear in the role claim

Примеры:Examples:

  1. Выдача групп в качестве имен групп в маркерах доступа OAuth в формате dnsDomainName\sAMAccountName.Emit groups as group names in OAuth access tokens in dnsDomainName\sAMAccountName format

    Настройка с помощью пользовательского интерфейса.UI configuration:

    Настройка необязательных утверждений с помощью пользовательского интерфейсаShows how to configure optional claims using the UI

    Запись в манифесте приложения.Application manifest entry:

    "optionalClaims": {
        "accessToken": [
            {
                "name": "groups",
                "additionalProperties": [
                    "dns_domain_and_sam_account_name"
                ]
            }
        ]
    }
    
  2. Выдача имен групп в формате netbiosDomain\sAMAccountName в качестве утверждения роли в маркерах SAML и маркерах идентификатора OIDC.Emit group names to be returned in netbiosDomain\sAMAccountName format as the roles claim in SAML and OIDC ID Tokens

    Настройка с помощью пользовательского интерфейса.UI configuration:

    Настройка необязательных утверждений с помощью пользовательского интерфейсаShows how to configure optional claims using the UI

    Запись в манифесте приложения.Application manifest entry:

    "optionalClaims": {
        "saml2Token": [
            {
                "name": "groups",
                "additionalProperties": [
                    "netbios_name_and_sam_account_name",
                    "emit_as_roles"
                ]
            }
        ],
        "idToken": [
            {
                "name": "groups",
                "additionalProperties": [
                    "netbios_name_and_sam_account_name",
                    "emit_as_roles"
                ]
            }
        ]
    }
    

Пример необязательного утвержденияOptional claims example

В этом разделе можно пошагово выполнить сценарий, чтобы узнать, как можно использовать возможность необязательных утверждений для приложения.In this section, you can walk through a scenario to see how you can use the optional claims feature for your application. Есть несколько доступных вариантов обновления свойств в конфигурации удостоверения приложения, позволяющих включить и настроить необязательные утверждения.There are multiple options available for updating the properties on an application's identity configuration to enable and configure optional claims:

  • Можно использовать пользовательский интерфейс (см. пример ниже).You can use the Token configuration UI (see example below)
  • Можно использовать манифест (см. пример ниже).You can use the Manifest (see example below). Ознакомьтесь со статьей Манифест приложения Azure Active Directory, чтобы получить общие сведения о манифесте.Read the Understanding the Azure AD application manifest document first for an introduction to the manifest.
  • Вы также можете написать приложение, в котором для обновления используется API Microsoft Graph.It's also possible to write an application that uses the Microsoft Graph API to update your application. При настройке необязательных утверждений могут помочь сведения о типе OptionalClaims в справочнике по API Graph.The OptionalClaims type in the Microsoft Graph API reference guide can help you with configuring the optional claims.

Пример.Example:

В приведенном ниже примере вы будете использовать пользовательский интерфейс и манифест для добавления необязательных утверждений в маркеры доступа, идентификации и SAML, предназначенные для вашего приложения.In the example below, you will use the Token configuration UI and Manifest to add optional claims to the access, ID, and SAML tokens intended for your application. Различные необязательные утверждения будут добавлены к каждому типу токена, который может получить приложение.Different optional claims will be added to each type of token that the application can receive:

  • Теперь токены идентификации содержат имена участников-пользователей федеративных пользователей в полной форме (<upn>_<homedomain>#EXT#@<resourcedomain>).The ID tokens will now contain the UPN for federated users in the full form (<upn>_<homedomain>#EXT#@<resourcedomain>).
  • Маркеры доступа, запрашиваемые для этого приложения другими клиентами, будут включены в утверждение auth_time.The access tokens that other clients request for this application will now include the auth_time claim
  • Токен SAML будет содержать расширение схемы каталога skypeId (в этом примере идентификатор этого приложения — ab603c56068041afb2f6832e2a17e237).The SAML tokens will now contain the skypeId directory schema extension (in this example, the app ID for this app is ab603c56068041afb2f6832e2a17e237). Токен SAML представит идентификатор Skype как extension_skypeId.The SAML tokens will expose the Skype ID as extension_skypeId.

Настройка с помощью пользовательского интерфейса.UI configuration:

  1. Войдите на портал AzureSign in to the Azure portal

  2. Пройдя аутентификацию, выберите клиент Azure AD, щелкнув его в правом верхнем углу страницы.After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page.

  3. В меню слева выберите Azure Active Directory.Select Azure Active Directory from the left-hand menu.

  4. В разделе Управление выберите Регистрация приложений.Under the Manage section, select App registrations.

  5. Найдите в списке приложение, для которого нужно настроить необязательные утверждения, и выберите его.Find the application you want to configure optional claims for in the list and select it.

  6. В разделе Управление выберите Конфигурация токена.Under the Manage section, select Token configuration.

  7. Выберите Добавить необязательное утверждение, тип маркера ИД, в списке утверждений выберите upn, а затем нажмите Добавить.Select Add optional claim, select the ID token type, select upn from the list of claims, and then select Add.

  8. Выберите Добавить необязательное утверждение, тип маркера Доступ, в списке утверждений выберите auth_time, а затем нажмите Добавить.Select Add optional claim, select the Access token type, select auth_time from the list of claims, then select Add.

  9. На странице общих сведений о конфигурации маркера щелкните значок карандаша рядом с утверждением upn, установите переключатель Внешняя проверка подлинности и нажмите Сохранить.From the Token Configuration overview screen, select the pencil icon next to upn, select the Externally authenticated toggle, and then select Save.

  10. Выберите Добавить необязательное утверждение, выберите тип маркера SAML, в списке утверждений выберите extn.skypeID (применимо только в том случае, если вы создали объект пользователя Azure AD с именем skypeID), а затем нажмите Добавить.Select Add optional claim, select the SAML token type, select extn.skypeID from the list of claims (only applicable if you've created an Azure AD user object called skypeID), and then select Add.

    Настройка необязательных утверждений с помощью пользовательского интерфейсаShows how to configure optional claims using the UI

Настройка с помощью манифеста.Manifest configuration:

  1. Войдите на портал Azure.Sign in to the Azure portal.

  2. Пройдя аутентификацию, выберите клиент Azure AD, щелкнув его в правом верхнем углу страницы.After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page.

  3. В меню слева выберите Azure Active Directory.Select Azure Active Directory from the left-hand menu.

  4. Найдите в списке приложение, для которого нужно настроить необязательные утверждения, и выберите его.Find the application you want to configure optional claims for in the list and select it.

  5. В разделе Управление выберите Манифест, чтобы открыть встроенный редактор манифеста.Under the Manage section, select Manifest to open the inline manifest editor.

  6. Можно напрямую изменить манифест с помощью этого редактора.You can directly edit the manifest using this editor. Манифест соответствует схеме для сущности приложения и автоматически форматирует манифест после сохранения.The manifest follows the schema for the Application entity, and automatically formats the manifest once saved. В свойство OptionalClaims будут добавлены новые элементы.New elements will be added to the OptionalClaims property.

    "optionalClaims": {
        "idToken": [
            {
                "name": "upn",
                "essential": false,
                "additionalProperties": [
                    "include_externally_authenticated_upn"
                ]
            }
        ],
        "accessToken": [
            {
                "name": "auth_time",
                "essential": false
            }
        ],
        "saml2Token": [
            {
                "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
                "source": "user",
                "essential": true
            }
        ]
    }
    
  7. Завершив изменение манифеста, нажмите Сохранить, чтобы сохранить его.When you're finished updating the manifest, select Save to save the manifest.

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

Дополнительные сведения о стандартных утверждениях, предоставляемых Azure AD, см. в следующих статьях.Learn more about the standard claims provided by Azure AD.