Настройка утверждений группы для приложений с помощью Microsoft Entra ID

Идентификатор Microsoft Entra может предоставить сведения о членстве пользователя в группах в токенах для использования в приложениях. Эта функция поддерживает три основных шаблона:

• Группы, определяемые атрибутом идентификатора объекта Microsoft Entra (OID)
• группы, определяемые атрибутом sAMAccountName или GroupSID для групп и пользователей, синхронизированных с Active Directory.
• Группы, определяемые атрибутом отображаемого имени для облачных групп

Внимание

Количество групп, создаваемых в маркере, ограничено 150 для утверждений SAML и 200 для JWT, включая вложенные группы. В крупных организациях число групп, в которых пользователь является членом, может превышать лимит, который система Microsoft Entra ID применяет перед добавлением записей о группах в токен. Превышение этого ограничения приведет к тому, что Microsoft Entra ID полностью исключит отправку утверждений группы в токене. Дополнительные сведения об этих ограничениях см. в разделе "Важные предостережения для этой функции".

Важные предостережения для этой функции

• Поддержка использования атрибутов sAMAccountName и идентификатора безопасности (SID), синхронизируемых из локальной среды, предназначена для переноса существующих приложений из служб федерации Active Directory (AD FS) и других поставщиков удостоверений. Группы, управляемые в идентификаторе Microsoft Entra, не содержат атрибуты, необходимые для выдачи этих утверждений.

• Чтобы избежать ограничения на количество групп, если у пользователей много членств в группах, можно ограничить группы, указанные в утверждениях, только теми, которые актуальны для приложения. Дополнительные сведения об отправке групп, назначенных приложению для маркеров JWT и токенов SAML. Если назначить группы приложениям невозможно, вы также можете настроить фильтр групп, чтобы уменьшить количество групп, выдаваемых в заявке. Фильтрация групп применяется к маркерам, созданным для приложений, где в разделе корпоративных приложений на портале были настроены утверждения группы и фильтрация. Помните, что в крупных организациях число групп, в которых пользователь является членом, может превышать ограничение, которое применяется идентификатором Microsoft Entra, прежде чем выдавать утверждения групп в токене. Превышение этого ограничения приведет к тому, что Microsoft Entra ID полностью исключит отправку утверждений о группах в токене.

• Претензии групп имеют ограничение в пять групп, если токен выдаётся через неявный поток. Токены, запрошенные через неявный поток, будут иметь утверждение "hasgroups":true только в том случае, если пользователь состоит более чем в пяти группах.

• Мы рекомендуем использовать авторизацию в приложении на основе ролей приложения, а не групп, в следующих случаях:

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

  Использование ролей приложения ограничивает объем информации, которая должна содержаться в токене, и поэтому такой способ более безопасен. Он также позволяет отделить назначение пользователя от конфигурации приложения.

Претензии группы для приложений, мигрирующих с AD FS и других поставщиков идентификации.

Многие приложения, настроенные для проверки подлинности с помощью AD FS, используют сведения о членстве в группах в форме атрибутов групп Windows Server Active Directory. Эти атрибуты представляют собой значение sAMAccountName группы, которое может быть дополнено доменным именем или идентификатором безопасности группы Windows (GroupSID). Если приложение объединено с AD FS, то AD FS использует функцию TokenGroups для получения сведений о членстве пользователя в группах.

Приложение, перемещенное из AD FS, должно иметь утверждения в том же формате. Утверждения групп и ролей, создаваемые Microsoft Entra ID, могут содержать атрибут sAMAccountName, соответствующий домену, или атрибут GroupSID, синхронизированный из Active Directory, вместо атрибута группы objectID Microsoft Entra ID.

Поддерживаемые форматы утверждений групп:

• Идентификатор объекта группы Microsoft Entra: доступен для всех групп.
• sAMAccountName: доступно для групп, синхронизированных из Active Directory.
• NetbiosDomain\sAMAccountName: доступно для групп, синхронизированных из Active Directory.
• DNSDomainName\sAMAccountName: доступно для групп, синхронизированных из Active Directory.
• Идентификатор безопасности локальной группы: доступен для групп, синхронизированных из Active Directory.

Примечание.

sAMAccountName и локальные атрибуты GroupSID доступны только для объектов групп, синхронизированных из Active Directory. Они недоступны для групп, созданных в идентификаторе Microsoft Entra или Office 365. Приложения, настроенные в идентификаторе Microsoft Entra для синхронизации атрибутов локальной группы, получают их только для синхронизированных групп.

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

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

Однако, если существующее приложение ожидает получения информации о группе через утверждения, можно настроить Microsoft Entra ID с различными форматами утверждений. Следуйте приведенным ниже рекомендациям.

