Настройка групповых утверждений для приложений с Azure Active DirectoryConfigure group claims for applications with Azure Active Directory

Azure Active Directory могут предоставить сведения о членстве в группах пользователей в маркерах для использования в приложениях.Azure Active Directory can provide a users group membership information in tokens for use within applications. Поддерживаются два основных шаблона:Two main patterns are supported:

  • Группы, определяемые по атрибуту "идентификатор объекта Azure Active Directory (OID)"Groups identified by their Azure Active Directory object identifier (OID) attribute
  • Группы, определяемые атрибутами sAMAccountName или Граупсид для синхронизированных групп и пользователей Active Directory (AD)Groups identified by sAMAccountName or GroupSID attributes for Active Directory (AD) synchronized groups and users

Важно!

Существует ряд предостережений, которые следует учитывать при работе с этой функцией:There are a number of caveats to note for this functionality:

  • Поддержка использования атрибутов sAMAccountName и идентификатора безопасности (SID), синхронизированных из локальной среды, предназначена для перемещения существующих приложений из AD FS и других поставщиков удостоверений.Support for use of sAMAccountName and security identifier (SID) attributes synced from on-premises is designed to enable moving existing applications from AD FS and other identity providers. Группы, управляемые в Azure AD, не содержат атрибуты, необходимые для выпуска этих утверждений.Groups managed in Azure AD do not contain the attributes necessary to emit these claims.
  • В крупных организациях число групп, членом которых является пользователь, может превысить ограничение, Azure Active Directory будет добавляться в маркер.In larger organizations the number of groups a user is a member of may exceed the limit that Azure Active Directory will add to a token. 150. группы для токена SAML и 200 для JWT.150 groups for a SAML token, and 200 for a JWT. Это может привести к непредсказуемым результатам.This can lead to unpredictable results. Если пользователи имеют большое количество членств в группах, рекомендуется использовать параметр, чтобы ограничить группы, созданные в заявках, соответствующими группами для приложения.If your users have large numbers of group memberships, we recommend using the option to restrict the groups emitted in claims to the relevant groups for the application.
  • При разработке новых приложений или в случаях, когда приложение может быть настроено для этого, а также когда поддержка вложенных групп не требуется, рекомендуется, чтобы авторизация в приложении основывалась на ролях приложений, а не на группах.For new application development, or in cases where the application can be configured for it, and where nested group support isn't required, we recommend that in-app authorization is based on application roles rather than groups. Это ограничивает объем информации, которую необходимо переключиться на маркер, является более безопасным и отделяет назначение пользователей от конфигурации приложения.This limits the amount of information that needs to go into the token, is more secure, and separates user assignment from app configuration.

Групповые утверждения для приложений, выполняющих миграцию с AD FS и других поставщиков удостоверенийGroup claims for applications migrating from AD FS and other identity providers

Многие приложения, настроенные для проверки подлинности с AD FS, используют сведения о членстве в группах в форме атрибутов группы Windows AD.Many applications configured to authenticate with AD FS rely on group membership information in the form of Windows AD group attributes. Эти атрибуты представляют собой значение sAMAccountName группы, которое может быть дополнено именем домена или идентификатором безопасности группы Windows (Граупсид).These attributes are the group sAMAccountName, which may be qualified by-domain name, or the Windows Group Security Identifier (GroupSID). Если приложение объединено с AD FS, AD FS использует функцию Токенграупс для получения членства в группах для пользователя.When the application is federated with AD FS, AD FS uses the TokenGroups function to retrieve the group memberships for the user.

Приложение, перемещенное из AD FS, должно иметь утверждения в том же формате.An app that has been moved from AD FS needs claims in the same format. Утверждения групп и ролей могут выдаваться из Azure Active Directory, содержащих доменные sAMAccountName или Граупсид, синхронизированные из Active Directory, а не Azure Active Directory objectID группы.Group and role claims may be emitted from Azure Active Directory containing the domain qualified sAMAccountName or the GroupSID synced from Active Directory rather than the group's Azure Active Directory objectID.

