Using SSO (Single Sign-On) with Keycloak

This article will guide you to how to connect your users on Keycloak via Single Sign-On (SSO) to our platform. This feature is only available for enterprise customers.

This article is covering the SSO integration with our platform based on an example with Keycloak.

• If you are using MS Azure Entra ID read our SSO post for Microsoft Azure Active Directory.
• If you are using Okta read our SSO post for Okta

This post contains technical details for IAM Admins or your IT
department managing Keycloak. Please get in touch with an IT expert on your end to help you in setting up the SSO connection.

SSO stands for Single Sign-On. It's an authentication process that allows a user to access multiple services, such as our QR Code platform, with only one set of login credentials (such as username and password). With SSO, users don't need to remember different passwords for each application they use, streamlining the login process and enhancing security by reducing the need for multiple credentials. Once authenticated, the user can navigate between various applications or services without needing to log in again.

Your company acts as a Identity Provider (IDP) that provides user data to us. Our White Label Platform acts as a Service Provider (SP) receiving user data and giving users access to our system.

Basic information about your IDP and our SP are going to be exchanged via so-called Descriptor URLs.

Behind these URLs are files that describe the IDP (your Keycloak) or SP with details for the other side to process automatically and help with the configuration.

The user information is going to be sent via a SAML 2.0 message. In this message the data is encoded in Attributes. When sending out the information from your Keycloak an Outbound Mapper is mapping your internal IDP fields, like first name, last name, email, etc. to SAML 2.0 Attributes.

When we receive your SAML 2.0 message our Inbound Mapper transforms the SAML 2.0 Attribute back to our internal format and we will sign in the user into our platform.

As the first step we need to make sure that your Keycloak system is ready to be an IDP (Identity Provider).

You always need a realm to operate upon. The realm has users stored inside of it. These users have certain information stored like first name, last name and email. They also have certain roles. The realm will also be connected to our White Label Platform via a so-called Client.

For the SSO connection from your Keycloak system to our White Label Platform you can either use an already existing realm (with users already inside of it) or create a completely new one.

If you want to use a new realm just follow the following steps.

First, make sure you are logged into your Keycloak system as an Administrator.

Then click the dropdown directly under the Keycloak logo in the top left of the screen.

On the following screen enter a realm name and click on Create. In our example we use YourCompanyRealm.

Attention: Please make sure that you don't use any spaces or special characters for the Realm name because this is a technical fieldname and can lead to problems. After creating a realm you can set a Display name which can be more expressive and is also the field that actually will be shown to the users.

After you have created the realm go to the Realm settings (in the left menu).

Go to the bottom of the page until you can see the Endpoints. There right-click on

SAML 2.0 Identity Provider Metadata and then choose Copy link.

The copied URL should look something like this:

Notice: The SAML 2.0 Identity Provider Metadata Url is the Descriptor URL of your Keycloak Identity Provider.

Now its time to set up our Service Provider configuration in the White Label Portal.

Head to our website and login to your white label account. Once logged in go to your Account settings and choose the SSO tab.

When you sign in with a user from your company on our platform you can choose how this user can access the platform. There are 2 different scenarios possible:

• User logs in as white label user 1:1
• User can login under different white label users 1:n

To continue with the setup of the SSO connection you must choose a SSO Type first.

For you to understand the concepts as quickly as possible we use an example during this article. Let‘s make the following assumptions:

• The users Adam, Eve and Steve work in your company and need to get access to the White Label Platform.
• You are using Keycloak
  as the Identity Provider (IDP) in your company. If you don't have Keycloak but a different IDP you do not need to worry.
  You can check out our general SSO post.

Attention: In the case of 1:1 a monthly fee for every user occurs.

Select User if you want that a user in your Identity Provider (="IDP User") will be assigned to exactly one (1:1) individual white label user.

When an IDP User signs in for the first time, the corresponding White Label User will be created. In the example above the IDP User Adam will be created as White Label User Adam when he is logging in for the first time.

In this scenario, let's assume as an example that the White Label platform has one user for the Marketing department and one user for the CustomerService department.

Select Subaccount if you want that a user in your Identity Provider (="IDP User") is mapped to one or more (1:n) white label users.

In the example above the IDP users Adam and Eve can use the White Label Users Marketing and CustomerService. The IDP User Steve can only use the White Label User CustomerService.

Before they can be used via SSO make sure that these two users are created in the White Label Platform by creating them via the menu Users on the left side and then Create User.

After creation the User list should look like this:

Inspiration: The White Label Users do not need to be based on a department like Marketing or CustomerService. We just use this here as an example.
It is also quite common that there is a separate White Label User for every

• Country (Austria, Spain, Italy, Brazil, etc.) and/or 
• Brand (BrandA, BrandB, BrandC, etc.) and/or 
• Product Line (Shoes, Shirts, Jacktes, etc.)

The use case can be different for every company. So, just think about how it would make the most sense for your company.

An IDP User will then act like a teamleader and he can choose under which white label user he wants to sign in. Hence Adam and Eve can choose if they want to sign in as White Label User Marketing or CustomerService

After you have chosen the SSO Type you need to enter the SSO IDP Descriptor URL of your Keycloak Identity Provider. This is needed for us to get basic information about how to connect and authenticate your users with SAML 2.0.

In order for you to do that you just need to copy the SAML 2.0 Identity Provider Metadata Url you have saved before into the field.

Once you have entered the SSO IDP Descriptor URL the service URLs are extracted from the Descriptor URL and the fields for the SSO Signon Service URL and the SSO Logout Service URL are pre-populated.

If there are no URLs shown, please enter them manually. The SSO Logout Service URL is optional. If the URL is set, the user will be redirected to this URL when he signs out from the QR Code platform. He can then optionally also log out from his IDP.

