Skip to main content

Create a SAML federation for Keycloak

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

1. Issue a certificate

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

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

2. Create a federation on the Selectel side

  1. In the control panel, on 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.

    Время жизни сессии также можно установить on стороне провайдера Keycloak in параметре SSO Session Max or Assertion Lifespan. Если время жизни сессии установлено and in настройках федерации, and in Keycloak, будет применяться наименьшее значение.

  5. In the IdP settings block:

    5.1. In the IdP Issuer field, enter the identity provider identifier — props.IdIssuer.

    Specify <idp_url> — your identity provider URL.

    5.2. Specify the link to the identity provider login page, where users will be redirected to authenticate through SSO — props.Link.

    Specify <idp_url> — your identity provider URL.

    5.3. To have users created automatically upon their first login to the control panel via SSO, select the Auto-create users 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 auto-creation of users and do not configure mapping, users will be created without permissions and will not have access to the control panel.

    If you do not select the Auto-create users checkbox, users will need to be added manually.

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

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

  6. Click Continue. You will be redirected to the Add Certificate 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 the Clients section.

  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 to which users will be redirected after authentication — https://api.selectel.ru/v1/federations/saml/<federation_id>.

    Specify <federation_id> — the ID of the federation on the Selectel side, which can be found 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 ID of the federation on the Selectel side, which can be found 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 ID of the federation on the Selectel side, which can be found 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 identifier format — username or email.

    6.2. Enable the Force POST binding and Include AuthnStatement toggles.

  7. At the Signature and Encryption step:

    7.1. Enable the Sign assertions toggle.

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

    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. Enable the Front channel logout toggle.

    8.2. Click Save.

4. Configure digital signature verification

You need to configure digital signature verification if you checked the Sign authentication requests box when creating a federation on the Selectel side at step 2 on step 5.2.

  1. Download the Selectel certificate for request signing.

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

  3. Open the SAML application page → Keys tab.

  4. At the Signature and Encryption step:

    4.1. In the Signing keys config block, enable the Encrypt Assertions and Client signature required toggles.

    4.2. In the Encryption keys config block, enable 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 from the federation page in Selectel.

    4.6. Click Confirm.

5. Configure user group mapping

You need to configure group mapping if you enabled user auto-creation when creating a federation on the Selectel side at step 2. Use the Configure group mapping subsection of the User group mapping guide.