Lark と Guance（SaaS）OIDC 設定ガイド¶

本ドキュメントは次の2部構成です。

Lark 統合プラットフォーム（Anycross）と Guance の連携手順
Lark ネイティブプラットフォームと Guance の連携手順

Lark 側でのアプリの作成方法に応じて、該当するセクションの設定手順と JSON テンプレートをご利用ください。

一、Lark 統合プラットフォーム（Anycross）連携手順¶

適用対象¶

Lark 統合プラットフォーム（https://anycross.feishu.cn）创建的应用与）と Guance（SaaS）を OIDC で SSO 連携する場合に適用します。

基本ルール¶

Lark アプリの Token 認証方式が client_secret_basic の場合：Guance UI 上で clientId / clientSecret を直接入力できます。JSON テンプレートのインポートは不要です（推奨）。
認証方式が client_secret_post の場合：Guance の「非 OIDC 標準設定」で JSON テンプレートをインポートする必要があります。

お客様側で準備いただく情報¶

情報項目	説明
clientId	アプリのクライアント ID（App ID）
clientSecret	アプリのクライアントシークレット（App Secret）
scope	テンプレートのデフォルト権限（変更不要）
claimMapping	アカウント情報のマッピング（固定）

固定の claimMapping：

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

説明：Lark OIDC が返す enterprise_email は企業メールアドレスで、通常必ず存在し一意です。Guance の email にはこのフィールドをマッピングすることを推奨します。

Lark 統合プラットフォーム側の確認項目¶

App ID、App Secret が有効であることを確認します。
サービスディスカバリ URL（テンプレート内フィールド：wellKnowURL）を取得します。
認可モードは authorization_code とします。Scope には openid、profile、email、phone、offline_access を含めます。
Token 交換時の認証方式（client_secret_basic または client_secret_post）を確認します。

Guance 側の設定¶

シナリオ 1 — client_secret_basic（推奨）

Guance にログインし、SSO 設定 → OIDC ページでサービスディスカバリ URL、clientId、clientSecret を入力します。
保存し、SSO ログインをテストします。

シナリオ 2 — client_secret_post

Guance 公式ドキュメントの「OIDC 非標準設定」セクションを参照し、以下の JSON テンプレートを使用して clientId、clientSecret、wellKnowURL を設定します。
Guance の OIDC 非標準設定ページでこの JSON テンプレートをインポートして保存し、SSO ログインをテストします。

JSON テンプレート（client_secret_post シナリオのみ）¶

{
  "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",
    "exterId": "enterprise_email"
  },
  "getUserInfoSet": {
    "url": "",
    "method": "get",
    "source": "origin",
    "authMethod": "bearer",
    "paramMapping": {},
    "responseInfoPath": ""
  },
  "verifyTokenSet": {"url": "", "keys": [], "method": "get", "verify": true}
}

テンプレート設定の注意事項：clientId、clientSecret、wellKnowURL のみを変更してください。その他のフィールドはデフォルトのままにします（すべての url フィールドは空欄のままにし、サービスディスカバリ URL が自動的にインターフェースを識別します）。

二、Lark ネイティブプラットフォーム連携手順¶

Lark ネイティブプラットフォームで作成したアプリと Guance（SaaS）を OIDC で連携する場合に適用します。本セクションの設定を「統合プラットフォーム」の設定と混在させないでください。

非互換ポイントとその理由¶

Lark ネイティブプラットフォームは、Code を Token と交換する際に Basic 認証をサポートしておらず、client_secret_post（POST body でのパラメータ送信）のみをサポートしています。
Lark が返すユーザ情報には data のネスト層が含まれるため、テンプレート内で responseInfoPath を data に指定する必要があります。

お客様側で準備いただく情報¶

情報項目	説明
clientId	App ID
clientSecret	App Secret
scope	固定の権限リスト。Lark 側で実際に有効化した権限と一致させる必要があります
claimMapping	アカウントマッピング（固定）

固定の claimMapping：

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

固定の scope リスト例（Lark 側で実際に有効化した権限と必ず一致させてください）：

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

Lark 側の確認項目¶

client_id（App ID）と client_secret（App Secret）が正しいことを確認します。
権限管理で、テンプレートに記載された scope の権限が有効化され、アプリが公開されていることを確認します。
コールバック URL の予約：Guance が生成するコールバック URL を、Lark アプリのコールバック URL に設定し、公開します。

Guance 側の設定とコールバック設定¶

Guance の OIDC 非標準設定ページで以下のテンプレートを使用し、clientId と clientSecret のみを置き換え、他のフィールドは変更しないでください。
getUserInfoSet.responseInfoPath が data であることを確認します（Lark の返却構造に適合）。
テンプレートをインポートして保存し、Guance が生成したコールバック URL をコピーして、Lark アプリの開発設定 → コールバック URL に設定し、アプリを公開します。
SSO ログインをテストします。

JSON テンプレート（Lark ネイティブプラットフォーム専用）¶

{
  "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",
    "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}
}

テンプレートの説明：clientId と clientSecret のみを変更してください。その他のフィールドは Lark 公式の固定設定であるため、変更しないでください。

よくある質問とトラブルシューティング¶

問題 1：コールバック URL が無効（エラーコード：20029）¶

現象：SSO ログイン時に redirect_uri が無効であると表示されます。

解決策：Guance SSO 設定ページからシステム生成のコールバック URL をコピーし（手動で変更しないでください）、Lark アプリのコールバック URL 設定に貼り付けて公開します。その後、Guance で設定を更新して再試行してください。

問題 2：認証失敗（「sso アカウントのメールアドレスが見つかりません」と表示）¶

現象：ログイン時に SSO アカウントのメールアドレスが見つからないとエラーが表示されます。

解決策：Lark から返されたユーザ情報（エラーメッセージ内の trace_id で確認）を確認し、getUserInfoSet.responseInfoPath の設定を確認してください。

ユーザ情報が data のネスト層にある場合は、responseInfoPath = "data" を維持します。
返却がフラットな構造の場合は、responseInfoPath = ""（空文字列）を設定します。

修正後、テンプレートを再インポートしてテストしてください。

問題 3：権限不足（Scope 設定の異常）¶

解決策：Lark アプリでテンプレートに記載された scope の権限が有効化され、アプリが公開されていることを確認します。JSON テンプレート内の scope リストが Lark 側と完全に一致していることを確認し、再インポートして保存してください。

Lark と Guance（SaaS）OIDC 設定ガイド¶

一、Lark 統合プラットフォーム（Anycross）連携手順¶

適用対象¶

基本ルール¶

お客様側で準備いただく情報¶

Lark 統合プラットフォーム側の確認項目¶

Guance 側の設定¶

JSON テンプレート（client_secret_post シナリオのみ）¶

二、Lark ネイティブプラットフォーム連携手順¶

非互換ポイントとその理由¶

お客様側で準備いただく情報¶

Lark 側の確認項目¶

Guance 側の設定とコールバック設定¶

JSON テンプレート（Lark ネイティブプラットフォーム専用）¶

よくある質問とトラブルシューティング¶

問題 1：コールバック URL が無効（エラーコード：20029）¶

問題 2：認証失敗（「sso アカウントのメールアドレスが見つかりません」と表示）¶

問題 3：権限不足（Scope 設定の異常）¶

このページは役に立ちましたか？ ×

このページは役に立ちましたか？