OIDC¶

This document describes how to configure single sign-on (SSO) based on the OIDC/OAuth 2.0 protocol in the TrueWatch workspace.

TrueWatch supports two OIDC configuration methods:

Standard OIDC Configuration: Suitable for identity providers compliant with the OpenID Connect standard.

Non-standard OIDC Configuration: Suitable for identity providers based on OAuth 2.0 but with different interface specifications.

Prerequisites¶

Before starting the configuration, ensure you have prepared the following:

Standard OIDC Configuration¶

Step 1: Access the Configuration Page¶

1. Navigate to Manage > Member Management > SSO Management > User SSO.
2. Select the OIDC access type.
3. Click Add Identity Provider.

Step 2: Connection Configuration¶

1. Identity Provider Name: The name of the platform providing identity management services (❗️ This name will serve as the IdP alias and appear on the SSO IdP selection screen. To ensure you can quickly locate the desired IdP for login, please provide an appropriate name).
2. Remarks: User-defined descriptive information for recording notes about the identity provider.
3. Identity Provider URL: The complete URL of the identity provider, also the service discovery address. For example: https://guance.example.com.
4. Client ID: A unique identifier provided by the authentication service, used to identify the client application.
5. Client Secret: Used in conjunction with the Client ID to authenticate the client application.
6. Authorization Request Scope: The scope of the authorization request. By default includes openid, profile, and email. Additional claims like address and phone can be added as needed.

Step 3: Mapping Configuration¶

To implement SSO login, it is necessary to map the account information fields from the identity provider (IdP) to the TrueWatch account information fields. The main fields are as follows:

1. Username: Required. The "username" field from the identity provider, e.g., referred_username.
2. Email: Required. The "email" field from the identity provider, e.g., email.
3. Phone Number: Optional. The "phone number" field from the identity provider, e.g., phone.

Step 4: Login Control¶

1. Access Restriction: Validates whether the domain suffix of the login email matches the configured domain. Only emails matching the suffix have permission to access the SSO login link. For users logging in for the first time, a TrueWatch member account can be dynamically created without needing to be pre-created in the workspace.
2. Role Assignment: Assigns a role to SSO accounts logging in for the first time. Accounts that are not logging in for the first time are not affected.
   • If SAML Mapping is enabled in the workspace, role assignment follows the mapping rules first.
3. Session Persistence: Sets the idle session timeout and maximum session duration for SSO login sessions.

Session Persistence Configuration¶

After modifying the session persistence time, logged-in members retain the original settings, while new logins will follow the latest settings.

Relationship Between Role Assignment and Role Mapping¶

• If the workspace has not enabled OIDC Role Mapping: All SSO users logging in for the first time receive the default role configured here.
• If the workspace has enabled OIDC Role Mapping: Role assignment follows the mapping rules first. Users not matching any rule receive the default role configured here.

Notes on OIDC-related Configuration on the User Side¶

• Authorization Mode: Only the authorization_code authorization mode is supported; its response type must be code.
• id_token Signature Algorithm: Currently only HS256 is supported.
• Authentication Method for Exchanging code for token:
  • Default support: client_secret_basic
  • Custom method support: client_secret_post, client_secret_basic, none
• scope Range:
  • Default scope: openid, profile, email, phone
  • Custom requirements: Must include openid. Others can be customized, but the returned result must include email, and phone_number can be optionally returned.

Step 5: Obtain Callback URLs¶

After successfully creating the identity provider, click the Edit button to obtain the following URLs and provide them to your IdP:

1. Callback URL: The address to which TrueWatch redirects after successful IdP authorization.
2. Login Initiation URL: The SSO login entry address for TrueWatch.

Step 6: Configure Callback Address in IdP¶

Based on the callback URL obtained in Step 5, complete the following configuration in your IdP:

1. Callback Address (Redirect URI): Enter the callback URL provided by TrueWatch.
2. Authorization Mode: Ensure support for authorization_code.
3. Response Type: Ensure support for code.

Non-standard OIDC Configuration¶

Suitable for identity providers based on OAuth 2.0 but not compliant with standard OIDC specifications. Common in the following scenarios:

• The IdP does not provide a standard OIDC discovery endpoint (.well-known/openid-configuration).
• The interface path or return format for obtaining user information differs from standard OIDC.
• The case style of interface parameters is inconsistent with the standard.

Configuration Steps¶

1. Navigate to Manage > Member Management > SSO Management > OIDC > Create Identity Provider.
2. Click the button in the top right corner to switch to the standard OIDC configuration page.
3. Connection Configuration:
   • Identity Provider Name: Custom display name (limited to 64 characters).
   • Configuration File Upload: Download the template, fill in information such as authorization endpoint, token endpoint, userinfo endpoint, field mapping, etc., and then upload it.
   • Remarks: User-defined descriptive information for recording notes about the identity provider.
4. Login Configuration: Configuration is the same as standard OIDC (Access Restriction, Role Assignment, Session Persistence).
5. Save and enable.

Login Verification¶

1. Access the TrueWatch SSO page via email login: https://auth.truewatch.com/login/sso.
2. Enter the email address configured during SSO creation and select the IDP to which the workspace you want to log in belongs.
3. After successful authentication, you will be redirected to the workspace selection screen.
4. Log in to that address.
5. Enter your username, password, and other information.
6. Login successful.

Notes¶

1. When role mapping is enabled: If a user does not match any role mapping rule, or if role mapping is disabled, they will receive a "No access permission" prompt upon login.
2. After deleting an identity provider: Users will not see workspaces associated with the deleted IdP when logging in via SSO.
3. Multiple IdP Configuration: A single workspace supports up to 10 IdPs. A user's email domain matching any configured IdP is sufficient for login.
4. Account Binding: During the first SSO login, if the email matches an existing TrueWatch account, automatic binding occurs, and historical data is preserved.
5. Mapping Field Errors: If the configured mapping fields do not match the actual fields returned by the IdP, user information cannot be retrieved, leading to login failure.

Further Reading¶

You might also be interested in: