User group mapping in Keycloak
To configure user group mapping in Keycloak
- Create a federation in Yandex Cloud Organization.
- Add a Keycloak certificate to the federation
- Create and configure a SAML application in Keycloak.
- Configure group mapping on the Keycloak side
- Configure group mapping on the federation side.
- 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.
-
Set up a local Keycloak server for testing:
-
If you do not have Docker yet, install it
. Make sure Docker Engine is running. -
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
. -
-
Get the certificate used for signing in Keycloak:
-
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:
- URL: http://0.0.0.0:8080/admin
. - User name or email:
admin
. - Password:
Pa55w0rd
.
- URL: http://0.0.0.0:8080/admin
-
In the Realm Settings section, select the Keys tab.
-
In the RS256 line, click Certificate and copy the certificate value.
-
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
-
Go to Yandex Cloud Organization
. -
In the left-hand panel, select
Federations. -
Click
Create federation in the top-right corner of the page. In the window that opens:-
Enter a name for the federation, e.g.,
demo-federation
. It must be unique within the folder. -
You can also add a description, if required.
-
In the Cookie lifetime field, specify the time before the browser asks the user to re-authenticate.
-
In the IdP Issuer field, enter a link of the form:
http://<Keycloak_IP_or_URL>:8080/realms/master
-
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.
-
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.
-
(Optional) To make sure that all authentication requests from Yandex Cloud contain a digital signature, enable Sign authentication requests.
-
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. -
Click Create federation.
-
-
(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 federation
To make sure that Cloud Organization can verify the Keycloak server certificate during authentication, add the certificate to the federation:
-
Log in to Yandex Cloud Organization
. -
In the left-hand panel, select
Federations. -
Click the row with the federation you need to add a certificate for:
demo-federation
. -
At the bottom of the page, click Adding a certificate under Certificates.
-
Enter a name for the certificate and specify the path to the
keycloak-cert.cer
file. -
Click Add.
Tip
To ensure the authentication is not interrupted when the certificate expires, add multiple certificates to the federation, i.e., both the current one and those to use afterwards. If one certificate goes invalid, Yandex Cloud will try another one to verify the signature.
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:
-
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:
- URL: http://0.0.0.0:8080/admin
. - User name or email:
admin
. - Password:
Pa55w0rd
.
- URL: http://0.0.0.0:8080/admin
-
Create a SAML application:
-
In the left-hand panel, select Clients. Click Create client.
-
In the Client type field, select SAML.
-
In the Client ID field, enter the ACS URL to redirect users to after successful authentication.
How to get the federation ID
-
Log in to Yandex Cloud Organization
. -
In the left-hand panel, select
Federations. -
Select the required federation and copy the Identifier field value on the federation info page.
How to get the federation ACS URL
-
Log in to Yandex Cloud Organization
. -
In the left-hand panel, select
Federations. -
Select the required federation and copy the ACS URL field value on the federation info page.
-
-
Click Next.
-
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
-
Log in to Yandex Cloud Organization
. -
In the left-hand panel, select
Federations. -
Select the required federation and copy the ACS URL field value on the federation info page.
-
Click Save.
-
-
Set up the SAML application parameters in the Settings tab:
-
Enable the following options:
- Include AuthnStatement
- Sign Assertions
- Force name ID format
- Force POST Binding
- Front Channel Logout
-
In the Signature Algorithm field, select RSA_SHA256.
-
In the SAML Signature Key Name field, select CERT_SUBJECT.
-
Select
username
as Name ID Format. -
Click Save.
-
-
(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:
- On the Keys tab of the SAML application, check that the Client Signature Required option is enabled.
- Click the Import key button under the automatically generated certificate and select Certificate PEM in the Archive Format field.
- 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.
- Click Import.
- Enable the Encrypt Assertions option.
- In the window that opens, select the Generate method and click Confirm.
- Click Import key under the generated certificate and select Certificate PEM in the Archive Format field.
- 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.
- Click Import.
Configure group mapping on the Keycloak side
-
Create a user:
- In the left-hand panel, select Users.
- Click Add user and enter a username, e.g.,
demo_user1
. - Click Create.
- In the Credentials tab, click Set Password and enter a password. For easier testing, disable the Temporary option.
-
Create a group and add a user to it:
- In the left-hand panel, select Groups.
- Click Create group and enter a name for the group, e.g.,
kc_demo_group
. - Click the group name, click Add member on the Members tab, and add the
demo_user1
user from the list to the group.
-
Add a mapper to the Keycloak application:
-
In the left-hand panel, select Clients and select the previously created application from the list.
-
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
-
Log in to Yandex Cloud Organization
. -
In the left-hand panel, select
Federations. -
Select the required federation and copy the ACS URL field value on the federation info page.
-
-
On the Mappers tab, click Configure a new mapper. Select Group list from the drop-down list.
-
Specify the following mapper settings:
- Name:
group_mapper
- Group attribute name:
member
- SAML Attribute NameFormat:
Basic
- Single Group Attribute:
On
- Full group path:
Off
- Name:
-
Click Save.
-
Configure group mapping on the federation side
-
Log in to Yandex Cloud Organization
. -
Create a user group named
yc_demo_group
in Cloud Organization and authorize it to view resources in the cloud or a separate folder (theviewer
role). -
In the left-hand panel, select
Federations. -
Select
demo-federation
you created previously and navigate to the IdP group tab. -
Enable Mapping group in IdP.
-
Click Add.
-
In the Group name field, enter the group name in Keycloak:
kc_demo_group
. -
In the IAM group field, select the
yc_demo_group
group you created in Yandex Cloud Organization from the list. -
Click Save.
Test authentication
-
Open your browser in guest or private browsing mode.
-
Use this URL to log in to the management console:
https://console.yandex.cloud/federations/<federation_ID>
How to get the federation ID
-
Log in to Yandex Cloud Organization
. -
In the left-hand panel, select
Federations. -
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.
-
-
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. -
Make sure the created
demo_user1
user belongs toyc-demo-group
and has the viewer permissions for resources according to the role assigned to the group.