Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

User group mapping in Microsoft Active Directory Federation Services

Written by
Updated at April 16, 2025

You can use Active Directory Federation Services (AD FS) to authenticate users in an organization.

To configure mapping between user groups in AD FS and user groups in an identity federation:

  1. Collect the AD FS farm data.
  2. Create a Yandex Cloud Organization federation.
  3. Add an AD FS certificate to your federation.
  4. Create and configure a relying party trust on the AD FS side.
  5. Configure attribute mapping on the AD FS side.
  6. Configure group mapping on the federation side.
  7. Test authentication.

Getting started

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.

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

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

Collect AD FS farm data

  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:

    $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.

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

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

      Get-AdfsProperties | Select Identifier

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

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

    2. Get the federation service endpoint:

      Get-AdfsEndpoint -AddressPath /adfs/ls/ | Select FullUrl

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

      https://<AD_FS_farm_FQDN>/adfs/ls/

    Note

    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.

Create a Yandex Cloud Organization federation

  1. Go to Yandex Cloud Organization.

  2. In the left-hand panel, select Federations.

  3. Click 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.

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

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

    4. In the IdP Issuer field, paste the federation service ID you got when collecting AD FS farm data.

    5. Select POST from the Single Sign-On method drop-down list.

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

    7. Enable Automatically create users to automatically add a new user to your organization after authentication. Otherwise, you will need to manually add 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.

    8. (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 Download and save the downloaded certificate file. You will need to upload it to you IdP server.

      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 it on the IdP provider's side and in your federation well in advance.

      You can download and install a Yandex Cloud certificate even after creating a federation.

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

    9. Enable Mandatory re-authentication (ForceAuthn) in IdP to set ForceAuthn to true in the SAML authentication request. If enabled, the IdP will request the user to re-authenticate once the Yandex Cloud session expires.

    10. Click Create federation.

Add the AD FS certificate to the federation

To enable Cloud Organization to verify the AD FS certificate during authentication, add the certificate to the federation:

  1. Log in to Yandex Cloud Organization.

  2. In the left-hand panel, select Federations.

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

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

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

  6. Click Add.

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 to notifications from the organization. Subscribed users get notifications 60, 30, and 5 days before the certificate expires and after its expiration.

Create and configure a relying party trust on the AD FS side

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.

  2. 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.

  3. At the Welcome step, select Claims aware. Click Start.

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

  5. 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.

  6. Skip the Configure Certificate step by clicking Next.

  7. At the Configure URL step, specify the redirect URL.

    1. Check the Enable support for the SAML 2.0 Web SSO protocol box.

    2. Specify the redirect URL in the Relying party SAML 2.0 SSO service URL field.

      The redirect URL must be in the following format:

      https://console.cloud.yandex.ru/federations/<federation_ID>
      How to get the federation ID
      1. Log in to Yandex Cloud Organization.
      2. In the left-hand panel, select Federations.
      3. Select the required federation and copy the Identifier field value on the federation info page.

    3. Click Next.

  8. 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.

    2. Click Add.

    3. Click Next.

  9. 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 access control policies later.

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

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

    You will configure claim issuance policies later.

  12. (Optional) If you enabled Sign authentication requests when creating the federation in Yandex Cloud Organization, 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.

    2. Go to the Encryption tab and add the Yandex Cloud SAML certificate you downloaded earlier to sign authentication requests:

      1. Click Browse.

      2. 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 Cloud Organization federation info page by clicking Download certificate in the Sign authentication requests field.

    3. Go to the Signature tab and add the same certificate:

      1. Click Add.
      2. Select the certificate file.

    4. Click OK.

    5. Enable required claim encryption and request signing for the created relying party trust:

      Set-AdfsRelyingPartyTrust `
    -TargetName "Yandex Cloud" `
    -EncryptClaims $true `
    -SignedSamlRequestsRequired $true `
    -SamlResponseSignature MessageAndAssertion

Configure attribute mapping on the AD FS side

Create a user

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

  2. 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.

  3. Specify user info:

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

      Note

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

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

    You may provide other user info, if required.

  4. Click Next.

  5. Specify a password and configure the associated policies:

    1. Enter and confirm the password.

    2. 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.

    3. Make sure to uncheck Account is disabled.

      Warning

      Otherwise, the user account will be disabled.

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

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

  6. Click Next and then Finish.

Create a group

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

  2. 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.

  3. 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.

  4. Specify the group settings:

    • Group scope: Global
    • Group type: Security

  5. Click OK.

Add the user to the group

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

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

  3. 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.

  4. Go to the Members tab and click Add.

  5. Enter the adfs_demo_user username and click OK.

  6. Click OK.

Configure the access control policy

This policy enables authentication of users belonging to the previously created group.

To configure such a policy:

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

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

  3. Select the Yandex Cloud relying party trust in the result pane.

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

    This will open the window with a list of policies.

  5. Select the Permit Specific Group policy from the Choose an access control policy list.

  6. Click the parameter link in the Policy field with the selected policy description.

  7. Click Add.

  8. Enter the adfs_group group name and click OK.

  9. In the Select Groups window, click OK.

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

Configure LDAP attribute mapping

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

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

  3. Select the Yandex Cloud relying party trust in the result pane.

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

    This will open the window with a list of policies.

  5. Click Add Rule.

    This will open the Add Transform Claim Rule wizard.

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

  7. 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). The UPN of the previously created user will look like this:

      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

      Tip

      To send other supported user attributes, add more mappings, if required.

  8. Click Finish.

  9. Click OK.

Configure group mapping on the federation side

  1. Log in to Yandex Cloud Organization.

  2. Create a user group named yc-demo-group in Cloud Organization and authorize it to view resources in the cloud or a separate folder (the viewer role).

  3. In the left-hand panel, select Federations.

  4. Select demo-federation you created previously and navigate to the IdP group tab.

  5. Enable Mapping group in IdP.

  6. Click Add group.

  7. In the Group name field, enter the group ID provided in AD FS claims.

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

  8. In the IAM group field, select the yc-demo-group group you created in Yandex Cloud Organization from the list.

  9. Click Save.

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

    # 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.

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

    For more information, see yandex_organizationmanager_group_mapping and yandex_organizationmanager_group_mapping_item in the Terraform provider documentation.

  2. Create the resources:

    1. In the terminal, change to the folder where you edited the configuration file.

    2. Make sure the configuration file is correct using the command:

      terraform validate

      If the configuration is correct, the following message is returned:

      Success! The configuration is valid.

    3. Run the command:

      terraform plan

      The terminal will display a list of resources with parameters. No changes are made at this step. If the configuration contains errors, Terraform will point them out.

    4. Apply the configuration changes:

      terraform apply

    5. Confirm the changes: type yes in the terminal and press Enter.

Test authentication

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

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

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

    https://console.cloud.yandex.com/federations/<federation_ID>
    How to get the federation ID
    1. Log in to Yandex Cloud Organization.
    2. In the left-hand panel, select Federations.
    3. Select the required federation and copy the Identifier field value on the federation info page.

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

  3. Enter the credentials of the adfs_demo_user@example.com user you created earlier 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 settings and then to the management console home page.

  4. 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.

Previous
Authentication using Keycloak
Next
User group mapping in Microsoft Entra ID