Step-by-Step SAML Integration with Liferay and Keycloak

Issue

Is Keycloak supported with Liferay? If yes, how can SAML be configured with Liferay?

Environment

Lifeary DXP [All versions]

Resolution

As per Liferay’s official compatibility matrix, Keycloak is not listed as a supported Identity Provider (IdP), as it has not been explicitly tested or certified by Liferay.
However, since Keycloak supports the SAML 2.0 protocol, it should work with Liferay’s SAML module. That said, using Keycloak is technically possible but should be done at the user's own discretion, as it is not officially tested by Liferay.
For best practice, please always test this in a lower environment first and proceed accordingly.
Steps to set up Keycloak as SSO:
1. Configure Keycloak Client:
  1. Log into the Keycloak Admin Console.
  2. Navigate to Clients and click Create client.
  3. Select SAML as the Client type.
  4. Enter the following values:
    1. Client ID: LiferaySaml
    2. Name: Liferay Saml
    3. Description: (leave blank)
  5. Click Next.
  6. Enter the following values:
    (Ensure ports match your Liferay instance—here using 8081 port)
    1. Root URL: http://localhost:8081/
    2. Home URL: http://localhost:8081/
    3. Valid Redirect URI: http://localhost:8081/*
    4. Leave other fields blank.
    5. Master SAML Processing URL: http://localhost:8081/
  7. Click Save.
2. Export the Certificate:
  1. Go to Clients > Liferay Saml > Keys.
  2. Click Export and choose:
    1. Archive format: PKCS12
    2. Key alias: liferay
    3. Key password: liferay
    4. Realm certificate alias: master
    5. Store password: liferay
  3. Click Export and save the file locally.
3. Navigate to Users > "test" user:
  1. Enter the following values in the respective fields:
    1. Username: Already filled as "test"
    2. Email: test@liferay.com
    3. First Name: test
    4. Last Name: test
  2. Click Save to apply the changes.
4. Configure Liferay as a SAML Service Provider:
  1. Start the Liferay bundle.
    1. Go to Control Panel > Security > SAML Admin.
    2. Under Entity ID, enter: LiferaySaml (same as Client ID).
    3. Click Save.
    4. Click Create Certificate, then go to Import Certificate.
      1. Upload the .p12 file exported from Keycloak.
      2. Keystore Password: liferay (as defined earlier).
      3. Select the “Liferay” entry from the list and click Import.
5. Add Identity Provider in Liferay:
  1. Go to Identity Provider Connections > Add Identity Provider.
  2. Fill the fields as follows:
    1. Name: Keycloak-idp
    2. Entity ID: http://localhost:8080/realms/master
    3. Enabled: ✅
    4. Force Authn: ✅
    5. Metadata URL: http://localhost:8080/realms/master/protocol/saml/descriptor
      (Found in Keycloak > Realm Settings > SAML 2.0 Identity Provider Metadata)
    6. User Resolution: Match a User Field Chosen Dynamically Based on Name ID Format
  3. Under Attribute Mapping, enter:
    1. firstName = firstName
    2. lastName = lastName
    3. emailAddress = email
    4. screenName = username
  4. Click Save.
6. Final Steps:
  1. Go back to the General tab and enable SAML. Save the configuration.
  2. Important: Deploy the “Sign In” widget on the page before logging out to ensure manual access if any configuration fails.
  3. Log out from Liferay.
  4. Click Sign In—it redirects to the Keycloak login page.
    1. Username: test
    2. Password: test
  5. After successful authentication, it will be redirected back and logged into Liferay.

Additional Information

SAML Authentication Process Overview