1. Kion Success Center
  2. Integrations
  3. General Integrations

Keycloak Integration

Follow

Last updated

Keycloak Integration

Kion integrates with Keycloak as a SAML 2.0 provider. This integration allows users to access Kion using familiar logins and consolidates user management.

This guide details both encrypted and unecrypted assertion options and was built against Keycloak v16.1.1.

Configuration

1. Obtaining Information from Kion

  1. Login to Kion as an administrator.
  2. Navigate to Users > Identity Management Systems.
  3. Click Add New.
  4. Select SAML 2.0 as the IDMS Type.
  5. Enter a name for the IDMS. Users see this name when selecting the IDMS on the Kion login page.
  6. Copy the following values to a text file. They will be used to configure Keycloak.
    • Service Provider Issuer (Entity ID)
    • Service Provider ACS URL

2. Obtaining Information from Keycloak

  1. On a separate browser tab, log in to Keycloak.
  2. Choose the Realm where you plan to install the Kion SSO Client. This defaults to the master realm.
  3. Navigate to Realm Settings.
  4. Click SAML 2.0 Identity Provider Metadata.
  5. Copy the Keycloak metadata to a text file. It will be used to configure Kion.

3. Configuring Kion

  1. Return to the new IDMS configuration you started to create in Kion.
  2. Paste the Keycloak metadata into the Identity Provider Metadata field.
  3. Locate and copy the entityID in the keycloak metadata. The format should follow https://<YOUR-KEYCLOAK-URL>/auth/realm/<REALM-NAME>.
  4. Paste the entityID in the Identity Provider Issuer (Entitiy ID) field.
  5. In the Name ID Format field, enter urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
  6. For the Assertion Mapping First Name, enter urn:oid:2.5.4.42
  7. For the Assertion Mapping Last Name, enter urn:oid:2.5.4.4
  8. For the Assertion Mapping Email, enter urn:oid:1.2.840.113549.1.9.1
  9. For the Assertion Mapping Username, enter urn:oid:1.2.840.113549.1.9.1
  10. (Optional) Upload the Keycloak logo for the Service Provider Icon. Users see this image when selecting the IDMS on the Kion login page.
  11. Click Create IDMS.
  12. On the IDMS details page, click the ellipsis menu and select Download Metadata. This downloads the Kion metadata for configuring Keycloak.

4. Configuring Keycloak

  1. Return to Keycloak, ensuring you are in the same realm that you selected earlier.
  2. Navigate to Clients.
  3. Click Create.
  4. Import the Kion metadata file you downloaded earlier. This populates the Client ID and the Protocol Type (SAML).
  5. In the Client SAML Endpoint field, paste the Service Provider ACS URL you obtained from Kion.
  6. By default, this uses encrypted SAML assertions and the Kion service provider certificate is added automatically. If you prefer to use unencrypted assertions, disable the Encrypt Assertions option and delete the certificate from the Keys tab.
  7. Select the Settings tab.
  8. Disable the following options:
    • Sign Assertions
    • Client Signature Required
    • Force Name ID Format
  9. Save your configuration.

Testing

  1. Open an incognito session in your browser.
  2. Go to the login page for your instance of Kion.
  3. Click the button for the Keycloak IDMS you just created.
  4. Authenticate with Keycloak to log in to Kion.
  5. By default, the built-in Keycloak administrator user doesn't have a first name, last name, or email address configured. We recommend either configuring those fields beforehand or using a different user in this test.
  6. In Kion, click the display name initials in the top-right corner, and select My Profile.
  7. Verify the first name, last name, email, and username are as expected.

(Optional) Editing Assertion Mappings

Assertion mappings are the names of the SAML assertions that Kion uses to populate user records. We recommend configuring the First Name, Last Name, Email, and Username fields to be more user friendly.

In Kion:

  1. Navigate to Users > Identity Management Systems.
  2. Click the ellipsis menu next to your Keycloak IDMS and select Edit IDMS.
  3. For the Assertion Mapping First Name, enter givenName
  4. For the Assertion Mapping Last Name, enter surname
  5. For the Assertion Mapping Email, enter email
  6. For the Assertion Mapping Username, enter email
  7. Click Save.

In Keycloak:

  1. Navigate to Clients.
  2. Select the configuration you created for Kion.
  3. Select the Mappers tab.
  4. Click Add Builtin.
  5. Select X500 email, role list, X500 givenName, and X500 Surname.
  6. Click Add Selected.
  7. Edit the SAML attribute name of the X500 givenName mapper to be givenName.
  8. Edit the SAML attribute name of the X500 Surname mapper to be surname.
  9. Edit the SAML attribute name of the X500 email mapper to be email.
  10. Save your changes.