Skip to main content

Create a SAML federation for Keycloak

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

1. Issue a certificate

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

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 Servercore 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 the mapping. If you enable automatic user 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 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.servercore.com/v1/federations/saml/<federation_id>.

    Specify <federation_id> — the federation ID on the Servercore 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, insert https://api.servercore.com/v1/federations/saml/<federation_id>.

    Specify <federation_id> — the federation ID on the Servercore 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, insert https://my.servercore.com/federated-login.

    5.3. In the Valid Redirect URIs field, insert https://api.servercore.com/v1/auth/federations/<federation_id>/saml/acs.

    Specify <federation_id> — the federation ID on the Servercore 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 ID 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, ensure that the Client signature required toggle is disabled 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

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

  1. Download the Servercore certificate to sign requests.

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

  3. Open the SAML application page → in the 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 on the federation page in Servercore.

    4.6. Click Confirm.

5. Configure user group mapping

Group mapping must be configured if you enabled automatic user creation during federation creation on the Servercore side in step 2. Use the Configure group mapping subsection of the User group mapping guide.