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, you need to enter the Client ID, Client protocol and the Client SAML Endpoint. These configuration parameters can be found within Flexopus. Navigate in Flexopus as an administrator to Dashboard > Settings > Authentication. Click in the Add provider button and select the SAML2 SSO option.

Download the Metadata File from Flexopus. Upload this metadata file to KeyCloak. The Client ID and Client Protocol fields are filled in automatically. Save your entries.

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

Click on the Mappers tab and then on the Add Builtin button.

Select the following options to have the Default Mappers applied:
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:

SAML2 for a custom provider

Which Identity Providers are supported for SAML2? Flexopus implemented the standard SAML2 Single Sign On protocol, which suppose to work with any Identity Providers that follows the SAML2 standard. Flexopus acts as a Service Provider. Therefore, you can try to connect your Identity Provider, even if we do not provide

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 select paste the metadata URL in the configuration.

Enter the name of the SAML2 Login button, which will be displayed on the login page. Recommendation: SSO Login

(optional) Enable the synchronization of the fields that you configured in the SAML2 settings: jobtitle or department

In the security settings, set at the allowed domains for SSO a * (star) and press ENTER. By this, you allow every user to log in that is configured in your directory for the login.

By default, the SAML2 SSO user are registered after the first login attempt automatically. This is good for you, since you don't need to create the user profiles manually one by one before the first login, however you can disable this setting (not recommended).

STEP 3 - Configure who can log in

If you try to log in now into Flexopus, you will see an error message, since you did not configure who can or cannot log in from your Keycloak user directory. Assign a test user to the application and test the connection at Flexopus.

Open the settings and decide which user or group can log in into the application. It's recommended enabling the login for the whole organization in case you don't have any reasonable limitations in place. In this case, you don't need to maintain the user's access for the login, and you can reduce the number of possible support cases regarding the login 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:

memberOf SAML2 attribute

Synchronize groups via SAML2 Flexopus implemented the standard SAML2 Single Sign On protocol, which suppose to work with any identity providers that follows the SAML2 standard. Often it’s not only required to set up a Single Sign On configuration for the login, but it’s also necessary to exchange group memberships.

Flexopus Help CenterDaniel Fafula

Navigate in Flexopus as an administrator to Dashboard > Settings > Authentication. Click on the preconfigured SAML2 provider and go to the setting called synchronize groups. This setting is turned off by default. Select the Array option.

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 can not edit the groups locally in Flexopus. You can not change the names, add user or delete user 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:

User groups

Introduction Here you can see a list of action you can do with user groups to use and manage them as an administrator: How to manage the user groups? * Manage groups manually * Manage groups via the SCIM API * Manage groups via SAML2 (memberOf) * Import users and groups (CSV and XLSX)

Flexopus Help CenterDaniel Fafula

Trouble Shooting / FAQ

R0052