For a Keycloak system the Url should look something like this:

Click on the Connect button at the bottom to initialize the connection to your Keycloak.

We now need to create a so-called Client in your Keycloak system. This client is the bridge between your Keycloak and our White Label Platform Service Provider.

Now switch back to your Keycloak system and into the realm you worked with before (in our example YourCompanyRealm).

Click on the menu Clients and then on Import client (right next to the Create Client button).

On the Import client screen click on Browse and choose the Descriptor XML file you just downloaded before.

The content from the Descriptor XML file then gets loaded into the Resource file text area and the Client ID gets set automatically.

You can optionally name the Client if you want. In our example we will name it QR Code Platform.

Click on Save to save the new client.

Next, we need to configure our Outbound Mapper in Keycloak to be able to transfer fields like first name, last name and email as well as the roles of the users.

In the Client that you just created (https://auth.webapp-portal.com/xxx) click on the tab Client scopes.

You should now see a Dedicated scope and a SAML role list scope.

In the Dedicated scope you already see the list of fields that our Service Provider needs from your Keycloak Identity Provider (thanks to the Descriptor XML we uploaded before).

Now we just need to configure the mapping for it. In order to do that lets start with the first name. Therefore click on firstname in the Name column.

Now click on the User Attribute dropdown and choose the firstName entry. Click on Save.

Next, do the same thing for the last name.

Now, do the same thing for the email.

Since the Mappers in the Dedicated scope got automatically created, due to the upload of the Descriptor XML, the SAML Attribute Names already match the entries in the SSO IDP Inbound Mapping in our Service Provider. So, no further configuration is necessary on the White Label Platform Service Provider concerning the mapping.

If you want to use the Subaccount (1:n) approach with creating users on the White Label Platform (discussed before) or you want to use SSO for Administrators and Managers you need to configure IDP Roles for that.

You can find the necessary screen via the following steps:

• Click on Clients in the left menu
• Click on the Client you just created - in our example its QR Code Platform
• Click on the Create role button to create a new role
  

If you have selected the SSO type Subaccount (1:n) you need to provide the information which IDP User should have access to which White Label User.

In order to do this we need to create an additional Role for every White Label User in the Keycloak Client roles. The name of the role must be identical to the White Label user name.

Your admin user can log into our whitelabel platform directly via username and password by default. However, it is also possible to use SSO to log in as an admin or manager.

For that case there are 2 special Roles available: whitelabel_admin and whitelabel_manager.

In our example we have 2 users in the organization that are a admin/manager. User John should be an Admin in the Whitelabel Portal, hence needs the Role whitelabel_admin, user Monica should be a Manager, hence needs the Role whitelabel_manager.

In order to do this we need to create two additional Roles named whitelabel_admin and whitelabel_manager in Keycloak. The names of the roles must be exactly that.

After we configured everything its time to actually add users in Keycloak, so that they can access the White Label Platform.

In the SSO-Type "1:n" scenario or if you want to give a user an Admin or Manager role do the following.

In Keycloak click on the Users menu (on the left), then choose a User (in our example Adam), click on the tab Role mapping and click on Assign role.

In the dropdown in the top left select Filter by clients to just see our client roles and enter webapp-portal.com into the search field to just see the relevant roles.

Since Adam should be able to access the White Label Users Marketing and CustomerService in the 1:n Scenario select Marketing and CustomerService for the user Adam. Then click Assign.

Conversely user John should be a White Label Admin. In that case choose the role whitelabel_admin.

In the SSO-Type "1:n" scenario or if you want to give a group an Admin or Manager role do the following.

In our example we want to have the behavior that everyone that is in the Marketing Department (member of the Group Marketing Department) should have access to the White Label User Marketing.

Usually you will already have groups for your departments like Marketing and CustomerService and have Users assigned to it. For this example we assume that we don't and will create them now.

Enter the name of the Group, e.g. Marketing Department, and click Create.

Now we will make sure that everyone in the Marketing Department group gets the Role Marketing assigned. We do this by opening the group Marketing Department and then clicking on Assign role.

You can do the same for a group CustomerService Department and also for example an White Label Admin Group or White Label Manager Group group.

After configuring the Groups its time to assign Users to the Groups.

Click on the left menu Group, choose the Marketing Department and click on Add member.

In the popup select the users that should belong to the group, in our example the user Adam should belong to the group Marketing Department, and then click on Add.

Now the user Adam, and every other user that would get added to the group Marketing Department, would get access to the Role Marketing and therefore be able to access the White Label User Marketing.

In this section you will see how the white label account looks like after the first login of the users for the 2 different SSO types.

When an IDP user logs in for the first time via SSO, a White Label user with the same name is created. In the example below you see the 3 IDP users Adam, Eve and Steve created as White Label users in the User section.

If an IDP user logs into our platform for the first time, a subaccount with the role SSO is created and the matching White Label users are assigned to that subaccount. You can see the Subaccounts in the Account section under the Subaccounts tab.

The following screenshot shows the IDP user Adam assigned to the White Label users Marketing and CustomerService.

To debug the SAML 2.0 communication between your Identity Provider (IDP) and our Service Provider (SP) you can install the browser plugin SAML-tracer.

• Firefox
• Chrome

After you open the SAML-tracer popup...

1. start with a SSO login process
2. You will see the list at the top of the popup fill with HTTP requests.
3. Click on the request that is marked as a SAML request in orange color.
4. Choose the tab Summary (or SAML for all the details in XML format). You can check, if the data (eg. Role) is transferred correctly. In this case the role whitelabel_admin has been transferred. This is exactly what we need for this user to log in as a whitelabel portal admin.