Keycloak Single Sign-On (Deployment Plan)¶
Introduction¶
GuanceDeployment Plan supports Single Sign-On based on the OpenID Connect and OAuth 2.0 protocols. This document uses Keycloak login as an example.
Keycloak is an open-source identity and access control solution for modern applications and distributed services. GuanceDeployment Plan uses the OpenID Connect protocol to enable enterprise Keycloak accounts to perform SSO into Guanceplatform and access the corresponding workspace resources, without needing to create separate enterprise/team Guanceaccounts.
Note: This document applies to deployments using the OpenID Connect protocol with Keycloak version 18.0.2 or lower.
Concepts¶
| Term | Description |
|---|---|
| Realm | A realm, similar to a workspace, 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 users. |
| Users | User accounts that can log in to the system. Login email and Credentials must be configured. |
| Credentials | Credentials used to verify user identity, e.g., setting a 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 type of 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 | Manages user groups, supports mapping roles to groups. |
Steps¶
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 admin console, click Master > Add realm.
2) On the Add realm page, enter the realm name in the Name field, e.g., "gcy", then click Create. A new realm will be created.
2. Create a Client and Configure the OpenID Connect Protocol¶
Note: This step creates a Keycloak client and configures the OpenID Connect protocol, establishing a trust relationship between Keycloak and Guanceso they can trust each other.
1) Under the newly created "gcy" realm, click Client and then click Create on the right.
2) On the Add Client page, fill in the following information and click Save.
After the client is created, configure it as shown in the screenshot below and click Save.
- Client Protocol: openid-connect
- Access Type: confidential
- Standard Flow Enabled: ON
- Direct Access Grants Enabled: ON
- Service Accounts Enabled: ON
- Valid Redirect URIs: *
3. Configure Keycloak Users¶
4. Guance Launcher Configuration¶
1) In the Guance Launcher Namespace: forethought-core > core, configure the basic Keycloak information.
# OIDC client configuration (when wellKnowURL is configured in this set, the KeyCloakPassSet configuration item becomes invalid)
OIDCClientSet:
# OIDC Endpoints configuration URL, i.e., the full `https://xxx.xxx.com/xx/.well-known/openid-configuration` URL.
wellKnowURL:
# Client ID provided by the authentication service
clientId:
# Client Secret key
clientSecret:
# Authentication method, currently only supports authorization_code
grantType: authorization_code
verify: false
# Data access scope
scope: "openid profile email address"
# Callback URL after successful authentication by the authentication server
innerUrl: "{}://{}/oidc/callback"
# After the authentication server successfully authenticates and calls back the DF system, the DF system obtains user information and redirects to the front-end intermediate page
frontUrl: "{}://{}/tomiddlepage?uuid={}"
# Mapping configuration between account information obtained from the authentication service and DF system accounts. Required fields: username, email, exterId
mapping:
# Username of the login account in the authentication service. Required. If the value does not exist, use email.
username: preferred_username
# Email of the login account in the authentication service. Required.
email: email
# Phone number field name of the login account in the authentication service. Optional.
mobile: phone_number
# Unique identifier of the login account in the authentication service. Required.
exterId: sub
Reference example:
The "wellKnowURL:" in the example above can be obtained from Realm Settings > General > Endpoints.
The "clientSecret:" in the example can be obtained from Client > Client ID (e.g., Guance) > Credentials.
2) In the Guance Launcher Namespace: forethought-webclient > frontNginx, configure the redirect information.
# =========OIDC protocol redirect configuration start=========
# Request directly redirects to the Inner API endpoint ========= start =========
# This URL is used for third-party login access; it can be changed as needed, but the route corresponding to proxy_pass must not be modified
location /oidc/login {
proxy_connect_timeout 5;
proxy_send_timeout 5;
proxy_read_timeout 300;
proxy_http_version 1.1;
proxy_set_header Connection "keep-alive";
add_header Access-Control-Allow-Origin *;
add_header Access-Control-Allow-Headers X-Requested-With;
add_header Access-Control-Allow-Methods GET,POST,OPTIONS;
proxy_pass http://inner.forethought-core:5000/api/v1/inner/oidc/login;
}
# This URL is used for the callback from the third-party service after OIDC authentication succeeds; it is directly related to the innerUrl configuration under the OIDCClientSet configuration item in [3.2.1]; when this URL changes, it should be updated synchronously with innerUrl; the proxy_pass value must not be modified
location /oidc/callback {
proxy_connect_timeout 5;
proxy_send_timeout 5;
proxy_read_timeout 300;
proxy_http_version 1.1;
proxy_set_header Connection "keep-alive";
add_header Access-Control-Allow-Origin *;
add_header Access-Control-Allow-Headers X-Requested-With;
add_header Access-Control-Allow-Methods GET,POST,OPTIONS;
proxy_pass http://inner.forethought-core:5000/api/v1/inner/oidc/callback;
}
# =========OIDC protocol redirect configuration end=========
Reference example:
3) In the Guance Launcher Namespace: forethought-webclient > frontWeb, configure the entry URL for Keycloak users to log in to GuanceDeployment Plan.
window.DEPLOYCONFIG = {
......
paasCustomLoginInfo:[
{url:"http://Guancedeployment domain/oidc/login",label:"Keycloak Login"}
],
paasCustomLoginUrl: "https://<客户提供的注销登录地址>?redirect_url=https://GuanceWeb login domain/oidc/login"
......
};
Reference example:
4) After configuration, select the updated Modify Configuration and confirm the restart.
5. Use Keycloak Account to SSO into Guance¶
After all configurations are complete, you can use SSO to log in to Guance.
1) Open the GuanceDeployment Plan login URL, and on the login page, select Keycloak Single Sign-On.
2) Enter the email address configured in Keycloak.
3) Update the login password.
4) Log in to the corresponding workspace in Guance.
Warning
- If the message "The current account has not joined any workspace. Please go to the management console to add the account to a workspace." appears, you need to log in to the Guancemanagement console to add the workspace for the user.
For more details, refer to the document Deployment Plan Workspace Management.
After adding the workspace for the user in the Guancemanagement console, the user can start using Guance.
