Поддерживаемые форматы для утверждения группы:The supported formats for group claims are:

  • ObjectID группы Azure Active Directory (доступно для всех групп)Azure Active Directory Group ObjectId (Available for all groups)
  • SamAccountName (доступен для групп, синхронизированных из Active Directory)sAMAccountName (Available for groups synchronized from Active Directory)
  • Нетбиосдомаин\самаккаунтнаме (доступно для групп, синхронизированных из Active Directory)NetbiosDomain\sAMAccountName (Available for groups synchronized from Active Directory)
  • Днсдомаиннаме\самаккаунтнаме (доступно для групп, синхронизированных из Active Directory)DNSDomainName\sAMAccountName (Available for groups synchronized from Active Directory)
  • Идентификатор безопасности локальной группы (доступен для групп, синхронизированных из Active Directory)On Premises Group Security Identifier (Available for groups synchronized from Active Directory)

Примечание

атрибуты идентификатора безопасности sAMAccountName и on локальной группы доступны только для объектов группы, синхронизированных из Active Directory.sAMAccountName and On Premises Group SID attributes are only available on Group objects synced from Active Directory. Они недоступны в группах, созданных в Azure Active Directory или Office 365.They aren't available on groups created in Azure Active Directory or Office365. Приложения, настроенные в Azure Active Directory для получения синхронизированных атрибутов локальной группы, получают их только для синхронизированных групп.Applications configured in Azure Active Directory to get synced on-premises group attributes get them for synced groups only.

Параметры для использования сведений о группе в приложенияхOptions for applications to consume group information

Приложения могут вызывать конечную точку группы MS Graph для получения сведений о группе для пользователя, прошедшего проверку подлинности.Applications can call the MS Graph groups endpoint to obtain group information for the authenticated user. Этот вызов гарантирует, что все группы, членом которых является пользователь, будут доступны даже при наличии большого количества групп.This call ensures that all the groups a user is a member of are available even when there are a large number of groups involved. Затем перечисление групп не зависит от ограничений размера маркера.Group enumeration is then independent of token size limitations.

Однако если существующее приложение планирует использовать сведения о группе через утверждения, Azure Active Directory можно настроить с помощью ряда различных форматов утверждений.However, if an existing application expects to consume group information via claims, Azure Active Directory can be configured with a number of different claims formats. Следуйте приведенным ниже рекомендациям.Consider the following options:

  • При использовании членства в группах в целях авторизации в приложении предпочтительнее использовать группу ObjectID.When using group membership for in-application authorization purposes it is preferable to use the Group ObjectID. Группа ObjectID является неизменяемой и уникальна в Azure Active Directory и доступна для всех групп.The Group ObjectID is immutable and unique in Azure Active Directory and available for all groups.
  • Если для авторизации используется локальная группа sAMAccountName, используйте полные имена доменов; вероятность конфликта имен меньше.If using the on-premises group sAMAccountName for authorization, use domain qualified names; there’s less chance of names clashing. значение sAMAccountName может быть уникальным в домене Active Directory, но если несколько Active Directory домена синхронизируются с клиентом Azure Active Directory, существует возможность, чтобы несколько групп имели одно и то же имя.sAMAccountName may be unique within an Active Directory domain, but if more than one Active Directory domain is synchronized with an Azure Active Directory tenant there is a possibility for more than one group to have the same name.
  • Рассмотрите возможность использования ролей приложения для обеспечения уровня косвенного обращения между членством в группе и приложением.Consider using Application Roles to provide a layer of indirection between the group membership and the application. Затем приложение выполняет внутренние решения по авторизации на основе роли Кламс в маркере.The application then makes internal authorization decisions based on role clams in the token.
  • Если приложение настроено для получения атрибутов группы, которые синхронизируются из Active Directory и группа не содержит этих атрибутов, она не будет включена в утверждения.If the application is configured to get group attributes that are synced from Active Directory and a Group doesn't contain those attributes, it won't be included in the claims.
  • Групповые утверждения в маркерах включают вложенные группы, за исключением случаев использования параметра для ограничения групповых утверждений группам, назначенным приложению.Group claims in tokens include nested groups except when using the option to restrict the group claims to groups assigned to the application. Если пользователь является членом Граупб, а Граупб является членом группы a, то утверждения группы для пользователя будут содержать как группы a, так и Граупб.If a user is a member of GroupB and GroupB is a member of GroupA, then the group claims for the user will contain both GroupA and GroupB. Если пользователи организации имеют большое количество членств в группах, число групп, перечисленных в маркере, может увеличить размер маркера.When an organization's users have large numbers of group memberships, the number of groups listed in the token can grow the token size. Azure Active Directory ограничивает количество групп, которое будет выдаваться в токене, в 150 для утверждений SAML и 200 для JWT.Azure Active Directory limits the number of groups it will emit in a token to 150 for SAML assertions, and 200 for JWT. Если пользователь является членом большего числа групп, группы пропускаются, а вместо этого включается ссылка на конечную точку графа для получения сведений о группе.If a user is a member of a larger number of groups, the groups are omitted and a link to the Graph endpoint to obtain group information is included instead.

