Configuring Keycloak for SSO in FHR Merchandising Studio

Learn how to configure Keycloak as an Identity Broker for SSO in Fredhopper. This step-by-step guide covers IdP setup, token flow, and access control for seamless aut

If you would like to start using SSO for your Fredhopper server, reach out to Customer Support or your Crownpeak CSM.

For access rights management, the Fredhopper Merchandising Studio uses the open source software Keycloak. Keycloak is a single sign-on (SSO) solution for web applications and RESTful web services.

When a user logs in to the Fredhopper Merchandising Studio, Keycloak redirects them to the external Identity Provider (IdP). An Identity Provider (IdP) stores and verifies user identities. After a successful authentication by the IdP, the IdP sends an identity token back to Keycloak. Keycloak then maps the user information from the IdP to a Keycloak user session and issues its own token. Then, the Keycloak server sends an identity token to the Fredhopper server, containing all the required information (user ID, group, validity period). This gives a user access to the required areas.

Note that Keycloak functions as an Identity Broker only in this set-up. Regular user management actions, such as user creation, are therefore not performed in Keycloak.

Configuring an Identity Provider (IdP) in Keycloak

For more information on the role of Keycloak as an Identity Broker see Keycloak Documentation.

To enable SSO for your Fredhopper instance, you have to configure your IdP in Keycloak. Keycloak offers a list of IdPs to integrate with.

To configure your IdP in Keycloak:

• You will receive temporary admin credentials from Crownpeak.

• Log into Keycloak with the admin credentials provided to you.

The URl used to access Keycloak will be of the following format: https://iam.global.fredhopperservices.com/admin/<provided-realm-name>/console/

• Reset your password.

• (Optional) Create additional users to manage your Keycloak realm.

• In Keycloak, navigate to Identity Providers.

• Click Add provider.

• Choose a provider from the list.

• Fill in the required fields based on Keycloak's and your IdP provider's documentation.

A valid client or application is required in the chosen IdP system with proper URl and permissions.

You can find instructions on where to retrieve the required information and for the configuration in Keycloak for Microsoft Entra ID here.

• Notify your Crownpeak Contact once your configuration is complete, so they can verify and finalize the integration.

Configuring Microsoft Entra ID

If you want to configure Microsoft Entra ID as your IdP the following information is required:

• Redirect URl (provided by Crownpeak)

• Client ID

• Client Secret

In Microsoft Entra ID:

• Register a new application in Microsoft Entra ID:

  • In Microsoft Entra ID, navigate to App registrations > New registration.

  • Provide a descriptive name, e.g. "Fredhopper SSO Integration".

  • Set Supported account types appropriately (typically "Accounts in this organizational directory only").

  • Enable "ID tokens" in "Implicit grant and hybrid flows."

Once you have received the Redirect URI from Crownpeak, you must add it here in the "Authentication" section of your App Registration. It will be of the following format: https://<fredhopper_sso_domain>/realms/<your_realm_name>/broker/microsoft/endpoint

• Copy the Record Application (client) ID from the App Registration's "Overview" page.

• Navigate to Certificates & secrets and click + New client secret.

Copy the Value of the Client Secret immediately as you won't be able to return to it.

• To configure API permissions:

  • Navigate to API permissions > Add a permission > Microsoft Graph > Delegated permissions.

  • Add openid, profile, and email and grant admin consent.

• To configure user assignment for access control, which will allow you to control the subset of users:

  • Navigate to Microsoft Entra ID > Enterprise applications.

  • Select your newly registered application.

  • Navigate to Properties and set "User assignment required?" to Yes.

  • Navigate to Users and groups and Add user/group. Select only the specific users or groups from your Entra ID that should be allowed to log in via Keycloak.

In Keycloak:

• Navigate to Identity Providers, click Add Provider, and choose “Microsoft Entra”.

• Insert the Redirect URl, Alias, Client ID, and Client Secret.

• Set Trust Email to True.

• Set First login flow override to First broker login.

• Set Sync mode to Import.

• Click Save.

Configuring a generic OIDC provider

To configure a generic OIDC provider, you need the following:

• Redirect URl (provided by Crownpeak)

• Discovery endpoint

• Authorization URl

• Token URl

• Client ID

• Client Secret

In your external OIDC IdP:

• Register Keycloak as a new OIDC client.

• Add the redirect URl provided by Crownpeak.

• Retrieve the require information.

For more information consult the Keycloak documentation on OIDC IdPs as well as your OIDC provider's documentation.

Configuring a SAML v2.0 provider

To configure a SAML v2.0 provider, you need the following:

• Redirect URl (provided by Crownpeak)

• Service provider entity ID

• SAML entity descriptor

• Single Sign-On service URL

In the SAML IdP:

• Register Keycloak as a SAML SP.

• Configure ASC (Assertion Consumer Service) URL.

• Set the Entity ID.

• Configure the NameID format.

• Export the IdP metadata XML.

For more information consult the Keycloak documentation on SAML IdPs as well as your SAML provider's documentation.