Using SSO (Single Sign-On) with Keycloak

book reader icon
14 Minutes
facebook logo gray
linkedin logo gray
mail logo gray
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.

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.

What is SSO?

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.

How the Integration with Keycloak works

To integrate your Keycloak with our White Label Platform we use SAML 2.0 (Security Assertion Markup Language) to exchange information between your system and our system.

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.

Simplified SSO Integration overview with Keycloak
Simplified SSO Integration overview with Keycloak

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.

How To Connect to our QR Code Platform with SSO using Keycloak

1. Set up Keycloak for SSO

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.

Optional: Create a new Keycloak Realm

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.

Click on dropdown below Keycloak Logo, then on Create realm
Click on dropdown below Keycloak Logo, then on Create realm

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.

Enter a realm name and click on Create
Enter a realm name and click on Create

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

Click on Realm settings
Click on Realm settings

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:

https://yourdomain.com/realms/YourCompanyRealm/protocol/saml/descriptor

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

2. First configuration of White Label Platform

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.

Login

Login
Login Form

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

SSO Types: 1 to 1 versus 1 to many
SSO Types: 1 to 1 versus 1 to many

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.

Create User (1:1)

1 IDP User is assigned to 1 White Label User
1 IDP User is assigned to 1 White Label User

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.

Create Subaccount (1:n)

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.
1 IDP User is assigned to 1 or more White Label Users
1 IDP User is assigned to 1 or more White Label Users

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:

Click Users on the left side and then Create User
Click Users on the left side and then Create User
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.

Enter the SAML 2.0 Identity Provider Metadata Url you saved before
Enter the SAML 2.0 Identity Provider Metadata Url you saved before

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:

https://yourdomain.com/realms/YourCompanyRealm/protocol/saml

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

Click on Connect
Click on Connect
You then get presented the Service Provider Descriptor URL. Download the configuration file that lies behind this Descriptor Url by clicking on the Download Descriptor XML button. Remember where you store the file - we will need it in a second for your Keycloak to upload it there.
Download SSO Service Provider Descriptor URL
Download SSO Service Provider Descriptor URL

3. Finish configuration of Keycloak

Create a Client

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).

Click on the menu Clients and then on Import client
Click on the menu Clients and then on Import client

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 Browse and choose the Descriptor XML file
click on Browse and choose the Descriptor XML file

Click on Save to save the new client.

Outbound Mapper

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.

Click on the Dedicated scope link (https://auth.webapp-portal.com/realms/...) in the Assigned client scope column of the table.
click on the tab Client Scopes and on the Dedicated scope link
click on the tab Client Scopes and on the Dedicated scope link

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.

click on firstname in the Name column
click on firstname in the Name column

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

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

Next, do the same thing for the last name.

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

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.

4. Optional: Create IDP Roles

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
Click on Create role button inside the Client
Click on Create role button inside the Client

Subaccount (1:n)

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.

On the Client > Roles screen click on Create role.
Next, enter the Role name and an optional Description. Make sure that the values match the Whitel Label Username. Click on Save.
In our example we need to create Marketing and CustomerService.
enter the Role name and an optional Description
enter the Role name and an optional Description
enter the Role name and an optional Description
enter the Role name and an optional Description

Special Case: Login of Admin/Manager via SSO

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.

Example of Admin John and Manager Monica
Example of Admin John and Manager Monica

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.

On the Client roles screen click on Create role.
Next, enter the Role name and an optional Description. Make sure that the values are exactly whitelabel_admin and whitelabel_manager. Click on Save.
enter the Role name and an optional Description
enter the Role name and an optional Description
enter the Role name and an optional Description
enter the Role name and an optional Description

5. Add Users to the Client

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

Lets take a look how to assign users and groups to roles. Before we continue make sure that you have created the Roles in Keycloak (see previous chapter).

Assign a Role to a User

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.

click on Assign role
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.

Click on Filter by clients, search for webapp-portal.com, select Roles and click on Assign
Click on Filter by clients, search for webapp-portal.com, select Roles and click on Assign

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

Click on Filter by clients, search for webapp-portal.com, select Roles and click on Assign
Click on Filter by clients, search for webapp-portal.com, select Roles and click on Assign

Assign a Role to a Group of Users

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.

Optional: Create a Group

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.

In Keycloak click on the Groups menu (on the left), then click on Create group.
click on the Groups menu (on the left), then click on Create group
click on the Groups menu (on the left), then click on Create group

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

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.

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.

open the group Marketing Department and then click on Assign role
open the group Marketing Department and then click on Assign role
Since the Marketing Department group should be able to access the White Label User Marketing select Marketing for the group Marketing Department. Then click Assign.
Click on Filter by clients, search for webapp-portal.com, select Roles and click on Assign
Click on Filter by clients, search for webapp-portal.com, select Roles and click on Assign

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.

Click on the left menu Group, choose the Marketing Department and click on Add member
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.

Select the user and click on Add
Select the user and 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.

6. First Login of a SSO User

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.

SSO Type User (1:1)

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.

One IDP User maps to a White Label user
One IDP User maps to a White Label user

SSO Type Subaccount (1:n)

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.

Subaccount for IDP User
Subaccount for IDP User

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

7. SSO Debugging

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.

Browser Plugin SAML-tracer
Browser Plugin SAML-tracer

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.
Last update 1 month ago