Необходимые условия для использования атрибутов группы, синхронизированных из Active DirectoryPrerequisites for using Group attributes synchronized from Active Directory

Утверждения членства в группе можно создавать в токенах для любой группы, если используется формат ObjectId.Group membership claims can be emitted in tokens for any group if you use the ObjectId format. Чтобы использовать групповые утверждения в форматах, отличных от ObjectId, группы необходимо синхронизировать из Active Directory с помощью Azure AD Connect.To use group claims in formats other than the group ObjectId, the groups must be synchronized from Active Directory using Azure AD Connect.

Настройка Azure Active Directory для создания имен групп для Active Directory групп состоит из двух этапов.There are two steps to configuring Azure Active Directory to emit group names for Active Directory Groups.

  1. Синхронизация имен групп из Active Directory Прежде чем Azure Active Directory может выдать имена групп или идентификатор безопасности локальной группы в утверждениях группы или роли, необходимо синхронизировать необходимые атрибуты из Active Directory.Synchronize group names from Active Directory Before Azure Active Directory can emit the group names or on premises group SID in group or role claims, the required attributes need to be synchronized from Active Directory. Необходимо запустить Azure AD Connect версии 1.2.70 или более поздней.You must be running Azure AD Connect version 1.2.70 or later. Более ранние версии Azure AD Connect, чем 1.2.70, будут синхронизировать объекты группы из Active Directory, но не будут содержать обязательные атрибуты имени группы.Earlier versions of Azure AD Connect than 1.2.70 will synchronize the group objects from Active Directory, but will not include the required group name attributes. Обновление до текущей версии.Upgrade to the current version.

  2. Настройка регистрации приложения в Azure Active Directory для включения групповых утверждений в токенах Утверждения группы можно настроить в разделе корпоративные приложения на портале или с помощью манифеста приложения в разделе регистрации приложений.Configure the application registration in Azure Active Directory to include group claims in tokens Group claims can be configured in the Enterprise Applications section of the portal, or using the Application Manifest in the Application Registrations section. Сведения о настройке групповых утверждений в манифесте приложения см. в разделе "Настройка регистрации приложения Azure Active Directory для атрибутов группы" ниже.To configure group claims in the application manifest see “Configuring the Azure Active Directory Application Registration for group attributes” below.

Добавление групповых утверждений в токены для приложений SAML с помощью конфигурации единого входаAdd group claims to tokens for SAML applications using SSO configuration

Чтобы настроить утверждения группы для приложения SAML коллекции или не коллекции, откройте приложение " корпоративные приложения", щелкните приложение в списке, выберите Конфигурация единого входа, а затем выберите атрибуты пользователя & утверждения.To configure Group Claims for a Gallery or Non-Gallery SAML application, open Enterprise Applications, click on the application in the list, select Single Sign On configuration, and then select User Attributes & Claims.

Щелкните " Добавить утверждение группы ".Click on Add a group claim

Пользовательский интерфейс утверждений

Использование переключателей для выбора групп, которые должны быть добавлены в маркерUse the radio buttons to select which groups should be included in the token

Пользовательский интерфейс утверждений

