Настройка и управление необязательными утверждениями в токенах идентификатора, токенах доступа и токенах SAML

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

Вы можете настроить необязательные утверждения для приложения с помощью пользовательского интерфейса или манифеста Центра администрирования Microsoft Entra.

Необходимые компоненты

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно.
• Завершение краткого руководства: Регистрация приложения

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

1. Войдите в Центр администрирования Microsoft Entra как минимум администратор облачных приложений.
2. Перейдите к Entra ID>регистрация приложений.
3. Выберите приложение, для которого необходимо настроить необязательные утверждения на основе вашего сценария и желаемого результата.

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

При поддержке определенного утверждения можно также изменить поведение необязательного утверждения с помощью additionalProperties поля.

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

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

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

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

При настройке дополнительных утверждений для расширения каталога с помощью манифеста приложения используйте полное имя расширения (в формате: extension_<appid>_<attributename>). Это <appid> отрезаная версия идентификатора приложения (или идентификатор клиента) приложения, запрашивающего утверждение.

В JWT эти утверждения создаются в следующем формате имени: extn.<attributename> В токенах SAML эти утверждения создаются со следующим форматом URI: http://schemas.microsoft.com/identity/claims/extn.<attributename>

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

Далее описываются параметры конфигурации в разделе необязательных утверждений для изменения атрибутов группы, используемых в утверждениях группы, из группы по умолчанию для атрибутов, синхронизированных из локальной Active Directory Windows. Вы можете настроить группы необязательных утверждений для приложения с помощью манифеста портал Azure или приложения. Необязательные утверждения группы создаются только в JWT для субъектов-пользователей. Субъекты-службы не включаются в необязательные утверждения группы, создаваемые в JWT.

Выполните следующие действия, чтобы настроить необязательные утверждения групп с помощью портал Azure:

1. Выберите приложение, для которого необходимо настроить необязательные утверждения.
2. В разделе "Управление" выберите конфигурацию токена.
3. Выберите Добавить претензии групп.
4. Выберите типы групп для возврата (группы безопасности или роли каталога, все группы и/или группы, назначенные приложению):
   • Группы, назначенные параметру приложения, включают только группы, назначенные приложению. Группы, назначенные приложению, рекомендуются для крупных организаций из-за ограничения на количество групп в токене. Чтобы изменить группы, назначенные приложению, выберите приложение из списка корпоративных приложений . Выберите "Пользователи" и "Группы" , а затем добавьте пользователя или группу. Выберите группы, которые нужно добавить в приложение из пользователей и групп.
   • Параметр "Все группы" включает в себя SecurityGroup, DirectoryRole и DistributionList, но не группы, назначенные приложению.
5. Необязательно: выберите свойства определенного типа маркера, чтобы изменить значение утверждения групп, чтобы оно содержало атрибуты локальной группы, или чтобы изменить тип утверждения на утверждение роли.
6. Нажмите кнопку "Сохранить".

Выполните следующие действия, чтобы настроить необязательные утверждения групп с помощью манифеста приложения:

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

2. В разделе "Управление" выберите "Манифест".

3. Добавьте следующую запись с помощью редактора манифеста:

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

   • "Все" (этот параметр включает SecurityGroup, DirectoryRole и DistributionList)
   • Группа безопасности
   • DirectoryRole
   • "ApplicationGroup" (этот параметр включает только группы, которые назначены приложению)

   Например:

   "groupMembershipClaims": "SecurityGroup"
   

   По умолчанию идентификаторы объектов группы создаются в значении утверждения группы. Чтобы изменить значение утверждения, содержащее атрибуты локальной группы, или изменить тип утверждения на роль, используйте optionalClaims конфигурацию следующим образом:

