Keycloak SAML Setup

Keycloak is an open-source identity and access management solution supporting user federation, OAuth, SAML, and OpenID Connect protocols. The below instructions explain how to configure Keycloak with Jmix application using SAML for users to log in with their Keycloak credentials.

The instructions were tested with Keycloak 26.5.6. Other, and particularly older, Keycloak versions may use different labels and place certain settings in different locations in the admin console, but the underlying SAML configuration should be the same.

Prerequisites

  • A Jmix application available at stable URL (e.g., https://jmix-app.com). This guide references the application URL using the placeholder <your-app-url>.

  • A Keycloak server (e.g., https://keycloak.test.com) that you have administrative access to. This guide references the server using the placeholder your-keycloak-server.

  • A Keycloak realm (e.g., master). This guide references the realm using the placeholder your-realm.

Configure Jmix Application

In your Jmix application:

  1. Install the add-on.

  2. Configure the application as a SAML service provider using Spring Security properties:

    application.properties
    spring.security.saml2.relyingparty.registration.keycloak.entity-id=https://<your-app-url>/saml/sp
spring.security.saml2.relyingparty.registration.keycloak.acs.location={baseUrl}/login/saml2/sso/keycloak
spring.security.saml2.relyingparty.registration.keycloak.assertingparty.metadata-uri=https://<your-keycloak-server>/realms/<your-realm>/protocol/saml/descriptor
spring.security.saml2.relyingparty.registration.keycloak.singlelogout.url={baseUrl}/logout/saml2/slo
spring.security.saml2.relyingparty.registration.keycloak.singlelogout.response-url={baseUrl}/logout/saml2/slo
spring.security.saml2.relyingparty.registration.keycloak.singlelogout.binding=redirect
keycloak in the property key is the provider ID. It can be any value.

The {baseUrl} placeholder is resolved by Spring Security at runtime. In Keycloak settings, use the actual application URL instead, for example https://jmix-app.com.

The entity-id value must be equal to the Keycloak Client ID. The assertingparty.metadata-uri property points to the Keycloak realm descriptor and allows the application to read the IdP entity ID, SSO/SLO endpoints, and the signature verification certificate on startup.

Both singlelogout.url and singlelogout.response-url point to the SLO endpoint of the Jmix application. The singlelogout.binding=redirect setting matches the default jmix.saml.force-redirect-binding-logout=true behavior and allows Spring Security to accept redirect-binding logout responses from Keycloak.

Configure Keycloak Client

In Keycloak, create or select the realm that will manage authentication for your Jmix application.

  1. Select or create the realm that will manage authentication for your Jmix application.

  2. In the realm, create a new client with these values:

    • Client type: SAML.

    • Client ID: https://<your-app-url>/saml/sp (the same value as entity-id property).

    • Root URL: your application base URL, for example https://jmix-app.com.

    • Master SAML Processing URL: https://<your-app-url>/login/saml2/sso/keycloak, the same endpoint as acs.location.

    • Valid redirect URIs: your allowed redirect patterns. Make sure they include the assertion consumer service URL, for example https://jmix-app.com/login/saml2/sso/keycloak.

    • Valid post logout redirect URIs: your allowed logout redirect patterns, for example https://jmix-app.com/*.

  3. In the Fine Grain SAML Endpoint Configuration section, set Logout Service Redirect Binding URL to https://<your-app-url>/logout/saml2/slo.

These values connect the Keycloak client to the Jmix service provider configuration from the previous step.

Configure User Access to the Application

Use Keycloak roles and user role mappings to control which users receive access and which Jmix roles they get.

Create Roles

Create roles that your users should receive:

  1. Go to Realm roles and create a new role.

  2. Provide the Role name. If you use the default Jmix role mapping it should match the Jmix role code, for example system-full-access.

Create and Configure Users

Create a Keycloak user:

  1. Go to Users and create a new user.

  2. Select the created user and go to the Credentials tab to set a password.

  3. Go to the Role Mapping tab to assign the realm roles created previously.

(Optional) Add SAML Attributes

This step only adds attributes to the SAML assertion. The application will not use them automatically. To fill application user attributes from these values, you must also configure attribute mapping in the application.

If you need to include any extra SAML attributes, add them in Keycloak as follows:

  1. Go to your Client → Client Scopes → https://<your-app-url>/saml/sp-dedicated → Configure a new mapper.

  2. Select appropriate mapper type. For built-in properties, (such as email, firstName, lastName) select User Property and provide values:

    • Name: descriptive mapper name, such as FirstName mapper

    • Property: property name within IdP: firstName

    • SAML Attribute Name: attribute name in the SAML Assertion: FirstName

Follow the same steps to add more attributes.

Configure Signing and Certificates

To enable signing you will need a public and a private keys. You can generate them manualy via openssl and then import to IdP. You can also generate those using Keycloak:

  1. Go to your Client and open the Keys tab.

  2. Enable Client signature required.

  3. Generate new key and export it as pkcs12 keystore. Make note of the store password you set.

  4. Extract the private key and certificate:

    openssl pkcs12 -in keystore.p12 -nodes -nocerts -out private.key -passin pass:<STORE_PASSWORD>
openssl pkcs12 -in keystore.p12 -nodes -nokeys -out public.crt -passin pass:<STORE_PASSWORD>

    If extraction fails, add the -legacy parameter to both commands. In this case you will also need to convert extracted private key to pkcs8 format:

    openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private.key -out private-pkcs8.key

  5. Place the files somewhere accessible to the application, such as src/main/resources, and add them through properties. The application uses this key pair to sign outgoing AuthnRequest and LogoutRequest messages:

    application.properties
    spring.security.saml2.relyingparty.registration.keycloak.signing.credentials[0].private-key-location=classpath:private-pkcs8.key
spring.security.saml2.relyingparty.registration.keycloak.signing.credentials[0].certificate-location=classpath:public.crt

Specify a Signing Algorithm

If a specific signing algorithm is required, configure it explicitly:

application.properties
spring.security.saml2.relyingparty.registration.keycloak.signing.credentials[0].algorithm=http://www.w3.org/2001/04/xmldsig-more#rsa-sha256

(Optional) Provide Verification Certificate

The IdP signature verification certificate is usually read from the assertingparty.metadata-uri descriptor. Provide it manually only when metadata is not available, or you need to override the certificate. To provide a certificate:

  1. Open the Keycloak metadata descriptor at https://<your-keycloak-server>/realms/<your-realm>/protocol/saml/descriptor

  2. Copy the value of X509Certificate.

  3. Save it to a file such as keycloak-signing.crt using this format:

    -----BEGIN CERTIFICATE-----
<value>
-----END CERTIFICATE-----

  4. Place the file somewhere accessible to the application, such as src/main/resources, and add it through the property:

    application.properties
    spring.security.saml2.relyingparty.registration.keycloak.assertingparty.verification.credentials[0].certificate-location=classpath:keycloak-signing.crt

Test the Connection

After the application and Keycloak are configured, start the application and test the SSO flow.

Validate that:

  • The user is redirected to the Keycloak login page.

  • Authentication succeeds.

  • Expected attributes are present in the SAML assertion.

  • Expected roles are granted in the application.

  • Logout works correctly, if SLO is configured.