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.

Log into the Keycloak Administration Console

Keycloak offers an Administration Console that is generally available at:

http://localhost:9090/auth/admin

It may be on a different port depending on the exact version of Keycloak that you're using. This example was written using Keycloak 3.4.6 (which is a bit older) but the steps provided here should be more or less consistent.

Enter the username and password you created on the Welcome Page or the add-user-keycloak script. 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_SHA256
  4. Force POST Binding should be set to On.
  5. Valid Redirect URIs should have an entry for *.

There are a lot of other options available. For more information on these options, please check out:

http://www.keycloak.org/docs/2.5/server_admin/topics/clients/client-saml.html

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.

You will need to click the Reset Password button to apply your changes.

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

  • firstname = Joe
  • lastname = 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.

An example of creating a Mapper "First Name" is:

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:9090/auth/realms/master/protocol/saml

This may vary depending on your installation of Keycloak (port, etc).

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

Save your changes and log out.

Verify it works

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

  • Log out of your current Cloud CMS account
  • Log back in
  • While Logging in again, you will be re-directed to Keycloak
  • Keycloak will ask for your username and password.
  • Enter joesmith and provide Joe's password.
  • If the credentials match, you will be redirected back to Cloud CMS.
  • Cloud CMS will automatically log you in and create your user if it doesn't yet exist.
  • Proceed and be merry.