4. Задайте необязательные утверждения для конфигурации имени группы.

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

   В списке можно указать несколько типов маркеров:

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

   Тип Saml2Token применяется как к токенам формата SAML1.1, так и SAML2.0.

   Для каждого соответствующего типа маркера измените утверждение групп, чтобы использовать optionalClaims раздел в манифесте. Схема optionalClaims выглядит следующим образом:

   {
       "name": "groups",
       "source": null,
       "essential": false,
       "additionalProperties": []
   }
   

   Схема необязательного утверждения	Значение
   name	Должен содержать значение groups.
   source	Не используется. Опустить или указать значение NULL.
   essential	Не используется. Опустить или указать значение false.
   additionalProperties	Список других свойств. Допустимые параметры: sam_account_name, dns_domain_and_sam_account_namenetbios_domain_and_sam_account_nameemit_as_roles и .cloud_displayname

   В additionalProperties одном из sam_account_nameних dns_domain_and_sam_account_name требуются только один из нихnetbios_domain_and_sam_account_name. Если указано более одного, используется первый, а остальные игнорируются. Вы также можете добавить cloud_displayname отображаемое имя облачной группы. Этот параметр работает только в том случае, если groupMembershipClaims задано значение ApplicationGroup.

   Некоторым приложениям требуются сведения о группе пользователя в утверждении роли. Чтобы изменить тип утверждения группы на утверждение роли, добавьте emit_as_roles в additionalProperties. Значения группы создаются в утверждении роли.

   Если emit_as_roles используется, все роли приложения, настроенные для назначения пользователем (или приложением ресурсов), не используются в утверждении роли.

В следующих примерах показана конфигурация манифеста для утверждений группы:

Вывод групп в виде имен групп в маркерах доступа OAuth в dnsDomainName\sAMAccountName формате.

"optionalClaims": {
    "accessToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "dns_domain_and_sam_account_name"
            ]
        }
    ]
}

Удаляйте имена групп, возвращаемые в формате, как утверждение ролей в netbiosDomain\sAMAccountName токенах идентификатора SAML и OIDC.

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

Выведите имена групп в формате sam_account_name локальных синхронизированных групп и имя для облачных групп в токенах идентификатора SAML и cloud_display OIDC для групп, назначенных приложению.

"groupMembershipClaims": "ApplicationGroup",
"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ]
}

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

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

• Вы можете использовать портал Azure
• Манифест можно использовать.
• Кроме того, можно написать приложение, использующее API Microsoft Graph для обновления приложения. Тип OptionalClaims в справочном руководстве по API Microsoft Graph поможет вам настроить необязательные утверждения.

В следующем примере портал Azure и манифест используются для добавления необязательных утверждений в маркеры доступа, идентификатора и SAML, предназначенных для приложения. К каждому типу маркера добавляются различные необязательные утверждения, которые приложение может получать:

• Маркеры идентификатора содержат имя участника-пользователя для федеративных пользователей в полной форме (<upn>_<homedomain>#EXT#@<resourcedomain>).
• Маркеры доступа, запрашиваемые другими клиентами auth_time для этого приложения, включают утверждение.
• Токены SAML содержат skypeId расширение схемы каталога (в этом примере — идентификатор приложения для этого приложения ab603c56068041afb2f6832e2a17e237). Маркер SAML предоставляет идентификатор Skype как extension_ab603c56068041afb2f6832e2a17e237_skypeId.

Настройте утверждения в портал Azure:

1. Выберите приложение, для которого необходимо настроить необязательные утверждения.
2. В разделе "Управление" выберите конфигурацию токена.
3. Выберите "Добавить необязательное утверждение", выберите тип маркера идентификатора , выберите upn из списка утверждений и нажмите кнопку "Добавить".
4. Выберите " Добавить необязательное утверждение", выберите тип маркера доступа , выберите auth_time из списка утверждений, а затем нажмите кнопку "Добавить".
5. На экране обзора конфигурации маркеров щелкните значок карандаша рядом с upn, выберите переключатель "Аутентифицирован внешними средствами", и нажмите кнопку "Сохранить".
6. Выберите " Добавить необязательное утверждение", выберите тип токена SAML , выберите extn.skypeID из списка утверждений (только если вы создали объект пользователя Microsoft Entra с именем skypeID), а затем нажмите кнопку "Добавить".

Настройте утверждения в манифесте:

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

2. В разделе "Управление" выберите "Манифест" , чтобы открыть встроенный редактор манифеста.

3. Можно напрямую изменить манифест с помощью этого редактора. Манифест следует схеме сущности приложения и автоматически форматирует манифест после сохранения. Новые элементы добавляются в optionalClaims свойство.

   "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
           }
       ]
   }
   

4. После завершения обновления манифеста нажмите кнопку "Сохранить ", чтобы сохранить манифест.

Ограничение

Приложение может выдавать не более 10 атрибутов расширения в качестве необязательных утверждений.

Связанный контент

• Маркеры доступа
• Манифест приложения
• Идентификационные токены
• Необязательная ссылка на заявления