サードパーティトークンの保存 & API アクセス

サードパーティトークンセット（別名：フェデレーテッドトークンセット）は、Logto のシークレットボールトに保存されるシークレットタイプであり、サードパーティのアイデンティティプロバイダーによって発行されたアクセストークン (Access token) およびリフレッシュトークン (Refresh token) を安全に管理するために使用されます。ユーザーがソーシャルまたはエンタープライズシングルサインオン (SSO) コネクター経由で認証 (Authentication) すると、Logto は発行されたトークンをボールトに保存します。これらのトークンは後で取得でき、再認証なしでユーザーの代理としてサードパーティ API にアクセスできます。

主なユースケース

この機能は、AI エージェント、SaaS プラットフォーム、生産性ツール、顧客向けアプリケーションなど、ユーザーの代理でサードパーティサービスと連携する必要がある現代的なアプリケーションに不可欠です。実際の例をいくつか紹介します：

📅 カレンダー管理アプリ：ユーザーが Google でサインインした後、生産性アプリが自動的にカレンダーイベントを同期し、新しい会議を作成し、招待状を送信できます。再度認証 (Authentication) を求める必要はありません。

🤖 AI アシスタント：AI エージェントがユーザーの GitHub リポジトリにアクセスし、コードを分析したり、プルリクエストを作成したり、課題を管理したりできます。すべてサインインやアカウント連携時の一度きりの同意で実現します。

📊 分析ダッシュボード：SaaS プラットフォームがユーザーの接続済みソーシャルメディアアカウント（Facebook、LinkedIn など）からデータを取得し、ワークフローを中断することなくインサイトやレポートを生成できます。

サードパーティトークンの保存を有効化する

この機能は、トークン保存をサポートするソーシャルコネクターで利用できます。サードパーティトークンは、ソーシャルサインイン、ソーシャルアカウント連携、およびサードパーティ API アクセス用トークンの更新時に保存できます。現在サポートされているコネクターは：GitHub、Google、Facebook、標準 OAuth 2.0、標準 OIDC です。今後、他のコネクターへの対応も順次拡大予定です。

コンソール > コネクター > ソーシャルコネクターに移動します。
サードパーティトークンの保存を有効にしたいソーシャルコネクターを選択します。
コネクターのセットアップチュートリアルに従い、特定のサードパーティ API へアクセスするために必要なスコープを追加します。
「設定」ページで 永続的な API アクセスのためにトークンを保存 オプションを有効にします。

エンタープライズ SSO コネクター

トークン保存は、すべての OIDC エンタープライズコネクターで利用できます。アクセストークン (Access token) およびリフレッシュトークン (Refresh token) は、エンタープライズシングルサインオン (SSO) 時に保存できます。現在サポートされているコネクターは：Google Workspace、Microsoft Entra ID (OIDC)、Okta、OIDC (Enterprise) です。

コンソール > エンタープライズ SSO に移動します。
サードパーティトークンの保存を有効にしたいエンタープライズ SSO コネクターを選択します。
コネクターのセットアップチュートリアルに従い、特定のサードパーティ API へアクセスするために必要なスコープを追加します。
「SSO 体験」タブで 永続的な API アクセスのためにトークンを保存 オプションを有効にします。

変更内容を必ず保存してください。

トークンの保存

サードパーティトークンの保存を有効化すると、ユーザーがソーシャルまたはエンタープライズ SSO コネクター経由で認証 (Authentication) するたびに、Logto はフェデレーテッドアイデンティティプロバイダーによって発行されたアクセストークン (Access token) およびリフレッシュトークン (Refresh token) を自動的に保存します。これには以下が含まれます：

保存されたトークンはユーザーのソーシャルまたはエンタープライズ SSO アイデンティティに紐づけられ、再認証なしで後から API アクセス用に取得できます。

トークン保存状況の確認

Logto コンソールでユーザーのサードパーティトークン保存状況を確認できます：

コンソール > ユーザーに移動します。
調べたいユーザーをクリックします。ユーザー詳細ページに移動します。
接続セクションまでスクロールします。ここにはユーザーに紐づくすべてのソーシャルおよびエンタープライズ SSO 接続が一覧表示されます。
各接続エントリには、その接続にトークンが保存されているかどうかを示すトークンステータスラベルが表示されます。
接続エントリをクリックすると、保存されたアクセストークン (Access token) のメタデータやリフレッシュトークン (Refresh token) の有無（利用可能な場合）など、詳細を確認できます。

また、管理 API を通じてユーザーのサードパーティアイデンティティおよびトークン保存状況を確認できます：

GET /api/users/{userId}/identities/{target}?includeTokenSecret=true：指定したコネクターターゲット（例：github、google など）に紐づくユーザーのソーシャルアイデンティティとトークン保存状況を取得します。
GET /api/users/{userId}/sso-identities/{ssoConnectorId}?includeTokenSecret=true：指定した SSO コネクター ID に紐づくユーザーのエンタープライズ SSO アイデンティティとトークン保存状況を取得します。

