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

Authentication using Keycloak

Written by
Updated at December 20, 2024

With an identity federation, you can use Keycloak to authenticate users in an organization.

Authentication setup includes the following steps:

  1. Creating and setting up a federation in Yandex Cloud Organization.

  2. Creating and setting up a SAML application in Keycloak.

  3. Adding users to Yandex Cloud Organization.

  4. Authentication.

Getting started

To follow the steps in this section, you will need:​

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

  2. Keycloak local IdP server. To install and start Keycloak, run these commands:

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

    git clone https://github.com/keycloak/keycloak-containers.git
cd ./keycloak-containers/docker-compose-examples
docker-compose -f keycloak-postgres.yml up

    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. Read more in the Keycloak documentation.

  3. Valid certificate used for signing in the Keycloak service. To get it:

    1. Log in to the Keycloak administrator account at:

      http://keycloak.example.com:8080/admin. Replace keycloak.example.com with your local server address, e.g., http://localhost:8080/admin.

      http://keycloak.example.com:8080/auth/admin. Replace keycloak.example.com with your local server address, e.g., http://localhost:8080/auth/admin.

      The default login parameters are as follows:

      • User name or email: admin.
      • Password: Pa55w0rd.

    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 as a text file with the .cer extension in the following format:

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

    You can also get the certificate through this direct link:

    http://keycloak.example.com:8080/realms/master/protocol/saml/descriptor. The certificate value is stored in the <ds:X509Certificate>...</ds:X509Certificate> tag.

    http://keycloak.example.com:8080/auth/realms/master/protocol/saml/descriptor. The certificate value is stored in the <ds:X509Certificate>...</ds:X509Certificate> tag.

Creating and setting up a federation in Yandex Cloud Organization

