メインコンテンツまでスキップ

不透明トークン (Opaque token)

認証 (Authentication) プロセス中にリソースが指定されていない場合、Logto は JWT ではなく不透明トークン (Opaque token) のアクセス トークンを発行します。不透明トークン (Opaque token) はランダムな文字列であり、JWT よりもはるかに短いです：

{
  "access_token": "some-random-string", // 不透明トークン (Opaque token)
  "expires_in": 3600,
  "id_token": "eyJhbGc...aBc", // JWT
  "scope": "openid profile email",
  "token_type": "Bearer"
}

不透明トークン (Opaque token) は、 userinfo エンドポイント を呼び出したり、認証 (Authentication) が必要な保護されたリソースへアクセスするために使用できます。JWT ではないため、リソースサーバーはどのようにしてこれを検証できるのでしょうか？

Logto は、不透明トークン (Opaque token) を検証するための イントロスペクションエンドポイント を提供しています。デフォルトでは、イントロスペクションエンドポイントは /oidc/token/introspection であり、POST リクエストを受け付けます。必要なパラメーターは次のとおりです：

  • token: 検証したい不透明トークン (Opaque token)

このエンドポイントではクライアント認証も必要です。次のいずれかの方法を使用できます：

  • HTTP Basic 認証：Authorization ヘッダーに Basic <base64-encoded-credentials> を指定します。クレデンシャルはクライアント ID とクライアントシークレットをコロン（:）で区切り、base64 エンコードしたものです。
  • HTTP POST 認証：client_id および client_secret パラメーターを使用します：
    • client_id: トークンをリクエストしたアプリケーションのクライアント ID
    • client_secret: トークンをリクエストしたアプリケーションのクライアントシークレット

クライアント ID（アプリ ID）およびクライアントシークレット（アプリシークレット）は、Logto の「従来の Web」または「マシン間通信」アプリケーションのいずれかのアプリクレデンシャルを使用できます。クレデンシャルが無効な場合、イントロスペクションエンドポイントはエラーを返します。

イントロスペクションエンドポイントは、トークンのクレーム (Claims) を含む JSON オブジェクトを返します：

{
  "active": true, // トークンが有効かどうか
  "sub": "1234567890", // トークンのサブジェクト (Subject)（ユーザー ID）
  "acr": "urn:logto:acr:1fa", // 認証保証レベル（達成時）
  "amr": ["pwd"], // インタラクションで使用された認証方法
  "auth_time": 1787745600 // ユーザーが認証 (Authentication) した時刻（エポック秒）
}

トークンが無効な場合、active フィールドは false となり、他のクレーム (Claims) は省略されます。acr、amr、auth_time の検証方法については ステップアップ認証 (Step-up authentication) を参照してください。構造化された JWT アクセストークンは /oidc/token/introspection でイントロスペクトできないことに注意してください。必ず JWT アクセストークンの検証 をテナントの JWKS でローカルに行ってください。

イントロスペクションリクエストの非規範的な例を示します：

curl --location \
  --request POST 'https://[tenant-id].logto.app/oidc/token/introspection' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'token=some-random-string' \
  --data-urlencode 'client_id=1234567890' \
  --data-urlencode 'client_secret=1234567890'

[tenant-id] をテナント ID に置き換えてください。

不透明トークン (Opaque token) と組織 (Organizations)​

不透明トークン (Opaque token) は、 userinfo エンドポイント を通じて組織 (Organization) メンバーシップ情報を取得するために使用できます。urn:logto:scope:organizations スコープをリクエストすると、userinfo エンドポイントは organizations（組織 ID）や organization_data など、ユーザーの組織 (Organization) 関連クレーム (Claims) を返します。

ただし、不透明トークン (Opaque token) は組織トークン (Organization token) として使用できません。組織トークン (Organization token) は常に JWT 形式で発行されます。理由は次のとおりです：

  1. 組織トークン (Organization token) には、リソースサーバーが検証する必要がある組織 (Organization) 固有のクレーム (Claims)（organization_id やスコープされた権限など）が含まれます。
  2. JWT 形式により、リソースサーバーは追加の API コールなしでトークンを検証し、組織 (Organization) コンテキストを抽出できます。

組織トークン (Organization token) を取得するには、組織パラメーターを指定して リフレッシュトークンフロー または クライアントクレデンシャルフロー を使用する必要があります。