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:
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:
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:
Trouble Shooting / FAQ
I got a 500 Error during the login.
In case you get a 500 error, you may misconfigure the URLs or the attributes. Check the settings based on the manual once again. If you can not find the issue, contact us via support@flexopus.com. We have server logs to see where the problem lies.
Can I change the UPN of the users?
As you may know, UPN stand for UNIQUE principal names. Unique attributes shall never change, especially the UPN of the user shall remain the same. It can be a number or anything else. External application are identifying users based on their UPN, if you change you may risk creating a new user within Flexopus. Still, you may have a reason to change the UPN. In this case, contact us via support@flexopus.com. We can assist you by deleting the UPNs and the External IDs of the user to allow you the change of the UPNs in your IdP.
Can I also synchronize the user profile pictures?
Unfortunately, the SAML2 SSO protocol is not supporting the synchronization of profile pictures.
I saw an attribute costcenters. What is it doing?
Indeed, we have an additional attribute, which is called costcenters. The feature is currently in a BETA testing phase. More information will follow.
Does Flexopus support Identity Provider (IdP) Initiated single sign on login?
Yes and No. We provide a workaround for the IdP initiated logins. You need to configure the initiate-sp-login
parameter for the RelayState. This will convert the IdP initiated login request into an SP initiated login. In this way, we can ensure a secure login process.
Reason: A classical IdP initiated login would enable a man in the middle attack for hackers. Through an SP initiated login, we can avoid it. This article explains the reasons in more details: https://www.identityserver.com/articles/the-dangers-of-saml-idp-initiated-sso
R0052