• При использовании членства в группах в целях авторизации в приложении предпочтительнее использовать атрибут ObjectID группы. Атрибут группы ObjectID является неизменяемым и уникальным в идентификаторе Microsoft Entra. Он доступен для всех групп.

• Если для авторизации применяется атрибут sAMAccountName локальной группы, используйте доменные имена. Это снижает вероятность конфликта имен. sAMAccountName Может быть уникальным в домене Active Directory, но если несколько доменов Active Directory синхронизированы с клиентом Microsoft Entra, существует возможность иметь несколько групп с одинаковым именем.

• Рассмотрите возможность применять роли приложения для введения уровня абстракции между членством в группе и приложением. В этом случае приложение занимается внутренней авторизацией на основе утверждений ролей в токене.

• Если для приложения настроено получение атрибутов группы, которые синхронизируются из Active Directory, и группа не содержит этих атрибутов, такая группа не будет добавлена в утверждения.

• Права групп в токенах включают вложенные группы, за исключением случаев, когда выбрана опция ограничения прав групп только теми группами, которые назначены для данного приложения.

  Если пользователь является членом GroupB, а GroupB является членом GroupA, то утверждения групп для пользователя будут содержать как GroupA, так и GroupB. Если пользователи организации имеют большое количество членств в группах, число групп, перечисленных в маркере, может увеличить размер маркера. Идентификатор Microsoft Entra ограничивает число групп в токене до 150 для утверждений SAML и до 200 для JWT. Если пользователь является членом большего числа групп, такие группы пропускаются. Вместо этого включается ссылка на конечную точку Microsoft Graph для получения сведений о группах.

Необходимые условия для использования атрибутов групп, синхронизированных из Active Directory

При использовании формата ObjectId утверждения членства в группах можно выдавать в токенах для любой группы. Чтобы использовать утверждения группы в форматах, отличных от группы ObjectId, группы должны быть синхронизированы из Active Directory через Microsoft Entra Connect.

Чтобы настроить идентификатор Microsoft Entra для отправки имен групп для групп Active Directory, выполните следующие действия.

1. Синхронизация имен групп из Active Directory

   Прежде чем Microsoft Entra ID сможет передавать имена групп или SID локальной группы в утверждениях для группы или роли, необходимо синхронизировать необходимые атрибуты из Active Directory. Необходимо запустить Microsoft Entra Connect версии 1.2.70 или более поздней. Более ранние версии Microsoft Entra Connect, чем 1.2.70, синхронизируют объекты группы из Active Directory, но они не будут включать обязательные атрибуты имени группы.

2. Настройте регистрацию приложения в Microsoft Entra ID для включения утверждений групп в токены

   Утверждения групп можно настроить в разделе Корпоративные приложения портала или с помощью манифеста приложения в разделе Регистрация приложений. Сведения о настройке запросов группы в манифесте приложения см. в разделе "Настройка регистрации приложений Microsoft Entra для атрибутов групп", далее в этой статье.

Добавление в токены утверждений групп для приложений SAML с помощью настройки единого входа

Чтобы настроить групповые утверждения для галерейного или не-галерейного приложения SAML с помощью единого входа, выполните указанные ниже действия.

1. Откройте Корпоративные приложения, выберите приложение в списке, выберите конфигурацию единого входа, а затем выберите Параметры пользователя и утверждения.

2. Выберите Добавить утверждение о группе.

   

3. Используйте параметры для выбора групп, которые должны быть добавлены в токен.

   

   Выбор	Описание
   Все группы	Выдает группы безопасности, а также списки рассылки и роли
   Группы безопасности	Выдает группы безопасности, членом которых является пользователь, в заявлении о группах. Если пользователю назначены роли каталога, они выдаются в виде идентификатора объекта.
   Роли каталога	Если пользователю назначаются роли каталога, они выдаются как утверждение wids. Заявление группы не будет выпущено.
   Группы, назначенные приложению	Выдает только те группы, которые явным образом назначены приложению и членом которых является пользователь. Рекомендуется для крупных организаций из-за ограничения по количеству групп в токене.

   • Например, чтобы выдать все группы безопасности, членом которых является пользователь, выберите Группы безопасности.

     

     Для выпуска групп с использованием атрибутов Active Directory, синхронизированных из Active Directory, вместо атрибутов objectID Microsoft Entra ID, выберите необходимый формат из раскрывающегося списка атрибутов источника. В утверждениях будут включены только группы, синхронизированные из Active Directory.

     

   • Чтобы выдать только группы, назначенные приложению, выберите пункт Группы, назначенные приложению.

     

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

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

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

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

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

