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

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

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

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

• Поддержка использования атрибутов 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, могут содержать атрибут, отвечающий sAMAccountName домену, или GroupSID атрибут, синхронизированный из Active Directory, а не атрибут microsoft Entra ID objectID группы.

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

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

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

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

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

• При использовании членства в группах в целях авторизации в приложении предпочтительнее использовать атрибут 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 может выдавать имена групп или идентификатор локальной группы в утверждениях группы или роли, необходимо синхронизировать необходимые атрибуты из Active Directory. Необходимо запустить Microsoft Entra Connect версии 1.2.70 или более поздней. Более ранние версии Microsoft Entra Connect, чем 1.2.70, синхронизируют объекты группы из Active Directory, но они не будут включать обязательные атрибуты имени группы.

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

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

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

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

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

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

   

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

   

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

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

     

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

     

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

     

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

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

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

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

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

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

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

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

   

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

   

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

   

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

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

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

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

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

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

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

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

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

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

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

\

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

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

Изменение конфигурации утверждения групп

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

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

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

1. На портале выберите "Приложения> удостоверений>Регистрация приложений> Select Application>Manifest.

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

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

   Выбор	Description
   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", "cloud_displayname""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". Если указано более одного свойства, используется первое, а остальные игнорируются.

   Некоторым приложениям требуются сведения о группе пользователя в утверждении роли. Чтобы изменить тип утверждения из утверждения группы на утверждение роли, добавьте "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 (пример кода)
• Назначение корпоративному приложению пользователя или группы
• Настройка утверждений ролей