Keycloak SSO¶

Keycloak is a cloud-based identity and access management service launched by RedHat, which can help enterprises manage internal and external resources.

This article uses the built Keycloak server to demonstrate how to use the SAML 2.0 protocol to implement Keycloak user SSO login to the Guance console.

Preconditions¶

The Keycloak server has been set up and can be logged in to the Keycloak server for configuration.

If there is no Keycloak environment, you can refer to the following steps to build it:

sudo yum update         #update

sudo yum install -y java-1.8.0-openjdk java-1.8.0-openjdk-devel      #install JDK

wget https://downloads.jboss.org/keycloak/11.0.2/keycloak-11.0.2.zip   #download Keycloak

yum install unzip       #install the unzipped package

unzip keycloak-11.0.2.zip       #unzip the downloaded Keycloak

cd keycloak-11.0.2/bin         #enter the bin directory

./add-user-keycloak.sh -r master -u admin -p admin     #Create a server administrator login account and password

nohup bin/standalone.sh -b 0.0.0.0 &     #Go back to the bin directory and hang in the background on Keycloak to start the service

After the Keycloak environment is built, enter https://IP address:8443/auth in the browser, and click "Administration Console" to open the Keycloak management studio.

Concepts¶

Here are the basic concept explanations during the KeyCloak configuration process:

Setup¶

1. Create Keycloak realm¶

Note: Keycloak itself has a Master domain, so we need to create a new domain (similar to a workspace).
1）In the Keycloak administrative console, click "Master"-"Add realm".

2）On the "Add realm" page, enter a domain Name at "Name", such as "gcy", and click "Create" to Create a new domain.

2.Create a Client and Configure SAML¶

Note: This step will create the Keycloak client and configure SAML to establish a trust relationship between Keycloak and Guance so that they trust each other.
1）Under the newly created "gcy" field, click "Client" and click "Create" on the right.

2）After "Add Client" is completed as follows, click "Save".

• Client ID (Entity ID): https://auth.guance.com/saml/metadata.xml
• Client Protocol: Select
• Client SAML Endpoint, temporary use: https://auth.guance.com/saml/assertion

Note: This configuration is only used to obtain the metadata document for the next step. After SSO is enabled in Guance, the correct "Entity ID" and "Assertion Address" are obtained and replaced again. Refer to doc **New SSO 。**

After the Client is created, you can see the entity ID, protocol, and assertion address filled out in the previous step in "Settings". Save after setting the following parameters.

• Sign Assertions：ON (used to prevent data transmitted by IdP from being tampered with and to secure data transmitted from IdP to SP.)

• IDP Initiated SSO URL Name: can be filled at any time, such as "gcy". After filling out, SSO address will be generated, as shown in the following figure.
• Base URL: Fill in the SSO address generated by the previous parameter, such as /auth/realms/gcy/protocol/saml/clients/gcy, which is mainly used to generate access links in Keycloak Clients to sign on directly to Guance.

3）In the "Mappers" section of "Clients", click "Create" to Create a mailbox map, which is required and cannot be completed without SSO.

On the "Create Protocol Mapper" page, enter the following and save.

• Name: optional, such as "mail mapper"
• Mapper Type: Select "User Property"
• Property: Fill in "email" according to the rules supported by the identity provider
• SAML Attribute Name: Required "Email"

Note: Guance defines a mapping field, which must be filled in with "Email" to associate the identity provider's user mailbox (that is, the identity provider maps the logged-in user's mailbox to Email).

3.Get the KeyCloak Metadata Doc¶

Note: This step obtains the metadata document for creating identity providers in Guance.
1）In the "Installation" of "clients", select "Mod Auth Mellon files" and click "Download" to Download the metadata document.

2）In the Download folder, select "idp-metadata.xml".

3）Since Keycloak's cloud data document is "domain" level, you need to add client parameters /clients/<IDP Initiated SSO URL Name> to the access address in the metadata document "idp-metadata.xml", in this document IDP Initiated SSO URL Name：gcy is set, then fill in /clients/gcy in the xml file, as shown below. Save the xml file after adding.

4.Configure the Keycloak User¶

Note: In this step, the authorized user email account of the identity provider is configured to be created in Guance, and the configured Keycloak user email account can be used to log in to Guance platform.
1）In the created gcy domain, click "User", click "Add user".

2）Enter "Username" and "Email", which is required and needs to be consistent with the User list mailbox configured by Guance identity provider to match the mailbox mapping to log in to Guance.

3）After creating the User, set the password for the User in "Credentials".

5.Enable SSO in Guance and Replace SAML Assertion Address in KeyCloak¶

1）Enable SSO, and click Enable in Guance workspace "Management"-"SSO Management". Refer to the doc new SSO.
Note: For account security reasons, only one SSO is configured in Guance support workspace. If you have previously configured SAML 2.0, we will regard your last updated SAML 2.0 configuration as the final single sign-on authentication entry by default.

Upload the "metadata document" of the identity provider, configure the "mailbox domain name", and select "access role" to obtain the "entity ID" and "assertion address" of the identity provider, and support directly copying the "login address" for login.
Note: When SSO login is enabled, "mailbox domain name" needs to be added for mailbox domain name mapping between oGuance and identity provider (user mailbox domain name needs to be consistent with mailbox domain name added in Guance) to realize single sign-on.

3）Return Keycloak and updates SAML's "assertion address", see step 2.2)。
Note: When configuring single sign-on in Guance, the assertion address configured in the identity provider SAML must be consistent with that in Guance to implement single sign-on.

6.SSO to Guance Using Keycloak Account¶

After all configuration is completed, there are two ways to single sign-on to Guance.

Method 1: Log in to Guance at Keycloak¶

1）In Keycloak's Clients, click "Base URL" on the right.

Enter the configured user mailbox and password.

Log in to the workspace corresponding to Guance.
Note: If multiple workspaces are configured with the same identity provider SSO at the same time, users can click the workspace option in the upper left corner of Guance to switch between different workspaces to view data.

Method 2: SSO with Keycloak Account in Guance¶

1）After the SSO configuration is completed, log in through Guance official website or Guance studio, and select SSO on the login page.

2）Enter the email address where the SSO is being created and click "Get login address".

3）Click the link to open the enterprise account login page.

4）Enter the enterprise common mailbox (the enterprise mailbox address configured in Keycloak and Guance SSO management) and password.
Log in to the workspace corresponding to Guance.
Note: If multiple workspaces are configured with the same identity provider SSO at the same time, users can click the workspace option in the upper left corner of Guance to switch between different workspaces to view data.