Configure Keycloak Users and Mapping Rules¶

Introduction¶

This article will explain how to configure users and mapping rules in Keycloak. After configuration is complete, single sign-on (SSO) can be achieved through the mapping rules to Guance.

Configure Keycloak Users¶

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

1. Enter the Username and Email. The email is a required field and must match the user email configured in the Guance backend management to ensure correct email mapping for SSO login to Guance.

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

Configure Mapping Rules¶

After adding Keycloak users, there are two ways to configure mapping rules: one is adding mapping rule attributes directly to the user, and the other is adding the user to a user group and then adding the mapping rule attributes.

Add Mapping Rule Attributes to User¶

In the created gcy realm, click User, select the user to which you want to add the mapping rule, and under Attributes, click Add. For example:

• Key: department
• Value: product

Configure Keycloak Mapping Fields¶

This step involves creating Client Scopes and configuring mapping fields to synchronize the mapping rules between Keycloak and Guance.

1. In the created "gcy" realm, click Client Scopes, and on the right side, click Create.

1. In Add client scope, enter the attribute field that needs to be mapped, such as “department”, and click Save.

1. Click into the created key, such as “department”, and under Mappers, click Create on the right side to create the mapping.

1. In the pop-up window Create Protocol Mappers, fill in the following details and click Save after completion.

1. In Client, click the created “Guance” client.

1. Click into it, and under Client Scopes > Setup, add the created “department” to the right side of Assigned Default Client Scopes.

Verify the Mapping Rule¶

After completing the above steps, you can log in directly to Guance via Keycloak SSO to check if the user has been added to the corresponding workspace and assigned the appropriate role.

You can also verify the mapping rules within Keycloak:

After configuring the mapping rules, go to Client > Client Scopes > Evaluate > Generated User Info to check if the mapping rules are functional. As shown in the figure below, if the configured mapping fields, such as “department”, exist, it indicates that login can be performed using these fields.

Configure Guance Management Backend Mapping Rules¶

In addition to configuring Keycloak SSO mapping rules, you also need to configure the mapping rules in the management backend. Both configurations must be completed for the mapping rules to take effect.

Go to Guance Deployment Plan Management Backend > Mapping Rules for configuration. Matching accounts will join the workspace and be granted roles based on the rules.

Use Keycloak Account to SSO Guance¶

After all configurations are complete, you can SSO to Guance.

Add Mapping Rule Attributes to User Group¶

1. In the created gcy realm, click Groups, then click New to create a new user group, such as “department”.

1. Under Attributes, click Add to add attributes, such as:

2. Key: department

3. Value: product

1. In User > Groups, click Join to add the user to the user group.

1. Start configuring the mapping rules.