Skip to main content

OAuth Single Sign-On Configuration Guide

Overview​

This document provides detailed instructions on configuring OAuth 2.0 Single Sign-On (SSO) parameters in the system.

Configuration Parameters​

1. Icon​

  • Required: Yes
  • Type: Image file, supports common image formats (PNG, JPG, SVG, etc.)
  • Purpose: Logo of the OAuth provider, displayed on the login page

2. Name​

  • Required: Yes
  • Type: String, custom defined by administrator, like GitHub, Lark, SSO
  • Purpose: Display name for the OAuth configuration, used to identify the OAuth provider in admin interface and login page

3. Client ID​

  • Required: Yes
  • Type: String
  • Purpose: OAuth 2.0 standard parameter used to identify your application

4. Client Secret​

  • Required: Yes
  • Type: String (password), obtained together with Client ID from the OAuth provider's developer console
  • Purpose: OAuth 2.0 standard parameter, secret key used to authenticate the application identity

5. Authorize URL​

  • Required: Yes
  • Type: URL string, must start with http:// or https://
  • Purpose: First step of OAuth 2.0 authorization code flow, users will be redirected to this URL for login authorization

6. Token URL​

  • Required: Yes
  • Type: URL string, must start with http:// or https://
  • Purpose: Second step of OAuth 2.0 authorization code flow, exchange authorization code for access token

7. User Info URL​

  • Required: Yes
  • Type: URL string, must start with http:// or https://
  • Purpose: API endpoint to retrieve user basic information using the access token

8. Redirect URL​

  • Required: Yes
  • Type: URL string, must start with http:// or https://
  • Purpose: After OAuth authorization is complete, the provider will redirect users back to your application at this URL

9. Scope​

  • Required: No
  • Type: String
  • Purpose: Specifies the scope of user data permissions the application requests to access

10. User Info Mapping Type​

  • Required: Yes
  • Type: Enum value
  • Available Values:
    • GITHUB: GitHub platform
    • LARK: Lark (Feishu) platform
    • CUSTOM: Custom mapping rules
  • Purpose: Specifies how to extract required fields from user information returned by the OAuth provider

11. Custom Mapping Rules​

  • Required: Required when type is CUSTOM
  • Type: JSON string, format detailed in Custom Mapping Rules Details
  • Purpose: Defines how to extract username and email from the user information returned by the OAuth provider

12. Role Configuration​

  • Required: Yes
  • Type: Array
  • Purpose: Specifies system roles and permissions that will be assigned to users logging in through this OAuth configuration

Custom Mapping Rules Details​

Use Cases​

Custom mapping rules are needed when your OAuth provider is not GitHub or Lark, or when the provider's user information format does not conform to the standard.

Mapping Rule Format​

Mapping rules must be a valid JSON object containing the following required fields:

{
  "name": "Path to extract username",
  "email": "Path to extract email",
  "nickname": "Path to extract nickname (optional)",
  "phone": "Path to extract phone number (optional)",
  "description": "Path to extract description (optional)"
}

JSON Pointer Expression Syntax​

The system uses the JSON Pointer standard (RFC 6901) to extract fields from user information responses.

Basic Syntax​

JSON Pointer uses forward slash / as a separator to represent object hierarchy:

ExpressionDescriptionExample
/fieldExtract field from root object/name
/object/fieldExtract field from nested object/user/email
/array/0Extract first element of array (index starts from 0)/emails/0
/array/0/fieldExtract field from array element/emails/0/value
`` (empty string)Represents entire document``

Special Character Escaping​

JSON Pointer requires escaping of two special characters:

  • ~0 represents literal character ~
  • ~1 represents literal character /

Examples:

  • For field name a/b, use /a~1b
  • For field name m~n, use /m~0n
  • For field name c~d/e, use /c~0d~1e

Configuration Examples​

Example 1: Simple Field Extraction​

User information returned by OAuth provider:

{
  "username": "john_doe",
  "email": "john@example.com",
  "id": 12345
}

Mapping Rule Configuration:

{
  "name": "/username",
  "email": "/email"
}

Explanation: Directly extract username and email fields from root object

Example 2: Nested Object Extraction​

User information returned by OAuth provider:

{
  "user_info": {
    "display_name": "John Doe",
    "contact": {
      "email": "john@example.com"
    }
  }
}

Mapping Rule Configuration:

{
  "name": "/user_info/display_name",
  "email": "/user_info/contact/email"
}

Explanation: Use / to separate each object layer, accessing nested fields level by level

Debugging Recommendations​

  1. Review Provider Documentation: Carefully read the OAuth provider's user info API documentation

  2. Actual Testing: Use Postman or curl to call the user info API and examine the actual returned data structure

    curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
         https://api.provider.com/user

  3. Build Incrementally: Configure simple fields first, then handle complex nesting after successful testing

  4. Use Online Tools: JSON Pointer online testing tools can be used to validate expressions

  5. Note Array Indexing: Array indices start from 0, use /array/0 to access the first element

  6. Check Field Name Case: JSON Pointer paths are case-sensitive

  7. Verify Escaping: If field names contain ~ or /, ensure proper escaping

Configuration Process​

Step 1: Register Application with OAuth Provider​

  1. Visit the OAuth provider's developer console
  2. Create a new OAuth application
  3. Record the Client ID and Client Secret
  4. Configure the Redirect URL

Step 2: Create OAuth Configuration in System​

  1. Go to Admin Console → User Management → OAuth
  2. Click "Add OAuth Config" button
  3. Upload the OAuth provider's icon
  4. Fill in the configuration name
  5. Enter the Client ID and Client Secret obtained from Step 1
  6. Fill in URL configurations according to provider documentation:
    • Authorize URL
    • Token URL
    • User Info URL
    • Redirect URL
  7. Configure permission scope (Scope)
  8. Select user info mapping type:
    • If GitHub or Lark, select the corresponding option directly
    • For other providers, select "Custom" and configure mapping rules
  9. Assign role permissions
  10. Save configuration

Step 3: Test Login​

  1. Log out of current account
  2. Find the newly configured OAuth option on the login page
  3. Click login and verify the flow works correctly
  4. Check if user information is correctly extracted after login