トークン保存ステータス

アクティブ：アクセストークン (Access token) が保存されており有効です。
期限切れ：アクセストークン (Access token) は保存されていますが、期限切れです。リフレッシュトークン (Refresh token) が利用可能な場合、新しいアクセストークン (Access token) を取得できます。
非アクティブ：この接続にアクセストークン (Access token) は保存されていません。ユーザーがこの接続で認証 (Authentication) していない場合や、トークン保存が削除された場合に発生します。
該当なし：コネクターがトークン保存をサポートしていません。

トークンメタデータ

データの整合性とセキュリティのため、すべてのトークンはシークレットボールトに保存される前に暗号化されます。実際のトークン値は、適切な認可 (Authorization) を持つエンドユーザーのみがアクセスできます。開発者は、機密情報を公開せずに保存されたトークンの状態を把握するために、トークンセットのメタデータのみ取得できます。

createdAt：接続が初めて確立され、トークンセットがシークレットボールトに保存されたタイムスタンプ。
updatedAt：トークンセットが最後に更新された時刻。
- リフレッシュトークン (Refresh token) がない場合、この値は createdAt と同じです。
- リフレッシュトークン (Refresh token) がある場合、この値はアクセストークン (Access token) が最後にリフレッシュされた時刻を示します。
hasRefreshToken：リフレッシュトークン (Refresh token) が利用可能かどうかを示します。コネクターがオフラインアクセスをサポートし、認可リクエストが正しく構成されている場合、Logto はアイデンティティプロバイダーから発行されたリフレッシュトークン (Refresh token) をアクセストークン (Access token) と一緒に保存します。アクセストークン (Access token) の有効期限が切れ、かつ有効なリフレッシュトークン (Refresh token) が存在する場合、ユーザーが接続先プロバイダーへのアクセスを要求するたびに、Logto は保存されたリフレッシュトークン (Refresh token) を使って新しいアクセストークン (Access token) の取得を自動的に試みます。
expiresAt：アクセストークン (Access token) の推定有効期限（秒単位）。これは、アイデンティティプロバイダーのトークンエンドポイントから返される expires_in 値に基づいて計算されます。（このフィールドは、プロバイダーがトークンレスポンスに expires_in を含めている場合のみ利用可能です。）
scope：アクセストークン (Access token) のスコープであり、アイデンティティプロバイダーによって付与された権限 (Permissions) を示します。保存されたアクセストークン (Access token) でどのような操作が可能かを把握するのに役立ちます。（このフィールドは、プロバイダーがトークンレスポンスに scope を含めている場合のみ利用可能です。）
tokenType：アクセストークン (Access token) のタイプ。通常は "Bearer" です。（このフィールドは、プロバイダーがトークンレスポンスに token_type を含めている場合のみ利用可能です。）

トークンの取得

トークン保存が有効化され、トークンが Logto のシークレットボールトに安全に保存されると、エンドユーザーは Logto のユーザーアカウント API を組み込むことで、クライアントアプリケーションからサードパーティのアクセストークン (Access token) を取得できます。

GET /my-account/identities/:target/access-token：コネクターターゲット（例：github、google）を指定してソーシャルアイデンティティのアクセストークン (Access token) を取得します。
GET /my-account/sso-identities/:connectorId/access-token：コネクター ID を指定してエンタープライズ SSO アイデンティティのアクセストークン (Access token) を取得します。

備考:

Logto 発行のアクセストークン (Access token) を使ってアカウント API を有効化およびアクセスする方法を学べます。

トークンローテーション

トークン取得エンドポイントは以下を返します：

200 OK：アクセストークン (Access token) の取得に成功し、かつ有効な場合。
404 Not Found：指定したターゲットまたはコネクター ID に紐づくソーシャルまたはエンタープライズ SSO アイデンティティが存在しない場合、またはアクセストークン (Access token) が保存されていない場合。
401 Unauthorized：アクセストークン (Access token) の有効期限が切れている場合。

アクセストークン (Access token) の有効期限が切れており、リフレッシュトークン (Refresh token) が利用可能な場合、Logto は自動的にアクセストークン (Access token) のリフレッシュを試み、新しいアクセストークン (Access token) をレスポンスで返します。シークレットボールト内のトークン保存も新しいアクセストークン (Access token) とそのメタデータで更新されます。

トークン保存の削除

サードパーティトークンの保存は、各ユーザーのソーシャルまたはエンタープライズ SSO 接続に直接紐づいています。つまり、以下の場合に保存されたトークンセットは自動的に削除されます：

関連するソーシャルまたはエンタープライズ SSO アイデンティティがユーザーアカウントから削除された場合。
ユーザーアカウントがテナントから削除された場合。
ソーシャルまたはエンタープライズ SSO コネクターがテナントから削除された場合。

トークンの失効

ユーザーのサードパーティトークンセットを手動で削除し、アクセスを失効させることもできます：

