Lark and TrueWatch (SaaS) OIDC Configuration Guide¶

This document consists of two parts:

• Integration guide for Lark Integration Platform (Anycross) and TrueWatch.
• Integration guide for Lark Native Platform and TrueWatch.

Depending on how the application is created on the Lark side, please refer to the corresponding section for configuration steps and JSON templates.

1. Lark Integration Platform (Anycross) Integration Guide¶

Use Cases¶

Applicable for SSO integration between applications created via the Lark Integration Platform (https://anycross.feishu.cn) and TrueWatch (SaaS) using OIDC.

Core Rules¶

• If the Lark application's Token authentication method is client_secret_basic: You can directly enter clientId/clientSecret in the TrueWatch UI, no need to import a JSON template (recommended).
• If the Token authentication method is client_secret_post: You need to import the JSON template in the TrueWatch "Non-OIDC Standard Configuration" section.

Information Required from the Customer¶

Fixed claimMapping:

{
  "email": "enterprise_email",
  "mobile": "mobile",
  "username": "email",
  "exterId": "enterprise_email"
}

Note: The enterprise_email returned by Lark OIDC is the corporate email, which is usually mandatory and unique. It is recommended to map the TrueWatch email to this field.

Lark Integration Platform Checklist¶

• Confirm the App ID and App Secret are valid.
• Obtain the service discovery address (Service Discovery URL, template field is wellKnowURL).
• The authorization mode should be authorization_code; Scope should include openid, profile, email, phone, offline_access.
• Confirm the Token exchange verification method (client_secret_basic or client_secret_post).

TrueWatch Configuration¶

Scenario 1 — client_secret_basic (Recommended)

1. Log in to TrueWatch, navigate to SSO Configuration → OIDC page, fill in the service discovery address, clientId, and clientSecret.
2. Save and test SSO login.

Scenario 2 — client_secret_post

1. Refer to the official TrueWatch "OIDC Non-Standard Configuration" section, use the JSON template below, filling in clientId, clientSecret, wellKnowURL.
2. Import this JSON template on the TrueWatch OIDC Non-Standard Configuration page, save, and test SSO login.

JSON Template (For client_secret_post scenario only)¶

{
  "scope": ["openid","profile","email"],
  "authSet": {
    "url": "",
    "verify": true,
    "paramMapping": {
      "scope": "$scope",
      "state": "$state",
      "client_id": "$client_id",
      "redirect_uri": "$redirect_uri",
      "response_type": "$response_type"
    }
  },
  "clientId": "<Fill in App ID>",
  "clientSecret": "<Fill in App Secret>",
  "modeType": "expert",
  "grantType": "authorization_code",
  "sslVerify": true,
  "getTokenSet": {
    "url": "",
    "method": "post",
    "verify": true,
    "authMethod": "none",
    "paramMapping": {
      "code": "$code",
      "state": "$state",
      "grant_type": "$grant_type",
      "redirect_uri": "$redirect_uri",
      "client_id": "$client_id",
      "client_secret": "$client_secret"
    }
  },
  "wellKnowURL": "<Fill in Lark service discovery address>",
  "claimMapping": {
    "email": "enterprise_email",
    "mobile": "mobile",
    "username": "email",
    "exterId": "enterprise_email"
  },
  "getUserInfoSet": {
    "url": "",
    "method": "get",
    "source": "origin",
    "authMethod": "bearer",
    "paramMapping": {},
    "responseInfoPath": ""
  },
  "verifyTokenSet": {"url": "", "keys": [], "method": "get", "verify": true}
}

Template filling instructions: Only modify clientId, clientSecret, wellKnowURL; keep other fields as default (leave all url fields empty, the service discovery address will automatically identify the interfaces).

2. Lark Native Platform Integration Guide¶

Applicable for SSO integration between applications created on the Lark Native Platform and TrueWatch (SaaS) using OIDC. Do not mix configurations from this section with the "Integration Platform" section.

Incompatibilities and Adaptation Reasons¶

• The Lark Native Platform does not support Basic authentication when exchanging Code for Token, it only supports client_secret_post (passing parameters via POST body).
• The user information returned by Lark contains a nested data layer, which needs to be specified as data in the template via responseInfoPath.

Information Required from the Customer¶

Fixed claimMapping:

{
  "email": "enterprise_email",
  "mobile": "mobile",
  "username": "email",
  "exterId": "enterprise_email"
}

Fixed scope list example (must be consistent with actual permissions enabled on Lark):

["component:user_profile","contact:user.employee_id:readonly","contact:user.email:readonly"]

Lark Side Checklist¶

• Confirm client_id (App ID) and client_secret (App Secret) are correct.
• In the permission management, confirm that the scope permissions listed in the template have been enabled and the application has been published.
• Reserve the callback address: TrueWatch will generate a callback address. You need to configure this address in the callback address settings of the Lark application and publish it.

TrueWatch Configuration and Callback Setup¶

1. On the TrueWatch OIDC Non-Standard Configuration page, use the template below, only replacing clientId and clientSecret, keep other fields unchanged.
2. Confirm getUserInfoSet.responseInfoPath is set to data (to adapt to Lark's response structure).
3. Import the template and save it. Copy the callback address generated by TrueWatch, paste it into the Lark application development configuration → Callback Address, and publish the application.
4. Test SSO login.

JSON Template (For Lark Native Platform only)¶

{
  "scope": [
    "component:user_profile",
    "contact:user.employee_id:readonly",
    "contact:user.email:readonly"
  ],
  "authSet": {
    "url": "https://accounts.feishu.cn/open-apis/authen/v1/authorize",
    "verify": true,
    "paramMapping": {
      "scope": "$scope",
      "state": "$state",
      "client_id": "$client_id",
      "redirect_uri": "$redirect_uri",
      "response_type": "$response_type"
    }
  },
  "clientId": "<Fill in App ID>",
  "clientSecret": "<Fill in App Secret>",
  "modeType": "expert",
  "grantType": "authorization_code",
  "sslVerify": true,
  "getTokenSet": {
    "url": "https://open.feishu.cn/open-apis/authen/v2/oauth/token",
    "method": "post",
    "verify": true,
    "authMethod": "none",
    "paramMapping": {
      "code": "$code",
      "state": "$state",
      "grant_type": "$grant_type",
      "redirect_uri": "$redirect_uri",
      "client_id": "$client_id",
      "client_secret": "$client_secret"
    }
  },
  "wellKnowURL": "",
  "claimMapping": {
    "email": "enterprise_email",
    "mobile": "mobile",
    "username": "email",
    "exterId": "enterprise_email"
  },
  "getUserInfoSet": {
    "url": "https://open.feishu.cn/open-apis/authen/v1/user_info",
    "method": "get",
    "source": "origin",
    "authMethod": "bearer",
    "paramMapping": {},
    "responseInfoPath": "data"
  },
  "verifyTokenSet": {"url": "", "keys": [], "method": "get", "verify": true}
}

Template instructions: Only modify clientId and clientSecret; other fields are fixed configurations for Lark's official platform, do not change them.

Common Issues and Troubleshooting¶

Issue 1: Invalid Callback Address (Error Code: 20029)¶

Symptom: SSO login prompts redirect_uri is invalid.

Solution: Copy the system-generated callback address from the TrueWatch SSO configuration page (do not modify it manually), paste it into the callback address configuration of the Lark application and publish it. Then refresh the configuration in TrueWatch and retry.

Issue 2: Authentication Failed (Prompt: SSO account email not found)¶

Symptom: Login error reports SSO account email not found.

Solution: Check the user information returned by Lark (via the trace_id in the error), confirm the configuration of getUserInfoSet.responseInfoPath:

• If user information is in the nested data layer, keep responseInfoPath = "data";
• If the response is a flat structure, set responseInfoPath = "" (empty string).

After modification, re-import the template and test.

Issue 3: Insufficient Permissions (Scope Configuration Exception)¶

Solution: Confirm that the Lark application has enabled the scope permissions listed in the template and has been published; ensure the scope list in the JSON template exactly matches the Lark side, then re-import and save.