Lark と Guance（SaaS）の OIDC 設定について¶

本ドキュメントには次の 2 つの部分があります。

• Lark 統合プラットフォーム（Anycross）と Guance の連携について
• Lark ネイティブプラットフォームと Guance の連携について

アプリの作成方法（Lark 側）に応じて、該当する章の設定手順と JSON テンプレートを使用してください。

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

ユースケース¶

Lark 統合プラットフォーム（https://anycross.feishu.cn）で作成したアプリと Guance（SaaS）を OIDC で SSO 連携する場合に適用します。

基本ルール¶

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

お客様が準備する情報¶

claimMapping の例：

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

説明：このテンプレートでは、ログイン用メールアドレスを enterprise_email にマッピングします。アプリにこのフィールドの取得権限があり、対象ユーザーの実際の userinfo に有効なメールアドレスが返されることを確認してください。このフィールドが必ず存在するとは想定できません。別のメールフィールドを使用する場合は、それがアカウントの識別要件を満たすことを確認してから claimMapping.email を調整してください。

現在のログインでは email、name、username、mobile のマッピングが読み取られます。このうち有効なメールアドレスが必須です。exterId マッピングはこのログインフローでは使用されないため、テンプレートに記入する必要はありません。

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

• App ID、App Secret が有効であることを確認します。
• サービスディスカバリの URL（テンプレートのフィールド名は wellKnowURL）を取得します。
• 認可モードは authorization_code である必要があります。テンプレートは openid、profile、email を起点としているため、サービスディスカバリ情報と実際に開通している権限に照らして確認してください。
• 携帯電話番号やオフライン認可が必要な場合は、アプリが対応する phone、offline_access スコープのリクエストをサポートし、許可されていることを確認してから、必要に応じてテンプレートに追加してください。これらの 2 つのスコープをすべてのログインシナリオで必須にしないでください。
• Token 取得時の認証方式（client_secret_basic または client_secret_post）を確認します。

Guance 側の設定¶

シナリオ 1 — client_secret_basic（推奨）

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

シナリオ 2 — client_secret_post

1. Guance 公式の「OIDC 非標準設定」の章を参照し、以下の JSON テンプレートを使用して clientId、clientSecret、wellKnowURL を入力します。
2. 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"
  },
  "getUserInfoSet": {
    "url": "",
    "method": "get",
    "source": "origin",
    "authMethod": "bearer",
    "paramMapping": {},
    "responseInfoPath": ""
  },
  "verifyTokenSet": {"url": "", "keys": [], "method": "get", "verify": true}
}

テンプレートの入力について：clientId、clientSecret、wellKnowURL を入力し、scope と claimMapping を確認します。各 API の url フィールドが空の場合は、サービスディスカバリ情報から API のエンドポイントを特定します。

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

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

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

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

お客様が準備する情報¶

claimMapping の例：

{
  "email": "enterprise_email",
  "mobile": "mobile",
  "username": "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 を生成するため、その URL を Lark アプリのコールバック URL に設定して公開する必要があります。

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

1. Guance の OIDC 非標準設定ページで以下のテンプレートを使用し、clientId と clientSecret を入力して、実際に開通している権限とアカウントフィールドのマッピングを確認します。
2. getUserInfoSet.responseInfoPath が data（Lark のレスポンス構造に適合）であることを確認します。
3. テンプレートをインポートして保存し、Guance が生成したコールバック URL をコピーして、Lark アプリの開発設定 → コールバック URL に貼り付け、アプリを公開します。
4. 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"
  },
  "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 を入力したら、scope と実際に返される claimMapping.email フィールドを確認します。getTokenSet は POST body でクライアントの認証情報を送信し、responseInfoPath=data でユーザー情報を取得します。これらは接続する API のプロトコルおよびレスポンス構造と一致させる必要があります。

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

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

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

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

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

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

対処：Lark が返したユーザー情報（エラーに含まれる trace_id を使用）を確認し、getUserInfoSet.responseInfoPath の設定を確認します。

• ユーザー情報が data のネスト層にある場合は、responseInfoPath = "data" のままにします。
• レスポンスがフラットな構造の場合は、responseInfoPath = ""（空文字列）に設定します。
• その層を取得した後に、claimMapping.email が指すフィールドが実際に存在し、有効なメールアドレスであることを確認します。
• メールアドレスフィールドが返されない場合は、アプリの権限、ユーザーの認可、ユーザーのメールアドレス情報を確認します。responseInfoPath の変更だけではメールアドレスフィールドの欠落は解決できません。

変更後にテンプレートを再インポートしてテストします。

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

対処：Lark アプリでテンプレートに記載された scope の権限が開通済みで、アプリが公開されていることを確認します。JSON テンプレートの scope リストが Lark 側と完全に一致していることを確認し、再インポートして保存します。