Skip to content

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).

  1. In the Keycloak Admin Console, click Master > Add realm.

  1. 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.

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

  1. 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

  1. 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.

  1. 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:

  1. 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:

  1. 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.

  1. Open the login address of the Guance Deployment Plan and select Keycloak SSO on the login page.

  1. Enter the email address configured in Keycloak.

  1. Update the login password.

  1. 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.

Feedback

Is this page helpful?