Настройка и управление необязательными утверждениями в токенах идентификатора, токенах доступа и токенах 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>

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

В этом разделе рассматриваются параметры конфигурации в разделе необязательных утверждений, которые позволяют изменить атрибуты группы, используемые в утверждениях о группах, с идентификатора объекта группы по умолчанию (objectID) на атрибуты, синхронизированные из локальной Windows Active Directory. Вы можете настроить необязательные утверждения для групп в своем приложении через портал 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 в виде утверждения roles в ID-токенах 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 поможет вам настроить необязательные утверждения.

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

• Токены идентификации содержат UPN для федеративных пользователей в полном формате (<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. После завершения обновления манифеста нажмите кнопку "Сохранить ", чтобы сохранить манифест.

Утверждение AMR

Утверждение amr (ссылки на методы аутентификации) определяет, как пользователь прошел аутентификацию. Утверждение amr отправляется по умолчанию для приложений Salesforce, поэтому для этих приложений не требуется никаких изменений конфигурации. Для всех остальных приложений SAML администратор приложения должен добавить в регистрацию приложения необязательное утверждение amr с дополнительным свойством include_granular_amr для запроса утверждений AMR. Значения multipleauthn и mfa передаются только после того, как пользователь прошёл MFA.

Настройка подробных значений AMR для приложения SAML

В настоящее время Центр администрирования Microsoft Entra не предоставляет вариант include_granular_amrпользовательского интерфейса. Настройте это свойство в манифесте приложения или с помощью Microsoft Graph. Свойство include_granular_amr изменяет amr утверждение для получения подробных значений метода проверки подлинности в токенах SAML.

Чтобы настроить манифест приложения, выполните следующее.

1. В Центр администрирования Microsoft Entra перейдите к Entra ID>Регистрация приложений.

2. Выберите регистрацию приложения.

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

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

   "optionalClaims": {
       "saml2Token": [
           {
               "name": "amr",
               "essential": false,
               "additionalProperties": [
                   "include_granular_amr"
               ]
           }
       ]
   }
   

5. Нажмите кнопку "Сохранить".

Кроме того, используйте API приложения обновления Microsoft Graph. Замените {applicationObjectId} идентификатором объекта регистрации приложения. Включите любую существующую конфигурацию необязательных утверждений, которую вы хотите сохранить в тексте запроса.

PATCH https://graph.microsoft.com/v1.0/applications/{applicationObjectId}
Content-Type: application/json

{
    "optionalClaims": {
        "saml2Token": [
            {
                "name": "amr",
                "essential": false,
                "additionalProperties": [
                    "include_granular_amr"
                ]
            }
        ]
    }
}

Дополнительные сведения о утверждении SAML см. в разделе authnmethodreferences.

Настройка утверждения AMR для приложения OIDC

Для приложения OpenID Connect версии 2.0 добавьте необязательное amr утверждение в типы маркеров, необходимые приложению. Свойство include_granular_amr применяется только к приложениям SAML и не требуется для приложений OIDC. Следующий манифест приложения запрашивает amr утверждение как в маркерах идентификатора, так и для доступа:

"optionalClaims": {
    "idToken": [
        {
            "name": "amr",
            "essential": false
        }
    ],
    "accessToken": [
        {
            "name": "amr",
            "essential": false
        }
    ]
}

Ограничение

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

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

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