Skip to main content

Create a SAML federation for Keycloak

  1. If you do not have a certificate issued by Keycloak, issue it.
  2. Create a federation on the Selectel side.
  3. Configure the SAML application.
  4. If you checked the Sign authentication requests checkbox when creating the federation on the Selectel side, configure digital signature verification.
  5. If you enabled automatic user creation when creating the federation on the Selectel side, configure user group mapping.

1. Issue a certificate

Issue a certificate on the Keycloak side; for details, see the Certificates instructions.

You can create a federation without a certificate and add it later, but without a certificate, the federation will not work.

2. Create a federation on the Selectel side

  1. In the control panel, in the top menu, click IAM.

  2. Go to the Federations section.

  3. Click Add federation and select SAML.

  4. In the Federation settings block:

    4.1. Enter the federation name.

    4.2. Optional: enter a description of the federation.

    4.3. Change the session lifetime or leave the default value (24 hours). The session defines the time during which a user will be authorized without needing to re-authenticate. You can specify a value from 1 to 720 hours.

    The session lifespan can also be set on the Keycloak provider side in the SSO Session Max or Assertion Lifespan parameter. If the session lifespan is set in both the federation settings and Keycloak, the lowest value will apply.

  5. In the IdP settings block:

    5.1. In the IdP Issuer field, enter the identity provider identifier — https://<idp_url>/realms/master.

    Specify <idp_url> — your identity provider URL.

    5.2. Specify the link to the identity provider login page where users will be redirected for SSO authentication — https://<idp_url>/realms/master/protocol/saml.

    Specify <idp_url> — your identity provider URL.

    5.3. To create users automatically upon their first login to the control panel via SSO, select the User auto-creation checkbox.

    If the checkbox is selected, you will need to configure user group mapping. Users will be created with the permissions you specify when configuring mapping. If you enable user auto-creation without configuring mapping, users will be created without permissions and will not have access to the control panel.

    If you do not select the User auto-creation checkbox, you will need to add users manually.

    5.4. Optional: to sign authentication requests, select the Sign authentication requests checkbox.

    5.5. Optional: to require users to authenticate via SSO on every login, select the Force authentication in IdP checkbox. If you do not select the checkbox, users will not need to authenticate as long as cookies are active.

  6. Click Continue. You will be redirected to the certificate addition page.

  7. Enter the certificate name.

  8. Paste the certificate that you issued in step 1. It must start with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE-----.

  9. Click Add certificate → Finish adding federation.

3. Configure the SAML application

  1. In the Keycloak control panel, log in to the administrator account (Administration Console).

  2. Go to Clients.

  3. Click Create client.

  4. At the General Settings step:

    4.1. In the Client type field, select SAML.

    4.2. In the Client ID field, enter the URL where users will be redirected after authentication: https://api.selectel.ru/v1/federations/saml/<federation_id>.

    Specify <federation_id> — the federation ID on the Selectel side, which can be viewed in the control panel: in the top menu, click IAM → Federations → federation row → ID field.

    4.3. In the Name field, enter the name of the SAML application.

    4.4. Click Next.

  5. At the Login Settings step:

    5.1. In the Root URL field, paste https://api.selectel.ru/v1/federations/saml/<federation_id>.

    Specify <federation_id> — the federation ID on the Selectel side, which can be viewed in the control panel: in the top menu, click IAM → Federations → federation row → ID field.

    5.2. In the Home URL field, paste https://my.selectel.ru/federated-login.

    5.3. In the Valid Redirect URIs field, paste https://api.selectel.ru/v1/auth/federations/<federation_id>/saml/acs.

    Specify <federation_id> — the federation ID on the Selectel side, which can be viewed in the control panel: in the top menu, click IAM → Federations → federation row → ID field.

    5.4. Click Save.

  6. At the SAML capabilities step:

    6.1. In the Name ID Format field, select the user ID format: username or email.

    6.2. Turn on the Force POST binding and Include AuthnStatement toggles.

  7. At the Signature and Encryption step:

    7.1. Turn on the Sign assertions toggle.

    7.2. If you do not plan to configure digital signature verification, make sure that in the Signing keys config section, the Client signature required toggle is turned off.

    7.3. In the Signature algorithm field, select RSA_SHA256.

    7.4. In the SAML Signature Key Name field, select NONE.

  8. At the Logout settings step:

    8.1. Turn on the Front channel logout toggle.

    8.2. Click Save.

4. Configure digital signature verification

Digital signature verification must be configured if when creating the federation on the Selectel side at step 2 you checked the Sign authentication requests checkbox in step 5.2.

  1. Download the Selectel certificate for signing requests.

  2. In the Keycloak control panel, go to Clients.

  3. Open the SAML application page → Keys tab.

  4. At the Signature and Encryption step:

    4.1. In the Signing keys config section, turn on the Encrypt Assertions and Client signature required toggles.

    4.2. In the Encryption keys config section, turn on the Client Signature Required toggle.

    4.3. In the Select method field, select Import.

    4.4. In the Archive Format field, select Certificate PEM. If the Certificate PEM option is missing, close the window, click Regenerate → Yes → Import key. The option will appear in the list.

    4.5. Click Browse and select the certificate you downloaded on the federation page in Selectel.

    4.6. Click Confirm.

5. Configure user group mapping

Configuring group mapping is necessary if you enabled automatic user creation when creating the federation on the Selectel side at step 2. Use the Configure group mapping section of the User group mapping instructions.