Keycloak SSO Example¶

Keycloak is an open-source identity and access management solution for modern applications and distributed services.

This article uses a self-built Keycloak server to demonstrate how to use the SAML 2.0 protocol to enable Keycloak users to SSO login to the Guance management console.

For information on using the OpenID Connect protocol to enable Keycloak users to SSO login to the Guance management console, refer to Keycloak SSO (Deployment Plan).

Prerequisites¶

A Keycloak server has been set up, and you can log in to the Keycloak server for configuration.

If you do not have a Keycloak environment, follow these steps to set it up:

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 unzip 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 server admin login credentials

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

After the Keycloak environment is set up, enter https://IP地址:8443/auth in your browser, click Administration Console, and open the Keycloak management console.

Concepts¶

The following are basic concepts involved in the Keycloak configuration process:

Field	Description
Realm	A realm is similar to a workspace. It manages users, credentials, roles, and user groups. Realms are isolated from each other.
Clients	Clients are applications or services that can request Keycloak to authenticate a user.
Users	User accounts that can log in to the system. The login email and Credentials need to be configured.
Credentials	Credentials used to verify the identity of a user. They can be used to set the login password for a user account.
Authentication	The process of identifying and verifying a user.
Authorization	The process of granting access permissions to a user.
Roles	Used to identify the identity type of a user, such as administrator, normal user, etc.
User role mapping	The mapping relationship between users and roles. A user can be associated with multiple roles.
Groups	Manage user groups. Supports mapping roles to groups.

Procedure¶

1. Create a Keycloak Realm¶

Note: Keycloak has a built-in master realm. We need to create a new realm (similar to a workspace).

1) In the Keycloak management console, click Master > Add realm.

2) On the Add realm page, enter a realm name in the Name field, for example, "gcy", and click Create to create a new realm.

2. Create a Client and Configure SAML¶

Note: This step creates a Keycloak client and configures SAML, establishing a trust relationship between Keycloak and Guance.

1) Under the newly created "gcy" realm, click Clients, then click Create on the right.

2) On the Add Client page, fill in the following information and click Save.

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

Note: This configuration is only used to obtain the metadata document in the next step. After enabling SSO in Guance, you need to replace the Entity ID and Assertion URL with the correct values.

After the client is created, you can see the Entity ID, Protocol, and Assertion URL filled in the previous step on the Settings tab. Set the following parameters and save.

Sign Assertions: ON (Used to prevent tampering of data transmitted by the IdP, ensuring the security of data transmitted from IdP to SP.)

IDP Initiated SSO URL Name: You can enter any value, for example, "gcy". After filling, an SSO login URL will be generated (see the figure below).
Base URL: Fill in the SSO login URL generated by the previous parameter, for example, /auth/realms/gcy/protocol/saml/clients/gcy. This is mainly used to generate an access link in the Keycloak Clients to directly SSO login to Guance.

3) Under Clients > Mappers, click Create to create an email mapping. This mapping is mandatory; without it, SSO login cannot be achieved.

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

Name: You can enter any value, for example, "mail mapper";
Mapper Type: Select "User Property";
Property: Enter Email according to the rules supported by the identity provider;
SAML Attribute Name: Must be filled in as Email.

Note: Guance defines a mapping field. You must enter Email to associate the identity provider's user email (i.e., the identity provider maps the logged-in user's email to Email).

3. Obtain the KeyCloak Metadata Document¶

Note: This step obtains the metadata document for creating the identity provider in Guance.

1) Under Clients > Installation, select Mod Auth Mellon files and click Download to download the metadata document.

2) In the downloaded folder, select idp-metadata.xml.

3) Because Keycloak's metadata document is at the realm level, you need to add the client parameter /clients/<IDP Initiated SSO URL Name> to the access URL in the metadata document idp-metadata.xml. Since IDP Initiated SSO URL Name：gcy is set in this document, enter /clients/gcy in the XML file, as shown in the figure below. After adding, save the XML file.

4. Enable SSO in Guance¶

1) To enable SSO, go to the Guance workspace, navigate to Management > Member Management > SSO Management, and click Enable.

Refer to the documentation Create SSO.

Note: For account security, Guance supports only one SSO configuration per workspace. If you have previously configured SAML 2.0, the last updated SAML 2.0 configuration will be used as the final SSO verification entry.

2) Upload the metadata document downloaded in Step 3, configure the Domain (email suffix domain), and select a Role. The Entity ID and Assertion URL of the identity provider will be automatically obtained. You can directly copy the Login URL to log in.

Note: The domain is used for email domain mapping between Guance and the identity provider to achieve SSO. That is, the suffix domain of the user's email must match the domain added in Guance.

5. Replace the SAML Assertion URL in KeyCloak¶

1) Return to Keycloak and update the Entity ID and Assertion URL configured in Step 2.

Note: When configuring SSO in Guance, the Assertion URL configured in the identity provider's SAML must match the one in Guance to achieve SSO.

6. Configure Keycloak Users¶

Note: This step configures the authorized user email accounts for the identity provider created in Guance. These Keycloak user email accounts can be used to SSO login to the Guance platform.

1) Under the "gcy" realm, click Users, then click Add user.

2) Enter a Username and Email. Email is required and must match the email used in the whitelist of the Guance identity provider configuration. This is used for email mapping to log in to Guance.

3) After creating the user, set a password under Credentials.

After all configurations are complete, you can SSO login to Guance in two ways.

Method 1: Log in to Guance via Keycloak¶

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

2) Enter the configured user email and password.

3) Log in to the corresponding workspace in Guance.

Note: If multiple workspaces are configured with the same identity provider SSO, after logging into a workspace via SSO, you can click the workspace selector in the upper left corner of Guance to switch between different workspaces and view data.

1) After SSO configuration is complete, log in via the Guance official website or the Guance console. On the login page, select SSO.

2) Enter the email address used when creating the SSO, and click Get Login URL.

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

4) Enter the enterprise email (the email address configured in both Keycloak and Guance SSO Management) and password.

5) Log in to the corresponding workspace in Guance.