1. Откройте Корпоративные приложения, выберите приложение в списке, выберите конфигурацию Единого входа, а затем выберите Атрибуты пользователей и Утверждения.

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

3. Для типа группы, испускаемого в токене, выберите группы, назначенные приложению:

   

4. Чтобы вывести отображаемое имя группы только для облачных групп, в раскрывающемся списке "Исходный атрибут " выберите отображаемые имена только для облачных групп:

   

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

   

Примечание.

В приложение можно добавлять только имена назначенных облачных групп. Ограничение groups assigned to the application заключается в том, что имя группы не является уникальным, и отображаемые имена можно создавать только для групп, явно назначенных приложению, чтобы снизить риски безопасности. В противном случае любой пользователь может создать группу с повторяющимся именем и получить доступ на стороне приложения.

Определение расширенных параметров

Настройка имени утверждения группы

Способ выдачи утверждений групп можно изменить с помощью параметров в разделе Дополнительные параметры.

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

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

Примечание.

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

Фильтрация групп

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

Примечание.

Фильтрация групп применяется к токенам, созданным для приложений, в панели Enterprise apps на портале, где настроены утверждения и фильтрация групп.
Фильтрация групп не применяется к ролям Microsoft Entra.

Вы можете настроить применение фильтров к отображаемому имени группы или атрибуту SAMAccountName. Поддерживаются следующие операции фильтрации:

• Префикс — соответствует началу выбранного атрибута.
• Суффикс — соответствует концу выбранного атрибута.
• Содержит — соответствует любому месту в выбранном атрибуте.

Преобразование групп

Для некоторых приложений могут потребоваться группы в другом формате от того, как они представлены в идентификаторе Microsoft Entra. Чтобы выполнить это требование, вы можете применить преобразование к каждой группе, которая будет включена в заявлении группы. Это достигается за счет настройки регулярного выражения и замещающего значения в утверждениях пользовательских групп.

\

• Шаблон регулярного выражения. Используйте регулярное выражение для анализа текстовых строк в соответствии с шаблоном, указанным в этом поле. Если указанный шаблон регулярного выражения дает результат true, будет выполнен шаблон замены регулярного выражения.
• Шаблон замены регулярных выражений. Укажите в нотации регулярных выражений, как нужно заменить строку, если шаблон регулярного выражения, описанный выше, дает результат true. Используйте группы записи для сопоставления частей выражений в этом замещающем регулярном выражении.

Дополнительные сведения о группах замены и захвата регулярных выражений см. в разделе Модель объекта регулярного выражения: Сохраненная группа.

Примечание.

Как описано в документации Microsoft Entra, вы не можете изменить ограниченное требование при помощи политики. Для таких утверждений также невозможно изменить источник данных, а при их создании не применяются преобразования. Групповой запрос по-прежнему является ограниченным, поэтому вам необходимо настроить группы, меняя имя. Если вы выберете недопустимое имя для пользовательской групповой атрибуции, это утверждение будет проигнорировано во время выполнения.

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

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

Редактировать конфигурацию утверждений группы

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

Настройка регистрации приложения Microsoft Entra для атрибутов группы

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

1. На портале выберите Удостоверение>Приложения>Регистрация приложений>Выберите приложение>Манифест.

2. Включите утверждения о членстве в группах, изменив атрибут groupMembershipClaims.

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

   Выбор	Описание
   All	Выдает группы безопасности, списки рассылки и роли.
   SecurityGroup	Выводит группы безопасности и роли Microsoft Entra, членом которых является пользователь, в утверждении группы.
   DirectoryRole	Если пользователю назначаются роли каталога, они выдаются как утверждение wids. (Групповой запрос выдан не будет.)
   ApplicationGroup	Выдает только те группы, которые явным образом назначены приложению и членом которых является пользователь.
   None	Группы не возвращаются. (Без учета регистра, поэтому none также работает. Его можно задать непосредственно в манифесте приложения.)

   Например:

   "groupMembershipClaims": "SecurityGroup"
   

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

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

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

   • idToken для токена идентификатора OIDC;
   • accessToken для токена доступа OAuth/OIDC.
   • 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_name", "netbios_domain_and_sam_account_name""cloud_displayname"и "emit_as_roles".

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

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

   Чтобы вывести отображаемое имя группы для облачных групп, можно добавить "cloud_displayname" в additional properties. Этот параметр будет работать только в том случае, если “groupMembershipClaims” задано значение ApplicationGroup

   Примечание.

   Если используется "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"]
    }]
}

Следующие шаги

• Добавление авторизации с помощью утверждений групп и групп в веб-приложение ASP.NET Core (пример кода)
• Назначьте пользователя или группу для корпоративного приложения
• Настройка утверждений ролей