フェデレーテッドトークンセット

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

フェデレーテッドトークンストレージの有効化

ソーシャルコネクター

備考:

この機能はトークンストレージをサポートするコネクターのみ利用可能です。現在サポートされているコネクターは：GitHub、Google、Facebook、Standard OAuth 2.0、Standard OIDC です。今後、追加のコネクターへの対応も順次行われます。

1. コンソール > コネクター > ソーシャルコネクター に移動します。
2. フェデレーテッドトークンストレージを有効にしたいソーシャルコネクターを選択します。
3. 「設定」ページで 永続的な API アクセスのためにトークンを保存 オプションを有効にします。

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

備考:

トークンストレージはすべての OIDC エンタープライズコネクターで利用可能です。

1. コンソール > エンタープライズ SSO に移動します。
2. フェデレーテッドトークンストレージを有効にしたいエンタープライズ SSO コネクターを選択します。
3. 「SSO 体験」タブで 永続的な API アクセスのためにトークンを保存 オプションを有効にします。

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

トークンストレージ

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

• ソーシャルサインイン・サインアップ
• エンタープライズ SSO サインイン・サインアップ
• アカウント API 経由のソーシャルアカウント連携

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

トークンストレージの状態確認

Logto コンソールでユーザーのフェデレーテッドトークンストレージの状態を確認できます：

1. コンソール > ユーザー に移動します。
2. 詳細を確認したいユーザーをクリックします。ユーザー詳細ページに移動します。
3. 接続 セクションまでスクロールします。このエリアにはユーザーに紐付くすべてのソーシャルおよびエンタープライズ SSO 接続が一覧表示されます。
4. 各接続エントリーには、その接続でトークンが保存されているかどうかを示すトークンステータスラベルが表示されます。
5. 接続エントリーをクリックすると、保存されたアクセス トークン (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) していない場合や、トークンストレージが削除された場合に発生します。
• 該当なし：コネクターがトークンストレージをサポートしていません。

トークンメタデータ

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

• createdAt：接続が初めて確立され、トークンセットが Secret Vault に初期保存されたタイムスタンプ。
• 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) のスコープ (Scope)。アイデンティティプロバイダーによって付与された権限 (Permission) を示します。 保存されたアクセス トークン (Access token) でどのような操作が可能かを把握するのに役立ちます。（このフィールドはプロバイダーがトークンレスポンスに scope を含めている場合のみ利用可能です。）
• tokenType：アクセス トークン (Access token) のタイプ。通常は "Bearer" です。 （このフィールドはプロバイダーがトークンレスポンスに token_type を含めている場合のみ利用可能です。）

トークン取得

トークンストレージが有効化され、トークンが Logto の Secret Vault に安全に保存されると、エンドユーザーは 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) を使って Account 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) をレスポンスで返します。Secret Vault 内のトークンストレージも新しいアクセス トークン (Access token) とそのメタデータで更新されます。

トークンストレージの削除

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

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

トークンの失効

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

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

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

再認証とトークン更新

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

注記:

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

1. ユーザーは POST /api/verification/social エンドポイントを呼び出してソーシャル認証リクエストを開始します。追加の権限 (Permission) を要求するためにカスタムスコープ (Scope) を指定することもできます。

   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：（任意）サードパーティプロバイダーから追加の権限 (Permission) を要求するカスタムスコープ (Scope)。指定しない場合はコネクターで設定されたデフォルトスコープが使用されます。

2. Logto は新しいソーシャル認証レコードを作成し、ユーザーをサードパーティプロバイダーへリダイレクトするための認可 (Authorization) URL とともにソーシャル認証 ID を返します。

   レスポンス例：

   {
     "verificationRecordId": "<social_verification_id>",
     "authorizationUri": "<authorization_url>",
     "expiresAt": "<expiration_time>"
   }

3. ユーザーを認可 (Authorization) URL へリダイレクトします。ユーザーはサードパーティプロバイダーで認証 (Authentication) し、権限 (Permission) を付与します。

4. サードパーティプロバイダーは認可コード付きでユーザーをクライアントアプリケーションへリダイレクトします。

5. 認可コールバックを処理し、認可コードを 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 パラメーターの検証を忘れないでください。

6. Logto は認可コードを検証し、サードパーティプロバイダーから新しいアクセス トークン (Access token) およびリフレッシュ トークン (Refresh token) を取得し、レスポンスでソーシャル認証 ID を返します。

7. 最後に、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 の Secret Vault 内のユーザーのトークンセットストレージが新しいアクセス トークン (Access token) およびリフレッシュ トークン (Refresh token) で更新され、ユーザーは再度 Logto にサインインすることなくサードパーティ API へアクセスできるようになります。

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