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

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

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

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

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

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

1. Войдите в Центр администрирования Microsoft Entra как минимум администратор облачных приложений.
2. Перейдите к приложениям> удостоверений>Регистрация приложений.
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)
   • "SecurityGroup"
   • "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, netbios_domain_and_sam_account_namedns_domain_and_sam_account_nameemit_as_roles и .cloud_displayname

   В additionalProperties одном из sam_account_nameних netbios_domain_and_sam_account_name требуются только один из нихdns_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 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. Завершив изменение манифеста, нажмите Сохранить, чтобы сохранить его.

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

• Маркеры доступа в Azure Active Directory
• Манифест приложения
• Маркеры идентификации
• Необязательный справочник по утверждениям