OAuth2

OAuth2 に関するドキュメント

ベースパス：/api/v1/oauth2

サードパーティ連携を接続するための OAuth2 認可コードフローを処理します。フロントエンドは authorize エンドポイントへのリダイレクトでフローを開始し、連携サービスがコールバックを処理します。

OAuth2 フロー概要

text

OAuth2 認可フローを開始します。サーバーはプロバイダーの認可 URL を構築し、ユーザーをそこへリダイレクトします。

JWT が必要です（authMiddleware + activeOrgPreferenceMiddleware）。

パラメータ	型	説明
`group`	string	連携グループ/スラッグ（例：`"google-workspace"`、`"slack"`）

パラメータ	型	必須	説明
`appCallbackUrl`	string (URL)	はい	認証成功後のリダイレクト先 URL（フロントエンドのコールバック URL）
`action`	string	はい	認可する特定のアクション、またはすべてのアクションの場合は `"all"`
`scopes`	string[]	いいえ	要求する追加の OAuth2 スコープ（スペースまたはカンマ区切り、または複数パラメータ）
`token`	string	いいえ	JWT トークンのオーバーライド（リダイレクトでトークンを運ぶ場合に便利）
`baseUrl`	string	いいえ	セルフホストサービスインスタンス用のカスタムベース URL

302 Found — ブラウザを OAuth2 プロバイダーの認可 URL にリダイレクトします。

リダイレクト URL には以下が含まれます。

{ appCallbackUrl, userId, orgKey, action, scopes, baseUrl } をエンコードした state パラメータ
コールバックエンドポイントを指す redirect_uri
要求されたスコープ
PKCE パラメータ（連携で必要な場合）

javascript

ユーザーがアプリケーションを認可した後の OAuth2 プロバイダーのコールバックを処理します。認可コードをアクセス/リフレッシュトークンと交換し、保存します。

認証は不要です。 このエンドポイントは OAuth2 プロバイダーのリダイレクトによって呼び出されます。

パラメータ	型	説明
`group`	string	連携グループ/スラッグ

パラメータ	型	必須	説明
`code`	string	はい	OAuth2 プロバイダーからの認可コード
`state`	string	はい	ステートパラメータ（エンコードされたコールバック URL とコンテキストを含む）

302 Found — ステータスパラメータ付きで appCallbackUrl にリダイレクトします。

https://myapp.example.com/oauth/callback?status=success

エラー時、リダイレクトにはエラーパラメータが含まれる場合があります。

https://myapp.example.com/oauth/callback?status=error&error=access_denied

javascript

一部の連携では PKCE（Proof Key for Code Exchange）が必要です。連携のクレデンシャル設定で requiresPKCE: true が設定されている場合、サーバーは PKCE チャレンジ/ベリファイアの生成と検証を自動的に処理します。

セルフホストサービスインスタンス（例：セルフホスト GitLab、Jira）では、baseUrl パラメータを渡してトークン交換に使用するデフォルト API ベース URL をオーバーライドします。

OAuth2 スコープはアクションの scopes 設定によって決定されます。scopes クエリパラメータにより、アクションのデフォルトを超える追加スコープを要求できます。複数の scopes 値は配列またはカンマ区切り文字列として渡せます。

交換成功後：