[Yandex Cloud documentation](../../../../index.md) > [Yandex Identity Hub](../../../index.md) > [Tutorials](../../index.md) > [Managing identity federations](../index.md) > User group mapping > User group mapping in Active Directory Federation Services

# User group mapping in Microsoft Active Directory Federation Services

You can use [Active Directory Federation Services](https://learn.microsoft.com/ru-ru/windows-server/identity/ad-fs/ad-fs-overview) (AD FS) to authenticate users in an organization.

To configure mapping between user groups in AD FS and user groups in an [identity federation](../../../concepts/add-federation.md):

1. [Collect the AD FS farm data](#get-adfs-info).
1. [Create a Yandex Identity Hub federation](#create-federation).
1. [Add an AD FS certificate to your federation](#add-certificate).
1. [Create and configure a relying party trust on the AD FS side](#create-relying-party-trust).
1. [Configure attribute mapping on the AD FS side](#adfs-mapping).
1. [Configure group mapping on the federation side](#org-mapping).
1. [Test authentication](#test-auth).

## Getting started {#before-you-begin}

Make sure to meet the following prerequisites:

1. You have access to the **Active Directory Users and Computers** MMC snap-in to manage domain computers, users, and groups.

1. You have configured a AD FS farm with one or more valid `Token-signing` certificates to sign tokens.

1. You have access to the following tools to manage this farm:

    * **AD FS Management** MMC snap-in.
    * [PowerShell module](https://learn.microsoft.com/en-us/powershell/module/adfs/) to manage AD FS.

## Collect AD FS farm data {#get-adfs-info}

1. Get and save the certificate that will be used to sign messages from AD FS.

    To get a `Token-Signing` certificate in Base64 format, run the following commands in PowerShell, providing the path where to save the certificate:

    ```powershell
    $ADFS_CERT_PATH = "<path_to_certificate>/adfs_certificate.cer"
    
    $TEMP_CERT = (Get-AdfsCertificate -CertificateType Token-Signing |
                    where {$_.IsPrimary -eq $true} | Select-Object -First 1
                 ).Certificate.Export([System.Security.Cryptography.X509Certificates.X509ContentType]::Cert)
    
    @(
        '-----BEGIN CERTIFICATE-----'
        [System.Convert]::ToBase64String($TEMP_CERT, 'InsertLineBreaks')
        '-----END CERTIFICATE-----'
    ) | Out-File -FilePath $ADFS_CERT_PATH -Encoding ascii
    
    ```
    
    The certificate will be saved as `adfs_certificate.cer`.

1. Get and save the credentials you will use to configure your identity federation:

    1. Get the FS ID (**Federation Service identifier**):

        ```powershell
        Get-AdfsProperties | Select Identifier
        ```

        The ID contains the FQDN of the AD FS farm and has the following format:

        ```text
        http://<AD_FS_farm_FQDN>/adfs/services/trust
        ```

    1. Get the federation service endpoint:
       
        ```powershell
        Get-AdfsEndpoint -AddressPath /adfs/ls/ | Select FullUrl
        ```
       
       The endpoint contains the FQDN of the AD FS farm and has the following format:
       
       ```text
       https://<AD_FS_farm_FQDN>/adfs/ls/
       ```

    {% note info %}

    The `http://` scheme in the ID is does not mean that data will be sent in plain text over HTTP.

    AD FS and Yandex Cloud will interact via an endpoint over HTTPS.

    {% endnote %}

## Create a Yandex Identity Hub federation {#create-federation}

{% list tabs group=instructions %}

- Cloud Center UI {#cloud-center}

  1. Go to [Yandex Identity Hub](https://center.yandex.cloud/organization).

  1. In the left-hand panel, select ![icon-federation](../../../../_assets/console-icons/vector-square.svg) **Federations**.

  1. Click ![Circles3Plus](../../../../_assets/console-icons/circles-3-plus.svg) **Create federation** in the top-right corner of the page. In the window that opens:

      1. Enter a name for the federation, e.g., `demo-federation`. It must be unique within the folder.

      1. You can also add a description, if required.

      1. In the **Cookie lifetime** field, specify the time before the browser asks the user to re-authenticate.

      1. In the **IdP Issuer** field, paste the federation service ID [you got when collecting AD FS](#get-adfs-info) farm data.

      1. Select `POST` from the **Single Sign-On method** drop-down list.

      1. In the **Link to the IdP login page** field, paste the federation service endpoint you got when collecting AD FS farm data.

      1. Enable **Automatically create users** to automatically add a new user to your organization after authentication. Otherwise, you will need to [manually add](../../../operations/add-account.md#add-user-sso) your federated users.

          A federated user is created automatically only when they log in to a cloud for the first time. If you removed a user from the federation, you can only add them back manually.

      1. (Optional) To make sure that all authentication requests from Yandex Cloud contain a digital signature, enable **Sign authentication requests**. You will need to install a Yandex Cloud SAML certificate on the IdP side.

          In the **SAML certificates** block that appears, you will see the information about the current Yandex Cloud SAML certificate.
          
          Click ![ArrowDownToLine](../../../../_assets/console-icons/arrow-down-to-line.svg) **Download** and save the downloaded certificate file. You will need to upload it to you IdP server.
          
          {% note tip %}
          
          Track certificate expiration dates and always install a new certificate before the current one expires. Make sure to [download the re-issued Yandex Cloud SAML certificate and install](../../../operations/renew-yc-certificate.md) it on the IdP provider's side and in your federation well in advance.
          
          {% endnote %}

          You can [download and install](../../../operations/setup-federation.md#add-certificate-idp) a Yandex Cloud certificate even after creating a federation.

          You will need this certificate later when configuring the AD FS relying party trust.

      1. Enable **Mandatory re-authentication (ForceAuthn) in IdP** to set [ForceAuthn](../../../saml/api-ref/Federation/index.md) to `true` in the SAML authentication request. If enabled, the IdP will request the user to re-authenticate once the Yandex Cloud session expires. This is an optional parameter.

      1. Click **Create federation**.

{% endlist %}

## Add the AD FS certificate to the federation {#add-certificate}

To enable Yandex Identity Hub to verify the AD FS certificate during authentication, add the certificate to the federation:

{% list tabs group=instructions %}

- Cloud Center UI {#cloud-center}

  1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization).

  1. In the left-hand panel, select ![VectorSquare](../../../../_assets/console-icons/vector-square.svg) **Federations**.

  1. Click the row with `demo-federation` to add your certificate to.

  1. Click **Certificates** under **Adding a certificate** at the bottom of the page.

  1. Enter the certificate name and specify the path to the `adfs_certificate.cer` file you saved earlier.

  1. Click **Add**.

{% endlist %}

{% note tip %}

Make sure to reissue certificates and add them to a federation in a timely manner.

To keep track of when your certificate expires, [subscribe](../../../operations/subscribe-user-for-notifications.md) to notifications from the organization. Subscribed users get notifications 60, 30, and 5 days before the certificate expires and after its expiration.

{% endnote %}

## Create and configure a relying party trust on the AD FS side {#create-relying-party-trust}

AD FS acts as the identity provider (IdP), with a relying party trust configured. To create and configure a relying party trust:

1. Open the **AD FS Management** MMC snap-in.

1. In the console tree, under **AD FS**, right-click **Relying Party Trusts** and select **Add Relying Party Trust**.

    This will open the Add Relying Party Trust wizard.

1. At the **Welcome** step, select **Claims aware**. Click **Start**.

1. At the **Select Data Source** step, select **Enter data about the relying party manually**. Click **Next**.

1. At the **Specify Display Name** step, specify a name for the relying party trust, e.g., `Yandex Cloud`, and its description, if required. Click **Next**.

1. Skip the **Configure Certificate** step by clicking **Next**.

1. At the **Configure URL** step, specify the redirect URL.

    1. Check the **Enable support for the SAML 2.0 Web SSO protocol** box.
    1. Specify the redirect URL in the **Relying party SAML 2.0 SSO service URL** field.

        The redirect URL must be in the following format:

        ```text
        https://console.cloud.yandex.ru/federations/<federation_ID>
        ```

        {% cut "How to get the federation ID" %}

        1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization).
        1. In the left-hand panel, select ![VectorSquare](../../../../_assets/console-icons/vector-square.svg) **Federations**.
        1. Select the required federation and copy the **Identifier** field value on the federation info page.

        {% endcut %}

    1. Click **Next**.

1. At the **Configure Identifiers** step, specify the relying party ID:

    1. In the **Relying party identifier** field, specify the redirect URL from the previous step.

    1. Click **Add**.

    1. Click **Next**.

1. Enable **I do not want to configure access control policies at this time. No user will be permitted access for this application** at the **Choose Access Control Policy** step. Click **Next**.

    You will [configure](#configure-access-control-policy) access control policies later.

1. At the **Ready to Add Trust** step, make sure all the parameters are correct. Click **Next**.

1. Disable **Configure claims issuance policy for this application** at the **Finish** step. Click **Close**.

    You will [configure](#map-adfs-ldap) claim issuance policies later.

1. (Optional) If you enabled **Sign authentication requests** when [creating the federation](#create-federation) in Yandex Identity Hub, configure the associated relying party trust parameters:
   
   1. Open the context menu of the relying party trust you created and select **Properties**.
   
       This will open the window with relying party trust properties.
   
   1. Go to the **Encryption** tab and add the Yandex Cloud SAML certificate you downloaded [earlier](#create-federation) to sign authentication requests:
   
       1. Click **Browse**.
       1. Select the certificate file, such as `YandexCloud.cer`.
   
            If you did not download a SAML certificate when creating the federation, you can download it on the Yandex Identity Hub federation info page by clicking ![ArrowDownToLine](../../../../_assets/console-icons/arrow-down-to-line.svg) **Download certificate** in the **Sign authentication requests** field.
   
   1. Go to the **Signature** tab and add the same certificate:
   
       1. Click **Add**.
       1. Select the certificate file.
   
   1. Click **OK**.
   
   1. Enable required claim encryption and request signing for the created relying party trust:
   
       ```powershell
       Set-AdfsRelyingPartyTrust `
           -TargetName "Yandex Cloud" `
           -EncryptClaims $true `
           -SignedSamlRequestsRequired $true `
           -SamlResponseSignature MessageAndAssertion
       ```

## Configure attribute mapping on the AD FS side {#adfs-mapping}

### Create a user {#create-user}

1. Open the **Active Directory Users and Computers** MMC snap-in.

1. In the console tree, select the organization unit (OU) where you need to create a user, right-click it, and select **New** → **User**.

    This will open the New Object - User wizard.

1. Specify user info:

    * **User logon name**: Username, such as `adfs_demo_user`, in combination with the domain, e.g., `example.com`.

        {% note info %}

        In the steps below, we will use the `example.com` domain name. If your domain has a different name, adjust the following steps accordingly.

        {% endnote %}

    * **Full name**: Full name of the user, e.g., `Ivan Ivanov`.

    You may provide other user info, if required.

1. Click **Next**.

1. Specify a password and configure the associated policies:

    1. Enter and confirm the password.

    1. Optionally, disable **User must change password at next login**.

        Otherwise, the user will be prompted to change the password the first time they get authenticated in AD FS.

    1. Make sure to uncheck **Account is disabled**.

        {% note warning %}

        Otherwise, the user account will be disabled.

        The user will be unable to get authenticated in AD FS and access Yandex Cloud.

        {% endnote %}

    1. If required, select other options based on the relevant password policies.

1. Click **Next** and then **Finish**.

### Create a group {#create-group}

1. Open the **Active Directory Users and Computers** MMC snap-in.

1. In the console tree, select the organization unit where you need to create a group, right-click it and select **New** → **Group**.

    This will open the New Object - Group wizard.

1. Specify the group info:

    * **Group name**: Name of the group, e.g., `adfs_group`.
    * **Group name (pre-Windows 2000)**: Group name in the legacy format to use with pre-Windows 2000 systems.

        By default, this name is the same as the group name you specify. You can enter a different name, if required.

1. Specify the group settings:

    * **Group scope**: `Global`
    * **Group type**: `Security`

1. Click **OK**.

### Add the user to the group {#add-user-to-group}

1. Open the **Active Directory Users and Computers** MMC snap-in.

1. In the console tree, select the organization unit containing the `adfs_group` group.

1. In the result pane, select the `adfs_group` group. Then, right-click the group and select **Properties** from the context menu.

    This will open the window with group properties.

1. Go to the **Members** tab and click **Add**.

1. Enter the `adfs_demo_user` username and click **OK**.

1. Click **OK**.

### Configure the access control policy {#configure-access-control-policy}

This policy enables authentication of users belonging to the [previously created group](#create-group).

To configure such a policy:

1. Open the **AD FS Management** MMC snap-in.

1. In the console tree, select **AD FS** → **Relying Party Trusts**.

1. Select the `Yandex Cloud` [relying party trust](#create-relying-party-trust) in the result pane.

1. Right-click the trust and select **Edit Access Control Policy**.

    This will open the window with a list of policies.

1. Select the `Permit Specific Group` policy from the **Choose an access control policy** list.

1. Click the `parameter` link in the **Policy** field with the selected policy description.

1. Click **Add**.

1. Enter the `adfs_group` group name and click **OK**.

1. In the **Select Groups** window, click **OK**.

1. In the **Edit Access Control Policy for Yandex Cloud** window, click **OK**.

### Configure LDAP attribute mapping {#map-adfs-ldap}

1. Open the **AD FS Management** MMC snap-in.

1. In the console tree, select **AD FS** → **Relying Party Trusts**.

1. Select the `Yandex Cloud` [relying party trust](#create-relying-party-trust) in the result pane.

1. Right-click the trust and select **Edit Claim Issuance Policy**.

    This will open the window with a list of policies.

1. Click **Add Rule**.

    This will open the Add Transform Claim Rule wizard.

1. Select `Send LDAP Attributes as Claims` from the **Claim rule template** drop-down list at the **Choose rule type** step. Click **Next**.

1. Configure the rule at the **Configure Claim Rule** step:

    * **Claim rule name**: Rule name, e.g., `LDAP Mappings`.

    * **Attribute store**: `Active Directory`.

    * **Mapping of LDAP attributes to outgoing claim types**: List of mappings in the form of attribute/outgoing claim type pairs.

        Add the following required mappings to the list to enable proper communication with Yandex Cloud:

        #|
        || **Attribute** | **Outgoing claim type** ||
        || `User-Principal-Name`

        Attribute to use to identify the user.

        In this case, the user will be identified by their [user principal name (UPN)](https://learn.microsoft.com/en-us/windows/win32/ad/naming-properties#userprincipalname). The UPN of the [previously created user](#create-user) will look like this:

        ```text
        adfs_demo_user@example.com
        ```

        You may use a different attribute as long as it is permanent and unique to ensure unambiguous user identification. In this case, adjust the following steps.

        | `Name ID` ||

        || `Token-Groups - Unqualified Names`

        List of groups the user belongs to. This list will be used for group mapping when authenticating the user in Yandex Cloud.

        This specific attribute enables sending short group names, such as `adfs_group` or `Domain Users`, that do not specify a domain.

        You may use a different attribute from the `Token-Groups` family, e.g., `Token-Groups as SIDs`. In this case, adjust the following steps.

        | `Group` ||

        |#

        {% note tip %}

        To send [other supported user attributes](../integration-adfs.md#configure-claims-mapping), add more mappings, if required.

        {% endnote %}

1. Click **Finish**.
1. Click **OK**.

## Configure group mapping on the federation side {#org-mapping}

{% note info %}

To configure [user group](../../../concepts/user-pools.md) mapping on the Yandex Cloud side, [assign](../../../../iam/operations/roles/grant.md#resource) the user one of the following [roles](../../../../iam/concepts/access-control/roles.md):

* [`organization-manager.federations.editor`](../../../security/index.md#organization-manager-federations-editor)
* [`organization-manager.federations.admin`](../../../security/index.md#organization-manager-federations-admin)
* [`organization-manager.editor`](../../../security/index.md#organization-manager-editor)
* [`organization-manager.admin`](../../../security/index.md#organization-manager-admin)

The role must be assigned for the groups you intend to map.

{% endnote %}

{% list tabs group=instructions %}

- Cloud Center UI {#cloud-center}

  1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization).

  1. [Create a user group](../../../operations/create-group.md) named `yc-demo-group` in Yandex Identity Hub and [authorize it](../../../operations/access-group.md) to view resources in the cloud or a separate folder (the `viewer` role).

  1. In the left-hand panel, select ![VectorSquare](../../../../_assets/console-icons/vector-square.svg) **Federations**.

  1. Select `demo-federation` [you created previously](#create-federation) and navigate to the **IdP group** tab.

  1. Enable **Mapping group in IdP**.

  1. Click **Add group**.

  1. In the **Group name** field, enter the group ID provided in [AD FS](#map-adfs-ldap) claims.

      When using `Token-Groups - Unqualified Names`, specify the short group name, i.e., `adfs_group`, as the ID.

  1. In the **IAM group** field, select the `yc-demo-group` group you created in Yandex Identity Hub from the list.

  1. Click **Save**.

- Terraform {#tf}

  1. Describe the properties of the new resources in the Terraform configuration file:

      ```hcl
      # Creating a user group
      resource "yandex_organizationmanager_group" "my-group" {
        name            = "yc-demo-group"
        organization_id = "demo-federation"
      }

      # Assigning the viewer role for a folder
      resource "yandex_resourcemanager_folder_iam_member" "viewers" {
        folder_id = "<folder_ID>"
        role      = "viewer"
        member    = "group:${yandex_organizationmanager_group.my-group.id}"
      }

      # Enabling federated user group mapping
      resource "yandex_organizationmanager_group_mapping" "my_group_map" {
        federation_id = "demo-federation"
        enabled       = true
      }

      # Configuring a federated user group mapping
      resource "yandex_organizationmanager_group_mapping_item" "group_mapping_item" {
        federation_id     = "demo-federation"
        internal_group_id = yandex_organizationmanager_group.my-group.id
        external_group_id = "<adfs_group_ID>"

        depends_on = [yandex_organizationmanager_group_mapping.group_mapping]
      }
      ```

      Where:
      * `folder_id`: Folder the role is assigned for.
      * `external_group_id`: Group ID provided in [AD FS claims](#map-adfs-ldap).

         When using `Token-Groups - Unqualified Names`, specify the short group name, i.e., `adfs_group`, as the ID.

      For more information, see the descriptions of the [yandex_organizationmanager_group_mapping](../../../../terraform/resources/organizationmanager_group_mapping.md) and [yandex_organizationmanager_group_mapping_item](../../../../terraform/resources/organizationmanager_group_mapping_item.md) resources in the Terraform provider guides.

  1. Create the resources:

     1. In the terminal, navigate to the configuration file directory.
     1. Make sure the configuration is correct using this command:
     
        ```bash
        terraform validate
        ```
     
        If the configuration is valid, you will get this message:
     
        ```bash
        Success! The configuration is valid.
        ```
     
     1. Run this command:
     
        ```bash
        terraform plan
        ```
     
        You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
     1. Apply the configuration changes:
     
        ```bash
        terraform apply
        ```
     
     1. Type `yes` and press **Enter** to confirm the changes.

{% endlist %}

## Test authentication {#test-auth}

1. Open your browser in guest or private browsing mode.

    For this, you must use a domain-joined computer with access to AD FS.

1. Use this URL to log in to the management console:

    ```text
    https://console.cloud.yandex.com/federations/<federation_ID>
    ```

    {% cut "How to get the federation ID" %}

    1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization).
    1. In the left-hand panel, select ![VectorSquare](../../../../_assets/console-icons/vector-square.svg) **Federations**.
    1. Select the required federation and copy the **Identifier** field value on the federation info page.

    {% endcut %}

    If you have set everything up correctly, the browser will redirect you to the AD FS authentication page.

1. Enter the credentials of the `adfs_demo_user@example.com` user you [created earlier](#create-user) and click **Sign in**.

    On successful authentication, the IdP server will redirect you to the `https://console.cloud.yandex.ru/federations/<federation_ID>` URL you specified in the [relying party trust](#create-relying-party-trust) settings and then to the [management console](https://console.yandex.cloud) home page.

1. Make sure the signed in user belongs to `yc-demo-group` and has the viewer permissions for resources according to the role assigned to the group.