コンソールから：ユーザーのアイデンティティ詳細ページに移動します。アクセストークン (Access token) セクション（トークン保存が利用可能な場合）までスクロールし、セクション末尾の トークンを削除 ボタンをクリックします。
管理 API 経由：
- DELETE /api/secret/:id：ユーザーアイデンティティ詳細から取得できる ID を指定して特定のシークレットを削除します。

トークンセットを失効させると、ユーザーは再度サードパーティプロバイダーで認証 (Authentication) し、新しいアクセストークン (Access token) を取得する必要があります。

再認証とトークンの更新

保存されたアクセストークン (Access token) の有効期限が切れた場合や、アプリケーションが追加の API スコープを要求する必要がある場合、エンドユーザーはサードパーティプロバイダーで再認証し、新しいアクセストークン (Access token) を取得できます—Logto への再サインインは不要です。これは Logto のソーシャル認証 API を通じて実現でき、ユーザーはフェデレーテッドソーシャル認可 (Authorization) フローを再開し、保存されたトークンセットを更新できます。

注記:

フェデレーテッド認可 (Authorization) の再開は現在ソーシャルコネクターに限定されています。エンタープライズ SSO コネクターの場合、再認証とトークンの更新にはユーザーが再度 Logto の認証 (Authentication) フロー全体を開始する必要があります。サインイン後のエンタープライズ SSO プロバイダーとの直接再認可 (Authorization) は現在サポートされていません。

ユーザーは POST /api/verification/social エンドポイントを呼び出してソーシャル認証リクエストを開始します。追加の権限 (Permissions) を要求するためにカスタムスコープを指定することもできます。
```
curl -X POST https://<your-logto-domain>/api/verification/social \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "<state>",
    "connectorId": "<logto_connectorId>",
    "redirectUri": "<redirect_uri>",
    "scope": "<custom_scope>"
  }'
```
- authorization header：Logto によって発行されたユーザーのアクセストークン (Access token)。
- connectorId：Logto 内のソーシャルコネクター ID。
- redirectUri：認証 (Authentication) 後にユーザーをアプリケーションに戻すための URI。この URI をプロバイダーのアプリケーション設定に登録する必要があります。
- scope：（任意）サードパーティプロバイダーから追加の権限 (Permissions) を要求するためのカスタムスコープ。指定しない場合はコネクターで設定されたデフォルトスコープが使用されます。
Logto は新しいソーシャル認証レコードを作成し、認証 (Authentication) 用の認可 (Authorization) URL とともにソーシャル認証 ID を返します。

レスポンス例：
```
{
  "verificationRecordId": "<social_verification_id>",
  "authorizationUri": "<authorization_url>",
  "expiresAt": "<expiration_time>"
}
```
ユーザーを認可 (Authorization) URL へリダイレクトします。ユーザーはサードパーティプロバイダーで認証 (Authentication) し、権限 (Permissions) を付与します。
サードパーティプロバイダーは認可コード付きでユーザーをクライアントアプリケーションにリダイレクトします。
認可 (Authorization) コールバックを処理し、認可コードを Logto の認証エンドポイントに転送します：
```
curl -X POST https://<your-logto-domain>/api/verification/social/verify \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "verificationRecordId": "<social_verification_id>",
    "connectorData": {
      "code": "<authorization_code>",
      "state": "<state>",
      "redirectUri": "<redirect_uri>"
    }
  }'
```
- authorization header：Logto によって発行されたユーザーのアクセストークン (Access token)。
- verificationRecordId：前のステップで返されたソーシャル認証 ID。
- connectorData：認可コードや、コールバック時にサードパーティプロバイダーから返されたその他のデータ。
注記:
CSRF 攻撃を防ぐため、state パラメーターの検証を忘れないでください。
Logto は認可コードを検証し、サードパーティプロバイダーから新しいアクセストークン (Access token) およびリフレッシュトークン (Refresh token) を取得し、レスポンスでソーシャル認証 ID を返します。
最後に、PATCH /my-account/identities/:target/access-token エンドポイントにソーシャル認証 ID を指定して呼び出し、ユーザーのトークン保存を更新します：
```
curl -X PATCH https://<your-logto-domain>/my-account/identities/<target>/access-token \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "socialVerificationId": "<social_verification_id>"
  }'
```
- authorization header：Logto によって発行されたユーザーのアクセストークン (Access token)。
- socialVerificationId：前のステップで返された認証済みソーシャル認証レコード ID。
これにより、Logto のシークレットボールト内のユーザーのトークンセット保存が新しいアクセストークン (Access token) およびリフレッシュトークン (Refresh token) で更新され、ユーザーは再度 Logto にサインインすることなくサードパーティ API にアクセスできるようになります。

更新されたアクセストークン (Access token) が返されます。

主なユースケース​

サードパーティトークンの保存を有効化する​

ソーシャルコネクター​

エンタープライズ SSO コネクター​

トークンの保存​

トークン保存状況の確認​

トークン保存ステータス​

トークンメタデータ​

トークンの取得​

トークンローテーション​

トークン保存の削除​

トークンの失効​

再認証とトークンの更新​