Keycloak Single Sign-On (Deployment Plan)¶
Introduction¶
Guance Deployment Plan supports single sign-on based on two protocols: OpenID Connect and OAuth 2.0. This document uses Keycloak login as an example.
Keycloak is an open-source identity authentication and access control solution for modern applications and distributed services. The Guance Deployment Plan implements single sign-on for enterprise Keycloak accounts to the Guance platform through the OpenID Connect protocol, allowing users to access the corresponding Workspace resources without creating separate enterprise/team Guance accounts.
Note: This document applies to Keycloak versions 18.0.2 and earlier that use the OpenID Connect protocol.
Concepts¶
| Term | Description |
|---|---|
| Realm | A realm is similar to a Workspace. It is used to manage users, credentials, roles, and user groups. Realms are isolated from one another. |
| Clients | A client is an application or service that can request Keycloak to authenticate users. |
| Users | User accounts that can log in to the system. A login email and credentials must be configured. |
| Credentials | Credentials used to verify user identity. They can also be used to set the login password for user accounts. |
| Authentication | The process of identifying and verifying users. |
| Authorization | The process of granting access permissions to users. |
| Roles | Used to identify the identity type of a user, such as administrator, ordinary user, etc. |
| User role mapping | The mapping relationship between users and roles. A user can be associated with multiple roles. |
| Groups | Used to manage user groups and supports mapping roles to groups. |
Steps¶
1. Create a Keycloak Realm¶
Note: Keycloak has its own master realm (Master). We need to create a new realm (similar to a Workspace).
- In the Keycloak Admin Console, click Master > Add realm.
- On the Add realm page, enter a realm name in Name, such as
gcy, and click Create. A new realm is then 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 Guance.
- In the newly created
gcyrealm, click Client, then click Create on the right.
- In Add Client, complete the following information and click Save.
After the Client is created, configure it as shown in the following screenshot 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¶
- Configure the basic Keycloak information in Guance Launcher under namespace: forethought-core > core.
# OIDC client configuration (when wellKnowURL is configured in this section, the KeyCloakPassSet configuration automatically becomes invalid)
OIDCClientSet:
# OIDC Endpoints configuration URL, that is, the complete `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 authorization_code is supported
grantType: authorization_code
verify: false
# Data access scope
scope: "openid profile email address"
# Callback URL after successful authentication on the authentication server
innerUrl: "{}://{}/oidc/callback"
# The URL to which the DF system redirects to the front-end middle page after the authentication service successfully authenticates and calls back to the DF system with user information
frontUrl: "{}://{}/tomiddlepage?uuid={}"
# Mapping configuration between the account information obtained from the authentication service and DF system accounts. Required fields: username, email, exterId
mapping:
# The username of the login account in the authentication service. Required. If this value does not exist, email is used.
username: preferred_username
# The email of the login account in the authentication service. Required.
email: email
# The phone number field name of the login account in the authentication service. Optional.
mobile: phone_number
# The unique identifier of the login account in the authentication service. Required.
exterId: sub
Refer to the example screenshot:
The wellKnowURL: value in the example above can be obtained from Realm Settings > General > Endpoints.
or
The clientSecret: value in the example can be obtained from Client > Client ID (for example, Guance) > Credentials.
- Configure the redirect information in Guance Launcher under namespace: forethought-webclient > frontNginx.
# =========Start of OIDC protocol redirect configuration=========
# Interface that directly redirects requests to the Inner API =========Start=========
# This address is the access URL for third-party login. You can change it as needed, but the route address corresponding to proxy_pass cannot be changed.
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 address is used for the callback to this service after a third-party service passes authentication through the OIDC protocol. It is directly associated with the innerUrl configuration under the OIDCClientSet configuration in [3.2.1]. When this address changes, it must be changed in sync with innerUrl. The value corresponding to proxy_pass cannot be changed.
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;
}
# =========End of OIDC protocol redirect configuration=========
Refer to the example screenshot:
- In Guance Launcher, under namespace: forethought-webclient > frontWeb, configure the entry URL for Keycloak users to log in to the Guance Deployment Plan.
window.DEPLOYCONFIG = {
......
paasCustomLoginInfo:[
{url:"http://Guance-deployment-domain/oidc/login",label:"Keycloak Login"}
],
paasCustomLoginUrl: "https://<logout-address-provided-by-customer>?redirect_url=https://Guance-web-login-domain-address/oidc/login"
......
};
Refer to the example screenshot:
- After the configuration is complete, check Modify Configuration and confirm the restart.
5. Single Sign-On to Guance with a Keycloak Account¶
After all configurations are complete, you can log in to Guance via single sign-on.
- Open the login address of the Guance Deployment Plan and select Keycloak SSO on the login page.
- Enter the email address configured in Keycloak.
- Update the login password.
- Log in to the corresponding Workspace of Guance.
Warning
- If the message “The current account has not joined any Workspace. Please go to the Admin Console and add this account to a Workspace.” is displayed, you need to log in to the Guance Admin Console and add a Workspace for the user.
For more details, refer to the document Deployment Plan Workspace Management.
After you add a Workspace for the user in the Guance Admin Console, the user can start using Guance.















