Keycloak Single Sign-On Example¶

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

This document uses a deployed Keycloak server to demonstrate how to use the SAML 2.0 protocol to enable Keycloak users to log in to the Guance management console via SSO.

For information on using the OpenID Connect protocol to implement Keycloak user SSO login to the Guance management console, see Keycloak SSO (Deployment Plan).

Prerequisites¶

A Keycloak server is deployed and you can log in to the Keycloak server for configuration.

If you do not have a Keycloak environment, follow the steps below 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 the 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 the server administrator login account and password

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_address:8443/auth in the browser, click Administration Console to open the Keycloak administration console.

Concepts¶

The following describes the basic concepts in the Keycloak configuration process:

Operation Steps¶

1. Create a Keycloak Realm¶

Note: Keycloak itself has a master realm (Master). We need to create a new realm (similar to a workspace).

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

1. On the Add realm page, enter a realm name in the Name field, such as "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 to establish a trust relationship between Keycloak and Guance.

1. In the newly created "gcy" realm, click Client and then click Create on the right.

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

2. Client ID (Entity ID): https://auth.guance.com/saml/metadata.xml;

3. Client Protocol: Select SAML;
4. Client SAML Endpoint (Assertion Address): temporarily use 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, obtain the correct Entity ID and Assertion Address and replace them.

After the client is created, you can view the Entity ID, protocol, and assertion address configured in the previous step under Settings. Set the following parameters and save.

• Sign Assertions: ON (prevents data transmitted by the IdP from being tampered with and ensures the security of data transmitted from the IdP to the SP.)

• IDP Initiated SSO URL Name: You can enter any value, such as "gcy". After filling it in, an SSO login URL is generated, as shown in the figure below;
• Base URL: Enter the SSO login URL generated by the previous parameter, such as /auth/realms/gcy/protocol/saml/clients/gcy. This is mainly used to generate an access link in Keycloak Clients to directly log in to Guance via SSO.

1. In Mappers under Clients, click Create to create the email mapping. This part is required. If left empty, SSO login cannot be implemented.

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

• Name: You can enter any value, 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: In this example, fill in Email to pass the user's email address.

Note: In SAML Attribute Mapping of Guance, set the Email mapping to the attribute name returned here (Email in this example). Also configure the required Username mapping. The Phone Number mapping can be filled in as needed.

3. Obtain the Keycloak Metadata Document¶

Note: This step allows you to obtain the metadata document for creating the identity provider in Guance.

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

1. In the downloaded folder, select idp-metadata.xml.

1. Since the Keycloak 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. Because 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 it, save the XML file.

4. Enable SSO in Guance¶

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

For more information, see Create SSO.

Note: For account security reasons, Guance supports only one SSO configuration per workspace. If you have previously configured SAML 2.0, your most recently updated SAML 2.0 configuration is used as the final SSO verification entry by default.

1. Upload the metadata document downloaded in Step 3, configure the domain (email domain suffix), and select the role to obtain the identity provider's Entity ID and Assertion Address. You can also directly copy the Login URL to log in.

Note: The domain is used for email domain mapping between Guance and the identity provider to implement SSO. That is, the email domain suffix of users must be consistent with the domain added in Guance.

5. Replace the SAML Assertion Address in Keycloak¶

1. Return to Keycloak and update the Entity ID and Assertion Address from Step 2.

Note: When configuring SSO in Guance, the assertion address configured in the identity provider's SAML must be consistent with the one in Guance for SSO to be implemented.

6. Configure Keycloak Users¶

Note: In this step, you configure the authorized user email accounts for the identity provider created in Guance. Users can log in to the Guance platform via SSO using the configured Keycloak user email accounts.

1. In the created "gcy" realm, click User and then click Add user.

1. Enter the Username and Email. Email is required and must match the allowlist email configured in the Guance identity provider so that users can log in to Guance through email mapping.

1. After creating the user, set a password for the user under Credentials.

7. Use a Keycloak Account to Log In to Guance via SSO¶

After all configurations are complete, there are two ways to log in to Guance via SSO.

Method 1: Log In to Guance from Keycloak¶

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

1. Enter the configured user email and password.

1. Log in to the corresponding workspace in Guance.

Note: If multiple workspaces have configured the same identity provider for SSO login, after users log in to a workspace via SSO, they can click the workspace option in the top-left corner of Guance to switch between different workspaces and view data.

Method 2: Log In to Guance with a Keycloak Account via SSO¶

1. After the SSO configuration is complete, log in through the Guance official website or the Guance console, and select Single Sign-On on the login page.

1. Enter the email address used when creating the SSO and click Get Login URL.

1. Click the link to open the enterprise account login page.

1. Enter the enterprise email address (the email address configured in Keycloak and Guance SSO management) and password.

1. Log in to the corresponding workspace in Guance.

Note: If multiple workspaces have configured the same identity provider for SSO login, after users log in to a workspace via SSO, they can click the workspace option in the top-left corner of Guance to switch between different workspaces and view data.