Single Sign-On-OAuth 2.0

1. OAuth 2.0 Overview

OAuth is a single sign-on protocol. By configuration, Guandata Data can be integrated with OAuth authentication service providers for authentication and authorization, allowing users to log in to Guandata Data through unified accounts provided or self-built by the organization.

2. OAuth 2.0 Standard Configuration Steps

2.1 Preparation

(1) Confirm whether the unified authentication service used provides a standard OAuth2 protocol. If not, customization may be required.

(2) Confirm the OAuth authentication callback address for Guandata Data Platform (needed when configuring the application on the authentication server):

  ${BI service address}/standard-oauth2/authenticate

(3) The authentication server provides the following information:

• Authentication server address: The address provided by the authentication service provider, usually the page for user input of credentials/QR code (to obtain Code)

  e.g.: http://xxx.guandata.com/auth/realms/guandata/protocol/openid-connect/auth

• AccessToken acquisition address: The URL to request the token from the authentication service provider (to exchange Code for Token)

  e.g.: http://xxx.guandata.com/auth/realms/guandata/protocol/openid-connect/token

• User info acquisition address: The URL to request user info from the authentication service provider (to exchange Token for user info)

  e.g.: http://xxx.guandata.com/auth/realms/guandata/protocol/openid-connect/userinfo

• Logout address (optional): The address to log out the current user from SSO

• ClientID: Client ID of the authentication provider

• ClientSecret: Client secret of the authentication provider

• BindKey: The field in the returned user info used to match with BI users, e.g., email

(3) Ensure BI server and SSO authentication server are network accessible.

2.2 Modify Configuration

(1) Go to Management Center > System Settings > Login Settings > Single Sign-On, select SSO method: OAuth

(2) Edit OAuth configuration

• Authentication Protocol: OAuth 2.0
• ClientId: Client ID of the authentication provider
• ClientSecret: Client secret of the authentication provider
• Authorization URL: The address provided by the authentication service provider, usually the page for user input of credentials/QR code
• Callback address (optional, depends on whether the authentication service interface requires redirect_uri): ${BI service address}/standard-oauth2/authenticate
• AccessToken URL: The URL to request the token from the authentication service provider (to exchange Code for Token). Token can be transmitted in the request Header
• User info URL: The URL to request user info from the authentication service provider (to exchange token for user info). Token can be passed in the URL, header, or post body as ${accessToken}
  • Three ways to pass the token:
    • Method 1: Pass in the URL, e.g., GET: https://www.xx.com/auth/userinfo?token=${accessToken}
    • Method 2: Pass in the request Header, must include ${accessToken} in the value, e.g.:

* Method 3: Pass in the request Post body, must include ${accessToken} in the JSON line, e.g.:

• User info field (UserIDKey): The field in the user info used to map to BI users, e.g., email

(3) Default login address and login redirect (optional)

• Default login address: ${BI service address}/standard-oauth2/authenticate
• If you provide a logout URL, enable logout redirect and set the address to your LogoutURL (usually the SSO logout address)

If the value of the user info field does not match the already created user account, go to System Settings > Login Settings > External Account Mapping to configure the mapping table in BI.

3. Test Process

• Visit ${BI service address}/standard-oauth2/authenticate, which will automatically redirect to the SSO login authentication page, e.g., Keycloak:

• After entering the correct credentials, it will redirect back to BI and confirm that the logged-in user is the SSO user bound in the SSO table

• If a logout address is configured, logging out in BI will also log out in SSO and return to the SSO login page