Lark and Guance (SaaS) OIDC Configuration Guide¶

This document contains two parts:

• Instructions for integrating the Lark Integration Platform (Anycross) with Guance;
• Instructions for integrating the Lark native platform with Guance.

Depending on how the application was created on the Lark side, select the configuration steps and JSON template from the corresponding section.

1. Lark Integration Platform (Anycross) Setup¶

Use Cases¶

Applicable to applications created through the Lark Integration Platform (https://anycross.feishu.cn) that use OIDC for SSO integration with Guance (SaaS).

Core Rules¶

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

Information Required from the Customer¶

claimMapping example:

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

Note: The template maps the login email to enterprise_email. Confirm that the application is authorized to access this field and that a valid email is actually returned in the target user's userinfo; do not assume this field always exists. If you use a different email field, first confirm that it meets the account identity requirements, then adjust claimMapping.email.

The current login reads the email, name, username, and mobile mappings, of which a valid email is required. The exterId mapping is not involved in this login flow, so it does not need to be specified in the template.

Lark Integration Platform Checklist¶

• Verify that the App ID and App Secret are valid.
• Obtain the service discovery URL (template field: wellKnowURL).
• The authorization mode should be authorization_code. The template starts with openid, profile, and email; check them against the service discovery information and the permissions actually granted.
• If you need the phone number or offline authorization, first confirm that the application supports and is authorized to request the corresponding phone and offline_access scopes, then add them to the template as needed; do not make these two scopes mandatory for all login scenarios.
• Confirm the authentication method used to exchange the token (client_secret_basic or client_secret_post).

Guance-Side Configuration¶

Scenario 1 — client_secret_basic (recommended)

1. Log in to Guance, go to SSO Configuration → OIDC, and enter the service discovery URL, clientId, and clientSecret.
2. Save and test SSO login.

Scenario 2 — client_secret_post

1. Refer to the official Guance "OIDC Non-Standard Configuration" section and use the JSON template below to fill in clientId, clientSecret, and wellKnowURL.
2. Import the JSON template on the OIDC non-standard configuration page in Guance, save it, and test SSO login.

JSON Template (only for the client_secret_post scenario)¶

{
  "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": "<填写 App ID>",
  "clientSecret": "<填写 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": "<填写飞书服务发现地址>",
  "claimMapping": {
    "email": "enterprise_email",
    "mobile": "mobile",
    "username": "email"
  },
  "getUserInfoSet": {
    "url": "",
    "method": "get",
    "source": "origin",
    "authMethod": "bearer",
    "paramMapping": {},
    "responseInfoPath": ""
  },
  "verifyTokenSet": {"url": "", "keys": [], "method": "get", "verify": true}
}

How to fill in the template: Fill in clientId, clientSecret, and wellKnowURL, and verify scope and claimMapping. When the url field in each endpoint is left empty, the endpoint addresses are determined from the service discovery information.

2. Lark Native Platform Setup¶

Applicable to applications created on the Lark native platform that connect to Guance (SaaS) via OIDC. Do not mix this section with the "Integration Platform" configuration.

Incompatibilities and Adaptation Reasons¶

• The Lark native platform does not support Basic authentication when exchanging the code for a token; it only supports client_secret_post (parameters passed in the POST body).
• The user information returned by Lark contains a nested data layer, so you need to set responseInfoPath to data in the template.

Information Required from the Customer¶

claimMapping example:

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

scope list example (must match the permissions actually granted on Lark):

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

Lark-Side Checklist¶

• Verify that client_id (App ID) and client_secret (App Secret) are correct.
• In Permission Management, confirm that the scope permissions listed in the template are granted and that the application has been published.
• Callback URL reservation: Guance will generate a callback URL. You need to configure this URL in the Lark application's callback URL settings and publish it.

Guance-Side Configuration and Callback Settings¶

1. On the OIDC non-standard configuration page in Guance, use the template below, fill in clientId and clientSecret, and verify the actually granted permissions and the account field mapping.
2. Confirm that getUserInfoSet.responseInfoPath is data (to adapt to Lark's response structure).
3. Import the template and save it. Copy the callback URL generated by Guance, enter it under Lark Application Development Configuration → Callback URL, and publish the application.
4. Test SSO login.

JSON Template (for Lark native platform)¶

{
  "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": "<填写 App ID>",
  "clientSecret": "<填写 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"
  },
  "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 notes: After filling in clientId and clientSecret, verify scope and the claimMapping.email field in the actual response. getTokenSet sends client credentials in the POST body, and responseInfoPath=data is used to extract user information; keep these consistent with the protocol and response structure of the integrated endpoints.

Common Issues and Troubleshooting¶

Issue 1: Invalid callback URL (Error code: 20029)¶

Symptom: redirect_uri is reported as invalid during SSO login.

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

Issue 2: Authentication failure (error: SSO account email not found)¶

Symptom: An error saying the SSO account email was not found is reported during login.

Solution: Check the user information returned by Lark (using the trace_id in the error message) and confirm the getUserInfoSet.responseInfoPath configuration:

• If the user information is in the nested data layer, keep responseInfoPath = "data";
• If the response is flat, set responseInfoPath = "" (empty string);
• After extracting that layer, confirm that the field referenced by claimMapping.email actually exists and is a valid email;
• If the email field is not returned, check the application permissions, user authorization, and the user's email information. Modifying only responseInfoPath cannot resolve a missing email field.

After making the changes, re-import the template and test.

Issue 3: Insufficient permissions (Scope configuration error)¶

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