ВыборSelection ОписаниеDescription
Все группыAll groups Выдает группы безопасности и списки рассылки и роли.Emits security groups and distribution lists and roles.
Группы безопасностиSecurity groups Создает группы безопасности, членом которых является пользователь в утверждении группEmits security groups the user is a member of in the groups claim
Роли каталогаDirectory roles Если пользователю назначаются роли каталога, они выдаются как утверждение "видс" (утверждение групп не будет выдаваться).If the user is assigned directory roles, they are emitted as a 'wids' claim (groups claim won't be emitted)
Группы, назначенные приложениюGroups assigned to the application Выдает только те группы, которые явным образом назначены приложению, а пользователь является членомEmits only the groups that are explicitly assigned to the application and the user is a member of

Например, чтобы выдать всех групп безопасности, членом которых является пользователь, выберите группы безопасности.For example, to emit all the Security Groups the user is a member of, select Security Groups

Пользовательский интерфейс утверждений

Чтобы выдать группы с использованием Active Directoryных атрибутов, синхронизированных из Active Directory вместо идентификаторов objectID Azure AD выберите нужный формат в раскрывающемся списке.To emit groups using Active Directory attributes synced from Active Directory instead of Azure AD objectIDs select the required format from the drop-down. В утверждениях будут включаться только группы, синхронизированные из Active Directory.Only groups synchronized from Active Directory will be included in the claims.

Пользовательский интерфейс утверждений

Чтобы выдать приложению только группы, назначенные для приложения, выберите группы, назначенные приложению .To emit only groups assigned to the application, select Groups Assigned to the application

Пользовательский интерфейс утверждений

Группы, назначенные приложению, будут включаться в маркер.Groups assigned to the application will be included in the token. Другие группы, членом которых является пользователь, будут пропущены.Other groups the user is a member of will be omitted. При использовании этого параметра вложенные группы не включаются, и пользователь должен быть прямым членом группы, назначенной приложению.With this option nested groups are not included and the user must be a direct member of the group assigned to the application.

Чтобы изменить группы, назначенные приложению, выберите приложение из списка корпоративные приложения , а затем щелкните Пользователи и группы в левом меню навигации приложения.To change the groups assigned to the application, select the application from the Enterprise Applications list and then click Users and Groups from the application’s left-hand navigation menu.

Сведения об управлении назначением групп для приложений см. в документе Назначение пользователя или группы корпоративному приложению .See the document Assign a user or group to an enterprise app for details of managing group assignment to applications.

Дополнительные параметры.Advanced options

Способ выдачи заявок на группы можно изменить с помощью параметров в разделе Дополнительные параметры.The way group claims are emitted can be modified by the settings under Advanced options

Настройка имени утверждения группы. Если этот параметр выбран, для групповых утверждений можно указать другой тип утверждения.Customize the name of the group claim: If selected, a different claim type can be specified for group claims. Введите тип утверждения в поле имя и необязательное пространство имен для утверждения в поле пространство имен.Enter the claim type in the Name field and the optional namespace for the claim in the namespace field.

Пользовательский интерфейс утверждений

Для некоторых приложений требуется, чтобы сведения о членстве в группе отображались в утверждении Role.Some applications require the group membership information to appear in the 'role' claim. При необходимости можно создать группы пользователей в качестве ролей, установив флажок "выдавать группы в утверждениях ролей".You can optionally emit the user's groups as roles by checking the 'Emit groups a role claims' box.

Пользовательский интерфейс утверждений

Примечание

Если используется параметр для отправки данных группы в качестве ролей, в заявке роли будут отображаться только группы.If the option to emit group data as roles is used, only groups will appear in the role claim. Любые роли приложений, назначенные пользователю, не будут отображаться в заявке роли.Any Application Roles the user is assigned will not appear in the role claim.

Изменение конфигурации групповых утвержденийEdit the group claims configuration

После добавления конфигурации утверждения группы в атрибуты пользователя & конфигурации утверждений возможность добавления утверждения группы будет неактивна. Чтобы изменить конфигурацию утверждения группы, щелкните утверждение группы в списке дополнительных утверждений .Once a group claim configuration has been added to the User Attributes & Claims configuration, the option to add a group claim will be greyed out. To change the group claim configuration click on the group claim in the Additional claims list.

Пользовательский интерфейс утверждений

Настройка регистрации приложения Azure AD для атрибутов группыConfigure the Azure AD Application Registration for group attributes

Утверждения группы также можно настроить в разделе необязательные утверждения манифеста приложения.Group claims can also be configured in the Optional Claims section of the Application Manifest.

  1. На портале >регистрация приложения Azure Active Directory > — >выберите манифест приложения->.In the portal ->Azure Active Directory -> Application Registrations->Select Application->Manifest

  2. Включение утверждений о членстве в группах путем изменения ГраупмембершипклаимEnable group membership claims by changing the groupMembershipClaim

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

ВыборSelection ОписаниеDescription
Каждого"All" Выдает группы безопасности, списки рассылки и ролиEmits security groups, distribution lists and roles
"SecurityGroup""SecurityGroup" Создает группы безопасности, членом которых является пользователь в утверждении группEmits security groups the user is a member of in the groups claim
"DirectoryRole"DirectoryRole Если пользователю назначаются роли каталога, они выдаются как утверждение "видс" (утверждение групп не будет выдаваться).If the user is assigned directory roles, they are emitted as a 'wids' claim (groups claim won't be emitted)
"ApplicationGroup"ApplicationGroup Выдает только те группы, которые явным образом назначены приложению, а пользователь является членомEmits only the groups that are explicitly assigned to the application and the user is a member of

Пример:For example:

"groupMembershipClaims": "SecurityGroup"

По умолчанию группы ObjectID будут выдаваться в значении утверждения группы.By default Group ObjectIDs will be emitted in the group claim value. Чтобы изменить значение утверждения в соответствии с атрибутами локальной группы или изменить тип утверждения на роль, используйте конфигурацию OptionalClaims следующим образом.To modify the claim value to contain on premises group attributes, or to change the claim type to role, use OptionalClaims configuration as follows:

  1. Задайте необязательные утверждения для конфигурации имени группы.Set group name configuration optional claims.

    Если требуется, чтобы группы в токене содержали атрибуты on локальной группы AD, укажите, к какому типу токена следует применить обязательное утверждение в разделе дополнительные утверждения.If you want the groups in the token to contain the on premises AD group attributes, specify which token type optional claim should be applied to in the optional claims section. В списке можно указать несколько типов маркеров:Multiple token types can be listed:

    • idToken для маркера идентификатора OIDC;idToken for the OIDC ID token
    • accessToken для маркера доступа OAuth/OIDCaccessToken for the OAuth/OIDC access token
    • Saml2Token для маркеров SAML.Saml2Token for SAML tokens.

    Примечание

    Тип Saml2Token применяется к маркерам формата SAML1.1 и SAML2.0.The Saml2Token type applies to both SAML1.1 and SAML2.0 format tokens

    Для каждого соответствующего типа токена измените утверждение групп, чтобы в манифесте использовался раздел OptionalClaims.For each relevant token type, modify the groups claim to use the OptionalClaims section in the manifest. Схема OptionalClaims выглядит следующим образом:The OptionalClaims schema is as follows:

    {
    "name": "groups",
    "source": null,
    "essential": false,
    "additionalProperties": []
    }
    
    Схема необязательных утвержденийOptional Claims Schema ЗначениеValue
    name:name: Должно быть "groups"Must be "groups"
    source:source: Не используется.Not used. Пропустите или укажите "null"Omit or specify null
    essential:essential: Не используется.Not used. Пропустите или укажите "false"Omit or specify false
    additionalProperties:additionalProperties: Список дополнительных свойств.List of additional properties. Допустимые значения: "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name", "emit_as_roles"Valid options are "sam_account_name", “dns_domain_and_sam_account_name”, “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".In additionalProperties only one of "sam_account_name", “dns_domain_and_sam_account_name”, “netbios_domain_and_sam_account_name” are required. Если указано более одного, используется первый, а остальные игнорируются.If more than one is present, the first is used and any others ignored.

    Некоторым приложениям требуются сведения о группе пользователя в утверждении роли.Some applications require group information about the user in the role claim. Чтобы изменить тип утверждения с утверждения группы на утверждение роли, добавьте "emit_as_roles" к дополнительным свойствам.To change the claim type to from a group claim to a role claim, add “emit_as_roles” to additional properties. Значения группы будут выдаваться в утверждении роли.The group values will be emitted in the role claim.

    Примечание

    Если используется "emit_as_roles", все роли приложения, настроенные для назначения пользователя, не будут отображаться в утверждении роли.If "emit_as_roles" is used any Application Roles configured that the user is assigned will not appear in the role claim

ПримерыExamples

Выдавать группы в виде имен групп в маркерах доступа OAuth в формате Днсдомаиннаме\самаккаунтнамеEmit groups as group names in OAuth access tokens in dnsDomainName\SAMAccountName format

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

Чтобы выдать имена групп, возвращаемых в формате Нетбиосдомаин\самаккаунтнаме, в качестве утверждения ролей в маркерах ИДЕНТИФИКАТОРов SAML и OIDC:To emit group names to be returned in netbiosDomain\samAccountName format as the roles claim in SAML and OIDC ID Tokens:

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

    "idToken": [{
        "name": "groups",
        "additionalProperties": ["netbios_name_and_sam_account_name", "emit_as_roles"]
    }]
 }

Дальнейшие шагиNext steps