---
title: "Keycloak"
description: "Configure Keycloak SSO for Cloud CMS with ease. Step-by-step setup guide for seamless identity integration using SAML 2.0. (Gitana 4.0)"
product: "Gitana"
version: "4.0"
url: "/documentation/gitana/4.0/engine/sso/keycloak"
---

![keycloak-logo.png](/documentation/gitana/4.0/engine/sso/keycloak/keycloak-logo.png)

# 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)](/documentation/gitana/4.0/engine/sso/overview.md).

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](https://www.keycloak.org/downloads.html "https://www.keycloak.org/downloads.html")

The Keycloak Getting Started guide is available here: [https://www.keycloak.org/docs/latest/getting\_started/index.html](https://www.keycloak.org/docs/latest/getting_started/index.html "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.

![keycloak1.png](/documentation/gitana/4.0/engine/sso/keycloak/keycloak1.png)

### 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:

![client1.png](/documentation/gitana/4.0/engine/sso/keycloak/client1.png)

Enter 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:

![client2.png](/documentation/gitana/4.0/engine/sso/keycloak/client2.png)

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

![user1.png](/documentation/gitana/4.0/engine/sso/keycloak/user1.png)

Click the **Add User** button to create a new user.

![user2.png](/documentation/gitana/4.0/engine/sso/keycloak/user2.png)

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 log in.

![user3.png](/documentation/gitana/4.0/engine/sso/keycloak/user3.png)

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:

![mapper1.png](/documentation/gitana/4.0/engine/sso/keycloak/mapper1.png)

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:

![mapper2.png](/documentation/gitana/4.0/engine/sso/keycloak/mapper2.png)

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

![cloudcms1.png](/documentation/gitana/4.0/engine/sso/keycloak/cloudcms1.png)

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