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

User group mapping in Keycloak

Written by
Updated at April 16, 2025

To configure user group mapping in Keycloak and user groups in the identity federation:

  1. Create a federation in Yandex Cloud Organization.
  2. Add a Keycloak certificate to the federation
  3. Create and configure a SAML application in Keycloak.
  4. Configure group mapping on the Keycloak side.
  5. Configure group mapping on the federation side.
  6. Test authentication.

Note

All examples were tested with Keycloak version 21.1.2.

Getting started

Tip

If you already have an active Keycloak server, check the Keycloak settings against the recommendations in this guide, and use your existing server instead of creating a new one. In this case, you can go directly to the Configure group mapping on the Keycloak side section.

  1. Set up a local Keycloak server for testing:

    1. If you do not have Docker yet, install it. Make sure Docker Engine is running.

    2. Install and run a Docker container with Keycloak version 21.1.2:

      docker run -p 8080:8080 \
-e KEYCLOAK_ADMIN=admin \
-e KEYCLOAK_ADMIN_PASSWORD=Pa55w0rd \
quay.io/keycloak/keycloak:21.1.2 start-dev

    As long as the container is running, the Keycloak administrator account will be available at http://localhost:8080/admin or http://0.0.0.0:8080/admin. The default login parameters are as follows:

    • User name or email: admin
    • Password: Pa55w0rd

    Note

    To enable employees on a corporate network or the internet to use Keycloak for authentication in your application, deploy the Keycloak IdP server on the network and set up a public address. For more information, see the Keycloak documentation.

  2. Get the certificate used for signing in Keycloak:

    1. Log in to the Keycloak administrator account at: http://<IP_or_URL_Keycloak>:8080/admin.

      If you are using a local server from a Docker image, the default login credentials are:

    2. In the Realm Settings section, select the Keys tab.

    3. In the RS256 line, click Certificate and copy the certificate value.

    4. Save the certificate to a file named keycloak-cert.cer in the following format:

    -----BEGIN CERTIFICATE-----
<certificate_value>
-----END CERTIFICATE-----

    You will need this certificate later when setting up the identity federation.

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, enter a link in this format:

      http://<Keycloak>_IP_or_URL:8080/realms/master

    5. In the Link to the IdP login page field, enter a link in this format:

      http://<Keycloak>_IP_or_URL:8080/realms/master/protocol/saml

      You can only use HTTP and HTTPS in a link.

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

    7. (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 setting up the client in Keycloak.

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

    9. Click Create federation.

Add the Keycloak certificate to the federation

To make sure that Cloud Organization can verify the Keycloak server 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 a name for the certificate and specify the path to the keycloak-cert.cer file.

  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 SAML application in Keycloak

A SAML application in Keycloak acts as an identity provider (IdP). To create and set up a SAML application:

  1. Log in to the Keycloak administrator account at: http://<IP_or_URL_Keycloak>:8080/admin.

    If you are using a local server from a Docker image, the default login credentials are:

  2. Create a SAML application:

    1. In the left-hand panel, select Clients. Click Create client.

    2. In the Client type field, select SAML.

    3. In the Client ID field, enter the ACS URL to redirect users to after successful authentication.

      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.
      How to get the federation ACS URL

      1. Log in to Yandex Cloud Organization.

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

      3. Select the required federation and copy the ACS URL field value on the federation info page.

    4. Click Next.

    5. Specify the ACS redirect URL,, in the following fields:

      • Home URL
      • Valid Redirect URIs
      • IDP Initiated SSO Relay State
      How to get the federation ACS URL

      1. Log in to Yandex Cloud Organization.

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

      3. Select the required federation and copy the ACS URL field value on the federation info page.

    6. Click Save.

  3. Set up the SAML application parameters in the Settings tab:

    1. Enable the following options:

      • Include AuthnStatement
      • Sign Assertions
      • Force name ID format
      • Force POST Binding
      • Front Channel Logout

    2. In the Signature Algorithm field, select RSA_SHA256.

    3. In the SAML Signature Key Name field, select CERT_SUBJECT.

    4. Select username as Name ID Format.

    5. Click Save.

  4. (Optional) If you enabled Sign authentication requests when creating the federation in Yandex Cloud Organization, set up digital signature verification in the SAML application:

    1. On the Keys tab of the SAML application, check that the Client Signature Required option is enabled.

    2. Click the Import key button under the automatically generated certificate and select Certificate PEM in the Archive Format field.

    3. Click Browse and select the Yandex Cloud SAML certificate you downloaded earlier to sign authentication requests.

      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.

    4. Click Import.

    5. Enable the Encrypt Assertions option.

    6. In the window that opens, select the Generate method and click Confirm.

    7. Click Import key under the generated certificate and select Certificate PEM in the Archive Format field.

    8. Click Browse and select the certificate you are going to use to sign authentication requests. The certificate is available for download on the Yandex Cloud Organization federation info page in the Sign authentication requests field.

    9. Click Import.

Configure group mapping on the Keycloak side

  1. Create a user:

    1. In the left-hand panel, select Users.
    2. Click Add user and enter a username, e.g., demo_user1.
    3. Click Create.
    4. In the Credentials tab, click Set Password and enter a password. For easier testing, disable the Temporary option.

  2. Create a group and add a user to it:

    1. In the left-hand panel, select Groups.
    2. Click Create group and enter a name for the group, e.g., kc_demo_group.
    3. Click the group name, click Add member on the Members tab, and add the demo_user1 user from the list to the group.

  3. Add a mapper to the Keycloak application:

    1. In the left-hand panel, select Clients and select the previously created application from the list.

    2. Navigate to the Client scopes tab and select the ACS URL with the -dedicated postfix: <ACS_URL>-dedicated.

      How to get the federation ACS URL

      1. Log in to Yandex Cloud Organization.

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

      3. Select the required federation and copy the ACS URL field value on the federation info page.

    3. On the Mappers tab, click Configure a new mapper. Select Group list from the drop-down list.

    4. Specify the following mapper settings:

      • Name: group_mapper
      • Group attribute name: member
      • SAML Attribute NameFormat: Basic
      • Single Group Attribute: On
      • Full group path: Off

    5. Click Save.

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 name in Keycloak: kc_demo_group.

  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 = "kc_demo_group"

  depends_on = [yandex_organizationmanager_group_mapping.group_mapping]
}

    Where:

    • folder_id: Folder the role is assigned for.

    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.

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

    https://console.yandex.cloud/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 Keycloak.

  3. Enter the username and password for the test federated user (demo_user1) and click Sign in.

    On successful authentication, the IdP server will redirect you to the ACS URL you specified in the Keycloak settings and then to the management console home page.

  4. Make sure the created demo_user1 belongs to yc_demo_group and has the viewer permissions for resources according to the role assigned to the group.

Previous
User group mapping in Microsoft Entra ID
Next
CAPTCHA in Android apps