Keycloak SAML2 SSO

Introduction

Connect Flexopus with Keycloak via a SAML2 for single sign on (SSO). With the integration, you can manage through your KeyCloak Directory which users should have access to Flexopus and force them to use their KeyCloak credentials for the login. Based on a SAML2 settings in Flexopus you can let the user profiles be created after the first successful SAML2 SSO login attempt to avoid a manual user creation process at Flexopus.

Setup Instruction Manual

Follow the step by step introduction manual to configure the integration. The manual also includes best practices and solution for some commonly made errors during the configuration. Still, if you need help with the setup, feel free to reach out to our support team via support@flexopus.com.

STEP 1 - Create SAML2 app

Go to your KeyCloak admin console and navigate to Clients > Create.

On this page, enter the Client ID, Client protocol, and Client SAML Endpoint. These configuration parameters are found in Flexopus. Navigate in Flexopus as an administrator to Dashboard > Settings > Authentication. Click Add provider and select the SAML2 SSO option.

Download the Metadata File from Flexopus and upload it to Keycloak. The Client ID and Client Protocol fields will autofill. Save your entries.

You do not need to make any changes to the default settings.

Click on the Mappers tab, then select the Add Built-in button.

Select the following options to apply the Default Mappers:X500 Email, X500 Givenname, X500 Surname.

Add a new Mapper for the unique principal name (UPN)

Now the mapping should look like this:

You can also synchronize the department, jobtitle and costcenter attributes if they exist as text fields in the system. For more information, see the mapping here:

Flexopus: SAML2 for a custom provider

Learn how to integrate Flexopus with any SAML2-compliant identity provider for secure single sign-on.

Flexopus Help CenterDaniel Fafula

In your Flexopus instance, you can now store the following URL at METADATA URL.

STEP 2 - Configure Flexopus

In Flexopus, navigate to Dashboard > Settings > Authentication and select the created SAML2 Provider. Enable the SAML2 SSO and paste the metadata URL into the configuration field.

Enter the name for the SAML2 Login button to display on the login page. Recommendation: “SSO Login”.

(Optional) Enable synchronization for fields configured in the SAML2 settings, such as jobtitle or department.

In the security settings, set the allowed domains for SSO to * (star) and press ENTER. This allows any user in your directory to log in.

By default, SAML2 SSO users are registered automatically after their first login attempt. This avoids manually creating each user profile before their first login; however, you can disable this setting if needed (not recommended).

STEP 3 - Configure who can log in

If you attempt to log in to Flexopus now, an error message will appear because login permissions from your Keycloak user directory have not yet been configured. Assign a test user to the application and test the connection in Flexopus.

Open Keycloak settings and specify which users or groups are authorized to access the application. It is recommended to enable login for the entire organization unless there are specific access restrictions. This approach minimizes the need for ongoing access maintenance and reduces potential support requests related to log in configuration.

STEP 4 - (Optional) memberOf group synchronization.

You can optionally send an array of groups via the memberOf SAML2 attribute to Flexopus. This way you can manage groups through Keycloak in Flexopus. Read more in this article:

Flexopus: memberOf SAML2 attribute

Learn how to synchronize user groups in Flexopus using the memberOf attribute during SAML2 authorization.

Flexopus Help CenterDaniel Fafula

Navigate in Flexopus as an administrator to Dashboard > Settings > Authentication. Click on the preconfigured SAML2 provider and find the setting labeled Synchronize groups. By default, this setting is off. Change it to array.

Navigate in Keycloak as an administrator to the mappers and add a new attribute mapping memberOf.

The result should look like this:

Log in again and then check whether the groups have been transferred.

Once you assigned a group and tested it, you can expect the following changes in Flexopus. The groups will be updated or created with an external status marking, which means that you cannot edit the groups locally in Flexopus. You cannot change the names, add users or delete users from the group. The single source of truth will be the group structure in your Keycloak directory.

You can use the groups for access management within Flexopus similar to the other internal or system groups.  Learn more about groups here:

Flexopus: User groups

Learn how to manage user groups in Flexopus for effective access control and reservation rights.

Flexopus Help CenterDaniel Fafula

Trouble Shooting / FAQ