Create a 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. Give your federation a name. 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 of the form:

      • Keycloak 17 or higher

        http://<host>:8080/realms/master

        If you set up a public address for the IdP server, specify its URL. Here is an example:

        http://keycloak.example.com:8080/realms/master

      • Keycloak 16 or lower

        http://<host>:8080/auth/realms/master

        If you set up a public address for the IdP server, specify its URL. Here is an example:

        http://keycloak.example.com:8080/auth/realms/master

    5. In the Link to the IdP login page field, enter a link of the form:

      • Keycloak 17 or higher

        http://<host>:8080/realms/master/protocol/saml

        If you set up a public address for the IdP server, specify its URL. Here is an example:

        http://keycloak.example.com:8080/realms/master/protocol/saml

      • Keycloak 16 or lower

        http://<host>:8080/auth/realms/master/protocol/saml

        If you set up a public address for the IdP server, specify its URL. Here is an example:

        http://keycloak.example.com:8080/auth/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. To make sure all authentication requests from Yandex Cloud contain a digital signature, enable the Sign authentication requests option. To complete the configuration, download and install a Yandex Cloud certificate.

      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 also download a certificate after creating a federation. To do this, click Download certificate in the Sign authentication requests field on the Yandex Cloud Organization federation info page.

    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.

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

  1. View the description of the create federation command:

    yc organization-manager federation saml create --help

  2. Create a federation:

    • Keycloak 17 or higher

      yc organization-manager federation saml create --name my-federation \
  --organization-id <organization_ID> \
  --auto-create-account-on-login \
  --encrypted-assertions \
  --cookie-max-age 12h \
  --issuer "http://<host>:8080/realms/master" \
  --sso-binding POST \
  --sso-url "http://<host>:8080/realms/master/protocol/saml" \
  --force-authn

    • Keycloak 16 or lower

      yc organization-manager federation saml create --name my-federation \
  --organization-id <organization_ID> \
  --auto-create-account-on-login \
  --encrypted-assertions \
  --cookie-max-age 12h \
  --issuer "http://<host>:8080/auth/realms/master" \
  --sso-url "http://<host>:8080/auth/realms/master/protocol/saml" \
  --sso-binding POST \
  --force-authn

      Where:

      • --name: Federation name. It must be unique within the folder.

      • --organization-id: Organization ID.

      • --auto-create-account-on-login: Flag enabling the automatic creation of new cloud users after authenticating on the IdP server.
        This option makes it easier to create users; however, users created this way will not be able to do anything with cloud resources. This does not apply to the resources for which roles are assigned to the All users or All authenticated users public group.

        If this option is off, users not added to the organization will not be able to log in to the management console, even if they authenticate on your IdP server. In this case, you can manage a list of users allowed to use Yandex Cloud resources.

      • --encrypted-assertions: Flag enabling a digital signature for authentication requests. To complete the configuration, download and install a Yandex Cloud certificate.

      • --cookie-max-age: Time before the browser asks the user to re-authenticate.

      • --issuer: ID of the IdP server to use for authentication:

        • Keycloak 17 or higher

          http://<host>:8080/realms/master

          If you set up a public address for the IdP server, specify its URL. Here is an example:

          http://keycloak.example.com:8080/realms/master

        • Keycloak 16 or lower

          http://<host>:8080/auth/realms/master

          If you set up a public address for the IdP server, specify its URL. Here is an example:

          http://keycloak.example.com:8080/auth/realms/master

      • --sso-url: URL of the page the browser has to redirect the user to for authentication:

        • Keycloak 17 or higher

          http://<host>:8080/realms/master/protocol/saml

          If you set up a public address for the IdP server, specify its URL. Here is an example:

          http://keycloak.example.com:8080/realms/master/protocol/saml

        • Keycloak 16 or lower

          http://<host>:8080/auth/realms/master/protocol/saml

          If you set up a public address for the IdP server, specify its URL. Here is an example:

          http://keycloak.example.com:8080/auth/realms/master/protocol/saml

        You can only use HTTP and HTTPS in a link.

      • --sso-binding: Specify the single sign-on binding type. Most identity providers support the POST binding type.

      • (Optional) --force-authn: When the Yandex Cloud session expires, your IdP will prompt the user to re-authenticate.

  1. Create a request body file, e.g., body.json:

    • Keycloak 17 or higher

      {
  "name": "my-federation",
  "organizationId": "<organization_ID>",
  "autoCreateAccountOnLogin": true,
  "cookieMaxAge":"43200s",
  "issuer": "http://<host>:8080/realms/master",
  "ssoUrl": "http://<host>:8080/realms/master/protocol/saml",
  "securitySettings": {
      "encryptedAssertions": true,
      "forceAuthn": true
  },
  "ssoBinding": "POST"
}

    • Keycloak 16 or lower

      {
  "name": "my-federation",
  "organizationId": "<organization_ID>",
  "autoCreateAccountOnLogin": true,
  "cookieMaxAge":"43200s",
  "issuer": "http://<host>:8080/auth/realms/master",
  "ssoUrl": "http://<host>:8080/auth/realms/master/protocol/saml",
  "securitySettings": {
    "encryptedAssertions": true,
    "forceAuthn": true
  },
  "ssoBinding": "POST"
}

      Where:

      • name: Federation name. It must be unique within the folder.

      • organizationId: Organization ID.

      • autoCreateAccountOnLogin: Flag enabling the automatic creation of new cloud users after authenticating on the IdP server.
        This option makes it easier to create users; however, users created this way will not be able to do anything with cloud resources. This does not apply to the resources for which roles are assigned to the All users or All authenticated users public group.

        If this option is off, users not added to the organization will not be able to log in to the management console, even if they authenticate on your IdP server. In this case, you can manage a list of users allowed to use Yandex Cloud resources.

      • cookieMaxAge: Time before the browser asks the user to re-authenticate.

      • issuer: ID of the IdP server to use for authentication:

        • Keycloak 17 or higher

          http://<host>:8080/realms/master

          If you set up a public address for the IdP server, specify its URL. Here is an example:

          http://keycloak.example.com:8080/realms/master

        • Keycloak 16 or lower

          http://<host>:8080/auth/realms/master

          If you set up a public address for the IdP server, specify its URL.

          Here is an example:

          http://keycloak.example.com:8080/auth/realms/master

      • ssoUrl: URL of the page the browser has to redirect the user to for authentication:

        • Keycloak 17 or higher

          http://<host>:8080/realms/master/protocol/saml

          If you set up a public address for the IdP server, specify its URL. Here is an example:

          http://keycloak.example.com:8080/realms/master/protocol/saml

        • Keycloak 16 or lower

          http://<host>:8080/auth/realms/master/protocol/saml

          If you set up a public address for the IdP server, specify its URL. Here is an example:

          http://keycloak.example.com:8080/auth/realms/master/protocol/saml

        You can only use HTTP and HTTPS in a link.

      • encryptedAssertions: Flag enabling a digital signature for authentication requests. To complete the configuration, download and install a Yandex Cloud certificate.

      • forceAuthn: Parameter that requires user re-authentication once a session expires in Yandex Cloud.

      • ssoBinding: Specify the single sign-on binding type. Most identity providers support the POST binding type.

  2. To create a federation, use the create REST API method for the Federation resource or the FederationService/Create gRPC API call and provide a file with the query parameters in your query.

    Query example:

    curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <IAM_token>" \
  --data '@body.json' \
  https://organization-manager.api.cloud.yandex.net/organization-manager/v1/saml/federations

    Response example:

    {
 "done": true,
 "metadata": {
  "@type": "type.googleapis.com/yandex.cloud.organization-manager.v1.saml.CreateFederationMetadata",
  "federationId": "ajeobmje4dgj********"
 }

    The federationId property contains the ID of the federation you created. Save it for later use.

If you don't have Terraform, install it and configure the Yandex Cloud provider.

  1. Specify the federation parameters in the configuration file.

    Here is an example of the configuration file structure:

    • Keycloak 17 or higher

      resource "yandex_organizationmanager_saml_federation" federation {
name            = "my-federation"
organization_id = "<organization_ID>"
auto_create_account_on_login = "true"
issuer          = "http://<host>:8080/auth/realms/master"
sso_url         = "http://<host>:8080/auth/realms/master/protocol/saml"
sso_binding     = "POST"
security_settings {
    encrypted_assertions = "true"
    force_authn          = "true"
  }
}

    • Keycloak 16 or lower

      resource "yandex_organizationmanager_saml_federation" federation {
name            = "my-federation"
organization_id = "<organization_ID>"
auto_create_account_on_login = "true"
issuer          = "http://<host>:8080/realms/master"
sso_url         = "http://<host>:8080/realms/master/protocol/saml"
sso_binding     = "POST"
security_settings {
    encrypted_assertions = "true"
    force_authn          = "true"
  }
}

    Where:

    • name: Federation name. It must be unique within the folder.

    • description: Federation description.

    • organization_id: Organization ID.

    • labels: Set of key/value label pairs assigned to the federation.

    • issuer: ID of the IdP server to use for authentication:

      • Keycloak 17 or higher

        http://<host>:8080/realms/master

        If you set up a public address for the IdP server, specify its ID. Here is an example:

        http://keycloak.example.com:8080/realms/master

      • Keycloak 16 or lower

        http://<host>:8080/auth/realms/master

        If you set up a public address for the IdP server, specify its ID. Here is an example:

        http://keycloak.example.com:8080/auth/realms/master

    • sso_binding: Specify the single sign-on binding type. Most identity providers support the POST binding type.

    • sso_url: URL of the page the browser has to redirect the user to for authentication:

      • Keycloak 17 or higher

        http://<host>:8080/realms/master/protocol/saml

        If you set up a public address for the IdP server, specify its URL,

        Here is an example:

        http://keycloak.example.com:8080/realms/master/protocol/saml

      • Keycloak 16 or lower

        http://<host>:8080/auth/realms/master/protocol/saml

        If you set up a public address for the IdP server, specify its URL.

        Here is an example:

        http://keycloak.example.com:8080/auth/realms/master/protocol/saml

      You can only use HTTP and HTTPS in a link.

    • cookie_max_age: Time in seconds before the browser asks the user to re-authenticate. The default value is 8 hours.

    • auto_create_account_on_login: Flag enabling the automatic creation of new cloud users after authenticating on the IdP server.
      This option makes it easier to create users; however, users created this way will not be able to do anything with cloud resources. This does not apply to the resources for which roles are assigned to the All users or All authenticated users public group.

      If this option is off, users not added to the organization will not be able to log in to the management console, even if they authenticate on your server. In this case, you can manage a list of users allowed to use Yandex Cloud resources.

    • case_insensitive_name_ids: Toggles username case sensitivity.
      If this option is enabled, the IDs of federated user names will be case-insensitive.

    • security_settings: Federation security settings:

      • encrypted_assertions: Sign authentication requests.

        If this option is enabled, all authentication requests from Yandex Cloud will have a digital signature.

      • force-authn: When the Yandex Cloud session expires, your IdP will prompt the user to re-authenticate. This is an optional parameter.

    For more information about the yandex_organizationmanager_saml_federation resource parameters, see the provider documentation.

  2. Make sure the configuration files are correct.

    1. In the command line, go to the folder where you created the configuration file.

    2. Run a check using this command:

      terraform plan

      If the configuration is described correctly, the terminal displays the federation parameters. If the configuration contains any errors, Terraform will point them out.

  3. Create a federation.

    1. If the configuration does not contain any errors, run this command:

      terraform apply

    2. Confirm you want to create a federation.

This will create a federation in the specified organization. You can check the new federation and its settings in the organization's Federations section.

Add certificates

While authenticating, the Cloud Organization service should be able to verify the IdP server certificate. To enable this, 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 the federation you want to add a certificate to.

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

  5. Enter certificate name and description.

  6. Choose how to add a certificate:

    • To add a certificate as a file, click Choose a file and specify the path to it.
    • To paste the contents of a copied certificate, select the Text method and paste the contents.

  7. Click Add.

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

  1. View a description of the add certificate command:

    yc organization-manager federation saml certificate create --help

  2. Add a federation certificate by specifying the certificate file path:

    yc organization-manager federation saml certificate create \
  --federation-id <federation_ID> \
  --name "my-certificate" \
  --certificate-file certificate.cer

Use the create method for the Certificate resource:

  1. Create a request body. In the data property, specify the contents of the certificate:

    {
  "federationId": "<federation_ID>",
  "name": "my-certificate",
  "data": "-----BEGIN CERTIFICATE..."
}

  2. Send the request to add the certificate:

    export IAM_TOKEN=CggaAT********
curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --data '@body.json' \
  "https://organization-manager.api.cloud.yandex.net/organization-manager/v1/saml/certificates"

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.

Creating and setting up 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://keycloak.example.com:8080/admin. Replace keycloak.example.com with your local server address, e.g., http://localhost:8080/admin.

    http://keycloak.example.com:8080/auth/admin. Replace keycloak.example.com with your local server address, e.g., http://localhost:8080/auth/admin.

    The default login parameters are as follows:

    • User name or email: admin.
    • Password: Pa55w0rd.

  2. Create a SAML application:

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

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

      How to get a 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.

    3. In the Client type field, select saml.

    4. Click Save.

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

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

      How to get a 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.

    3. In the Client Protocol field, select saml.

    4. Click Save.

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

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

      • Home URL
      • Valid Redirect URIs
      • IDP Initiated SSO Relay State.
      • Valid Redirect URIs
      • Base URL
      • 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.

    2. Enable the following options:

      • Include AuthnStatement
      • Sign Assertions
      • Force POST Binding
      • Front Channel Logout.

    3. In the Signature Algorithm field, select RSA_SHA256.

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

    5. Select the format you need from the list in the Name ID Format field. To make sure this format is provided regardless of the Yandex Cloud Organization settings, enable the Force Name ID format option.

    6. Click Save.

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

    1. In the SAML application Keys tab, enable Encrypt Assertions and disable Client Signature Required.

    2. Select the Import method for Client Signature Required.

    3. In the Archive Format field, select Certificate PEM. (You may need to generate certificates first so that clicking Import key makes the Certificate PEM option available.)

    4. Click Browse and select the Yandex Cloud SAML certificate you downloaded earlier to sign authentication requests. If you did not download a SAML certificate, you can do this on the Yandex Cloud Organization federation info page by clicking Download certificate in the Sign authentication requests field.

    5. Click Confirm.

    1. In the SAML application settings, select Encrypt Assertions and Client Signature Required and save the application to update the available tabs.

    2. In the SAML application's Keys tab, locate the Signing Key and Encryption Key sections and click Import.

    3. In the Archive Format field, select Certificate PEM.

    4. Click Select file and select the Yandex Cloud SAML certificate you downloaded earlier to sign authentication requests. If you have not downloaded the 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.

    5. Click Import.

  5. Add users:

    1. In the left-hand panel, select Users.

    2. Click Add user and specify user data.

    3. Click Save.

    4. In the Credentials tab, click Set Password and enter a password.

Adding users to Yandex Cloud Organization

If you did not enable the Automatically create users option when creating the federation, you will have to add federated users to your organization manually.

To do this, you will need user name IDs. They are returned by the IdP server together with a response confirming successful authentication.

If the Automatically create users option is enabled, a federation will only add users logging in to a cloud for the first time. If a federated user has been removed, they can only be added again manually.

A user can be added by the organization administrator (the organization-manager.admin role) or owner (the organization-manager.organizations.owner role). To learn how to grant a role to a user, see Roles.

Note

To enable a user to access the management console, assign them a role for the cloud or organization. For added security, you can assign one of the least priveleged roles, such as resource-manager.clouds.member. However, you may also assign other roles if you know which permissions you want to grant to the invited users.

To grant these permissions to all the organization users at once, assign the role to the All users in organization X system group. When using the CLI or API, no additional roles are required.

  1. Go to Yandex Cloud Organization.

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

  3. In the top-right corner, click More and select Add federated users.

  4. Select the identity federation to add users from.

  5. List the name IDs of users, separating them with spaces or line breaks.

  6. Click Add. This will give the users access to the organization.

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

  1. View a description of the add user command:

    yc organization-manager federation saml add-user-accounts --help

  2. Add users by listing their name IDs separated by a comma:

    yc organization-manager federation saml add-user-accounts --id <federation_ID> \
  --name-ids=alice@example.com,bob@example.com,charlie@example.com

    Where:

    • --id: Federation ID.
    • --name-ids: Name IDs of users.

To add identity federation users to the cloud:

  1. Create a file with the request body, e.g., body.json. In the request body, specify the array of name IDs of users you want to add:

    {
  "nameIds": [
    "alice@example.com",
    "bob@example.com",
    "charlie@example.com"
  ]
}

  2. Send the request by specifying the federation ID in the parameters:

    curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <IAM_token>" \
  --data '@body.json' \
  https://organization-manager.api.cloud.yandex.net/organization-manager/v1/saml/federations/<federation_ID>:addUserAccounts

Setting up user attribute mappings

Following user authentication, the IdP server will send the user a SAML message via the browser containing:

  • Information about successful authentication.

  • User attributes such as a list of roles, the user's full name, and email address.

You can set up a mapping between the SAML message attributes and the personal data stored on the IdP server. To do this:

  1. Enable the option for mapping the identity provider roles and Yandex Cloud Organization:

    1. In the left-hand panel, select Client Scopes → role_list.

    2. Go to the Mappers tab and select role list.

    3. Enable the Single Role Attribute option.

  2. Set up the attributes to provide to Yandex Cloud:

    1. In the left-hand panel, select Client, open your SAML application settings, and go to role_list.

    2. In the Client Scopes tab, select optional next to role_list and click the line with the same name as your client.

    3. In the window that opens, click Add predefined mappers.

    4. Select the attributes you need in the list and click Add. The following user attributes are available in Keycloak by default:

      • X500 email: Email address.
      • X500 surname: Last name.
      • X500 givenName: First name.
      • role list: List of roles.

    5. You can create additional user attributes such as a phone number. To do this, click Add mappers -> By configuration -> User Property, select User Attribute in the Configure a new mapper table, and set attribute parameters.

    6. Sync Keycloak attributes and Yandex Cloud Organization: open an attribute and edit the SAML Attribute Name value. You can find the SAML Attribute Name values supported in Yandex Cloud Organization below.

    1. In the left-hand panel, select Clients and open your SAML application's settings.

    2. In the Mappers tab, click Add Builtins.

    3. Select the desired attributes in the list and click Add selected. The following user attributes are available in Keycloak by default:

      • X500 email: Email address.
      • X500 surname: Last name.
      • X500 givenName: First name.
      • role list: List of roles.

    4. You can create additional user attributes such as a phone number. To do this, click Create, select User Attribute in the Mapper Type field, and set attribute parameters.

    5. Sync Keycloak attributes and Yandex Cloud Organization: open an attribute and edit the SAML Attribute Name value. You can find the SAML Attribute Name values supported in Yandex Cloud Organization below.

  3. If you created additional attributes, add them to user parameters:

    1. In the left-hand panel, select Users, open the user parameters, and go to the Attributes tab.

    2. In the Key field, enter the Name given to the additional attribute.

    3. In the Value field, enter the user data to include in the attribute.

      Note

      By default, the Value field is limited to 256 characters. Attributes may contain more characters, for example, a Base64-encoded profile image. To add such a value, change the field data type in the user_attribute table in the internal Keycloak storage.

    4. Click Add and then click Save.

User data Comment SAML Attribute Name
Last name Used for search in Yandex Cloud services.
Value length limit: 64 characters.		 lastName
Name Used for search in Yandex Cloud services.
Value length limit: 64 characters.		 firstName
Full name Displayed in Yandex Cloud services.
Value length limit: 64 characters.		 name
Email Used to send notifications from Yandex Cloud services.
Example: ivanov@example.com.
Value length limit: 256 characters.		 email
Phone Used to send notifications from Yandex Cloud services.
Example: +71234567890.
Value length limit: 64 characters.		 phone
Profile image Displayed in Yandex Cloud services. The image must be provided in Base64 format.
Value length limit: 204800 characters.		 thumbnailPhoto
Group membership Used for dynamic mapping of group members. member

Warning

The thumbnailPhoto attribute value exceeding the length limit is ignored. If the value of a different attribute exceeds the limit, the value part that goes beyond the limit is truncated.

Attribute mapping example:

image

Authentication

When you finish setting up SSO, test that everything works properly:

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

    The browser will redirect you to the Keycloak authentication page.

  3. Enter your credentials 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. In the top-right corner, you will see being logged in to the console as a federated user.

Previous
Authentication using Microsoft Entra ID
Next
User group mapping in Active Directory Federation Services