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

サードパーティートークンセット（別名：フェデレーテッドトークンセット）は、Logto のシークレットボールトに保存されるシークレットタイプであり、サードパーティのアイデンティティプロバイダーによって発行されたアクセストークン (Access token) およびリフレッシュトークン (Refresh token) を安全に管理するために使用されます。ユーザーがソーシャルまたはエンタープライズシングルサインオン (SSO) コネクター経由で認証 (Authentication) すると、Logto は発行されたトークンをボールトに保存します。これらのトークンは後で取得でき、ユーザーに再認証 (Authentication) を求めることなく、ユーザーの代理でサードパーティ 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 アイデンティティに紐付けられ、再認証 (Authentication) を求めることなく後で 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) が利用可能かどうかを示します。コネクターがオフラインアクセスをサポートし、認可 (Authorization) リクエストが正しく構成されていれば、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) を取得します。

備考:

サードパーティのアクセストークン (Access token) を取得するには、まずエンドユーザー向けにアカウント API を有効化する必要があります。コンソール > サインイン & アカウント > アカウントセンターで設定できます。アカウント API の有効化方法および Logto 発行のアクセストークン (Access token) でのアクセス方法もご覧ください。

トークンローテーション

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

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) ) を取得しない限り、サードパーティ API へアクセスできなくなります。

再認証とトークンの更新

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

注記:

フェデレーテッド認可 (Authorization) の再開は現在ソーシャルコネクターに限定されています。エンタープライズ SSO コネクターの場合、再認証 (Authentication) およびトークンの更新には、ユーザーが再度 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 は新しいソーシャル認証レコードを作成し、ユーザーをサードパーティプロバイダーへリダイレクトするための認可 (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 コネクター​

トークンの保存​

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

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

トークンメタデータ​

トークンの取得​

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

トークン保存の削除​

トークンの失効​

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