---
title: "User Group Mapping"
sidebar_label: "Group mapping"
sidebar_position: 4
description: "How to configure mapping between an identity provider user group and a Selectel user group"
---

import Formbricks from '@theme/MDXComponents/Formbricks'
import TrashIcon from '@selectel/docux/icons/trash'
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
import {TabItemLabel} from '@selectel/docux/components'

# User Group Mapping

If you use [federations](/access-control/federations/) and have user groups on the identity provider side, you can configure group mapping to integrate them into Selectel user groups.

## How it works \{#principle-of-operation}

Users from a mapped identity provider group will be added to the Selectel group automatically upon [first authentication](/access-control/federations/sso-authentication.mdx#first-auth). Users will be assigned the [permissions](/access-control/access-management.mdx#permissions) that you specify for the Selectel user group when [configuring group mapping](#configure-group-mapping).

If permissions or user data change on the identity provider side, the changes will be applied in Selectel upon re-authentication.

You can map one identity provider group to one Selectel user group. You cannot map a Selectel group to multiple identity providers, or vice versa.

## Configure group mapping \{#configure-group-mapping}

1. [Create user groups](#create-groups).
2. [Add group mapping](#add-group-mapping).
3. [Configure mappings on the identity provider side](#configure-provider-mapping).
4. [Add users to a group on the identity provider side](#add-users-to-provider-group).

### 1. Create user groups \{#create-groups}

1. Make sure you have a user group on the identity provider side.
2. If you already have a user group on the Selectel side and want to use it for mapping, you do not need to create a new group. If you do not have a group or want to use a new one:

   2.1. [Add a user group](/access-control/groups/create-group.mdx#add-group).

   2.2. [Assign permissions to the user group](/access-control/groups/create-group.mdx#assign-permissions).

### 2. Add group mapping \{#add-group-mapping}

1. In the [control panel](https://my.selectel.ru/iam/federations), on the top menu, click **IAM**.

2. Go to the **Federations** section.

3. Open the federation page → **Group Mapping** tab.

4. Click **Map groups**.

5. In the **Mapped groups** block:

   5.1. Select the Selectel group you created in [step 1](#create-groups) or earlier.

   5.2. Enter the name of the identity provider group.

6. Optional: to add another group mapping, click **Add mapping** and repeat step 5.

7. Click **Save settings**.

### 3. Configure mappings on the identity provider side \{#configure-provider-mapping}

<Tabs queryString="configure-provider-mapping">
  <TabItem value="keycloak" default>
    <TabItemLabel>
      Keycloak
    </TabItemLabel>

    <Tabs queryString="configure-provider-mapping-keycloak">
      <TabItem value="saml" default>
        <TabItemLabel>
          SAML
        </TabItemLabel>

        1. In the Keycloak control panel, log in to the administrator account (Administration Console).

        2. Go to the **Client scopes** section → **Setup** tab.

        3. Select the client scope specified in the `<client_id>-dedicated` format. Here, `<client_id>` is the URL you entered when [configuring the SAML application](/access-control/federations/manage-saml/create-saml-federation-keycloak.mdx#configure-saml) in the **Client ID** field.

        4. Configure user group mapping:

           4.1. On the **Mappers** tab, click **Add mapper** → **By configuration** → **Group list**.

           4.2. In the **Name** field, enter a name for the mapping.

           4.3. In the **Group attribute names** field, enter **groups**.

           4.4. Turn on the **Single Group Attribute** toggle.

           4.5. Turn off the **Full group path** toggle.

           4.6. Click **Save**.

        5. Configure user email mapping:

           5.1. On the **Mappers** tab, click **Add mapper** → **From predefined mappers** → **x500 email**.

           5.2. Open the **x500 email** mapping.

           5.3. In the **SAML Attribute Name** field, enter `email`.

           5.4. Click **Save**.

        6. Configure user name mapping:

           6.1. On the **Mappers** tab, click **Add mapper** → **From predefined mappers** → **x500 givenName**.

           6.2. Open the **x500 givenName** mapping.

           6.3. In the **SAML Attribute Name** field, enter `firstName`.

           6.4. Click **Save**.

        7. Configure user surname mapping:

           7.1. On the **Mappers** tab, click **Add mapper** → **From predefined mappers** → **x500 lastName**.

           7.2. Open the **x500 lastName** mapping.

           7.3. In the **SAML Attribute Name** field, enter `lastName`.

           7.4. Click **Save**.
      </TabItem>

      <TabItem value="oidc">
        <TabItemLabel>
          OIDC
        </TabItemLabel>

        1. In the Keycloak control panel, log in to the administrator account (Administration Console).

        2. Go to the **Clients** section.

        3. Open the client page → the **Client scopes** tab.

        4. Select the client scope specified in the `<client_id>/dedicated` format. Here, `<client_id>` is the identifier you entered when [configuring the federation on the Keycloak side](/access-control/federations/manage-oidc/create-oidc-federation-keycloak.mdx#configure-federation-for-identity-provider) in the **Client ID** field.

        5. Click **Configure a new mapper** → **Group Membership**.

        6. In the **Name** field, enter a name for the mapping.

        7. In the **Token Claim Name** field, enter **groups**.

        8. Clear the **Full group path** checkbox.

        9. Select the **Add to ID Token** checkbox.

        10. Click **Save**.
      </TabItem>
    </Tabs>
  </TabItem>

  <TabItem value="ad-fs">
    <TabItemLabel>
      AD FS
    </TabItemLabel>

    <Tabs queryString="configure-provider-mapping-adfs">
      <TabItem value="saml" default>
        <TabItemLabel>
          SAML
        </TabItemLabel>

        1. On the AD FS server, open **Server Manager**.

        2. In the **Tools** menu, select **AD FS Management**.

        3. In the **Actions** block, select **Relying Party Trust**.

        4. Right-click the Relying Party Trust you added when [configuring trust relationships](/access-control/federations/manage-saml/create-saml-federation-adfs.mdx#configure-relying-party-trust) during federation creation, and select **Edit Claim Issuance Policy**.

        5. Click **Add Rule**.

        6. At the **Choose rule type** stage:

           6.1. In the **Claim rule template** field, select **Send LDAP Attributes as Claims**.

           6.2. Optional: enter a description.

           6.3. Click **Next**.

        7. At the **Configure Claim Rule** stage:

           7.1. In the **Claim rule name** field, enter a name for the mapping.

           7.2. In the **Attribute Store** field, select **Active Directory**.

           7.3. In the **Mapping of LDAP attributes to outgoing claim types** block:

           * in the left column, select **Token-Groups - Unqualified Names**;
           * in the right column, enter **groups**.

           7.4. Click **Finish**.
      </TabItem>

      <TabItem value="oidc">
        <TabItemLabel>
          OIDC
        </TabItemLabel>

        1. On the AD FS server, open **Server Manager**.
        2. In the **Application Group** folder, right-click the Application Group you configured during federation creation and select **Properties**.
        3. In the **Applications** list, select **Web API**.
        4. Open the **Issuance Transform Rules** tab.
        5. Click **Add Rule**.
        6. At the **Choose Rule Type** stage, in the **Claim rule template** field, select **Send LDAP Attributes as Claims**.
        7. At the **Configure Claim Rule** stage:

           7.1. In the **Claim rule name** field, enter a name for the mapping.

           7.2. In the **Attribute Store** field, select **Active Directory**.

           7.3. In the **Mapping of LDAP attributes to outgoing claim types** block, in the first column, select **Token-Groups - Unqualified Names**.

           7.4. In the second column, enter **groups**.

           7.5. Click **Finish**.
      </TabItem>
    </Tabs>
  </TabItem>
</Tabs>

### 4. Add users to a group on the identity provider side \{#add-users-to-provider-group}

<Tabs queryString="add-users-to-provider-group">
  <TabItem value="keycloak" default>
    <TabItemLabel>
      Keycloak
    </TabItemLabel>

    1. In the Keycloak control panel, go to the **Users** section.

    2. Open the user page → **Groups** tab.

    3. Click **Join Group**.

    4. Select the group you want to add the user to.
  </TabItem>

  <TabItem value="ad-fs">
    <TabItemLabel>
      AD FS
    </TabItemLabel>

    1. On the AD FS server, open **Active Directory Users and Computers**.

    2. Select the user you want to add to the group.

    3. On the right, in the **Actions** section, select **Properties**.

    4. Open the **Member Of** tab.

    5. Click **Add**.

    6. Select the group you want to add the user to.

    7. Click **OK**.
  </TabItem>
</Tabs>

## Disable group mapping \{#disable-group-mapping}

After disabling group mapping, users will no longer be able to authenticate to the control panel via SSO.

You can re-enable group mapping at any time.

1. In the [control panel](https://my.selectel.ru/iam/federations), on the top menu, click **IAM**.
2. Go to the **Federations** section.
3. Open the federation page → **Group Mapping** tab.
4. In the **Settings enabled** block, turn off the toggle.

## Delete group mapping \{#delete-group-mapping}

After deleting group mapping, users from the identity provider group will no longer be able to authenticate to the control panel via SSO.

If users are added to another Selectel group that has mapping configured, they will retain access as part of the other group's mapping.

1. In the [control panel](https://my.selectel.ru/iam/federations), on the top menu, click **IAM**.
2. Go to the **Federations** section.
3. Open the federation page → **Group Mapping** tab.
4. In the **Mapped groups** block, in the mapping row, click <TrashIcon />.
5. Click **Save settings**.

<Formbricks />