Keycloak

This page provides an example of how to configure Cloud CMS Single Sign On (SSO) for JBoss KeyCloak.

Keycloak is an open-source Identity and Access Management product provided by JBoss/RedHat.

Keycloak plays the role of an Identity Provider that speaks SAML 2.0 and/or JWT. Cloud CMS integrates via either of these mechanism and can therefore integrate to Keycloak straight away as an identity provider.

Cloud CMS provides Single Sign On (SSO) Enterprise support for a variety of Identity Providers using SAML 2.0 and/or JWT. For more information, see Cloud CMS Single Sign On (SSO).

You can learn more about Keycloak here:

http://www.keycloak.org/about.html

Set up Keycloak

In this section, we'll set up Keycloak with some sample data that we can use to demonstrate SSO.

Here we assume that you've downloaded and installed Keycloak. For the purposes of this documentation, we've tested using Keycloak 8.0.2.

The Keycloak download is available here: https://www.keycloak.org/downloads.html

The Keycloak Getting Started guide is available here: https://www.keycloak.org/docs/latest/getting_started/index.html

Once you have Keycloak up and running, you should proceed to learn how to set it up as an SSO provider for Cloud CMS.

Log into the Keycloak Administration Console

Keycloak offers an Administration Console that is generally available at:

http://localhost:8080/auth/admin

It may be on a different port depending on the exact version of Keycloak that you're using.

Enter your administrative username and password to log in. If you're using a standard configuration, then this may simply be admin / admin.

Once you have logged in, you can see the Admin Console with a Master realm already present.

Create a SAML 2.0 Client

Go to Clients in the left menu bar. Click on the Create button the right hand side of the page.

You will see a form like this:

Enter in the Client ID of the client. This can be any name but we recommend myapp.

Select saml in the Client Protocol drop down box.

Click Save. This will create the client and bring you to the client Settings tab as below:

Customize the Client

By default, Keycloak sets up your client to work with default settings. We need to make a few adjustments to have it work correctly with Cloud CMS.

1. Include AuthnStatement should be set to On.
2. Sign Documents should be set to On.
3. Signature Algorithm should be set to RSA_SHA1
4. Force Signature Required should be set to Off.
5. Force POST Binding should be set to On.
6. Valid Redirect URIs should have an entry for *.

Make sure to save your changes.

Create a User

Let us now create a user named Joe Smith.

Go to Users in the left menu bar. Then, on the right side of the empty user list, you should see an Add User button.

Click the Add User button to create a new user.

The only required field is Username. Click Save.

Once the User is created, go to the Credentials tab and add a Password for the User which will be used to login.

Set Temporary to off. Then click on Set Password to apply your changes.

Finally, click on the Attributes tab and add three attributes.

• first_name = Joe
• last_name = Smith
• name = joesmith

Cloud CMS supports mapping user attributes from SAML Assertions back into the Cloud CMS user object. It also supports group mappings to auto-sync project and team memberships, but we'll leave that for another time.

Add Mappers

We now want to tell Keycloak to hand back these three attributes (firstname, lastname and name) as part of the SAML 2.0 assertion response. That way, Cloud CMS will learn about these properties when a user successfully logs in and can use them to automatically keep the Cloud CMS user account in sync.

Go to your myapp Client by clicking on Clients on the left-hand menu bar. Then click on myapp.

Click on the Mappers tab:

Click on Create button present on the right side of the Mappers tab and start creating a mapper.

Add this mapping for First Name:

• Name = first_name
• Mapper Type = User Attribute
• Property = first_name
• Friendly Name = firstName
• SAML Attribute Name = firstName

Add this mapping for Last Name:

• Name = last_name
• Mapper Type = User Attribute
• Property = last_name
• Friendly Name = lastName
• SAML Attribute Name = lastName

Add this mapping for Name:

• Name = name
• Mapper Type = User Attribute
• Property = name
• Friendly Name = name
• SAML Attribute Name = name

An example of creating a Mapper "First Name" might look something like this:

Set up Cloud CMS

In a new browser window, log in to the Cloud CMS user interface.

Click on Manage Platform and then pick SSO on the left-hand menu.

Select SAML 2.0 from the radio button list.

And then fill out the form.

The following is required:

1. The SAML URL should be http://localhost:8080/auth/realms/master/protocol/saml

This may vary depending on your installation of Keycloak. By default, Keycloak is installed on port 8080. If you've modified this or if your Keycloak installation exists on a different port, you will need to modify this URL.

2. The SAML Issuer should match the Keycloak Client ID of myapp.

3. Under the User Field Mappings section, add the following:

• User Property firstName = Field Value firstName
• User Property lastName = Field Value lastName
• User Property name = Field Value name

This sets things up so that the SAML Assertion Attributes (which you configured using User Attribute Mappers in Keycloak) will be picked up and sync'd to the Cloud CMS user's properties.

Save your changes and log out.

Verify it works

You can now verify that Cloud CMS is configured to use SAML 2.0:

1. Log out of your current Cloud CMS account
2. Try to access Cloud CMS again.
3. You will be redirected to Keycloak's login screen.
4. Fill in the username and password for the Joe Smith user you created above.
5. After you successfully authenticate to Keycloak, you will be redirected back to Cloud CMS.
6. Cloud CMS will automatically log you in and create your user if it doesn't yet exist.
7. Proceed and be merry.

Tips and Tricks

While testing our your SSO configuration, you may find that you need to log back into Cloud CMS as an administrator or as another pre-established account. To do so, simply go to the Cloud CMS UI and point to the /login route.

This lets you log in manually using an existing account.