User group mapping in Keycloak

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.

Getting startedGetting started

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://<Keycloak_IP_or_URL>:8080/admin.

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

      • URL: http://0.0.0.0:8080/admin.
      • 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 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 federationCreate a Yandex Cloud Organization federation

1. Go to Yandex Cloud Organization.

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

3. Click Create federation.

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

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

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

7. In the IdP Issuer field, enter a link of the form:

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

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

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

   You can only use HTTP and HTTPS in a link.

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

10. (Optional) To make sure that all authentication requests from Yandex Cloud contain a digital signature, enable Sign authentication requests.

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

12. Click Create federation.

13. (Optional) Download the certificate from the link in the Sign authentication requests field if you previously enabled the corresponding option. You will need this certificate later when setting up the client in Keycloak.

Add the Keycloak certificate to the federationAdd 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. In the left-hand panel, navigate to Federations and select the federation to add the certificate to: demo-federation.

2. At the bottom of the page, click Adding a certificate.

3. Enter a name for the certificate and specify the path to the keycloak-cert.cer file.

Create and configure a SAML application in KeycloakCreate 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://<Keycloak_IP_or_URL>:8080/admin.

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

   • URL: http://0.0.0.0:8080/admin.
   • 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 type field, select SAML.

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

      How to get the federation ID

      1. Go to Yandex Cloud Organization.

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

      3. Copy the ID of the federation you are configuring access for.

      How to get the federation ACS URL

      1. Go to Yandex Cloud Organization.

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

      3. From the list, pick the federation you are configuring access to, and copy its ACS URL.

   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. Go to Yandex Cloud Organization.

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

      3. From the list, pick the federation you are configuring access to, and copy its ACS URL.

   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 the Sign authentication requests option when creating a 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 certificate to use for signing authentication requests. The certificate is available on the Yandex Cloud Organization federation information page 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 to use for signing authentication requests. The certificate is available on the Yandex Cloud Organization federation information page in the Sign authentication requests field.
   9. Click Import.

Configure group mapping on the Keycloak sideConfigure 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. Go to Yandex Cloud Organization.

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

      3. From the list, pick the federation you are configuring access to, and copy its ACS URL.

   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 sideConfigure group mapping on the federation side

1. Create a user group named yc_demo_group in Yandex Cloud Organization and authorize it to view resources in the cloud or a separate folder (the viewer role).
2. In the left-hand panel, select Federations .
3. Select demo-federation you created previously and navigate to the IdP group tab.
4. Enable group mapping in the Mapping group in IdP field.
5. In the Group name field, enter the group name in Keycloak: kc_demo_group.
6. In the IAM group field, select the yc_demo_group group you created in Yandex Cloud Organization from the list.
7. Click Save.

Test authenticationTest 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. Go to Yandex Cloud Organization.

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

   3. Copy the ID of the federation you are configuring access for.

   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 user belongs to yc-demo-group and has the viewer permissions for resources according to the role assigned to the group.