DPoP

Bearer トークンは、それを持つ誰にでも使えます。DPoP (RFC 9449) では、プロバイダーがトークンをアプリの鍵ペアに結び付けます。すべてのトークンリクエストとすべての API の呼び出しが、鍵で署名された短いプルーフを持つので、アプリからコピーされたトークン (ログ、バックアップ、プロキシ) はデバイスなしでは役に立ちません。登録の dpop がそう指定すると、OAuth2 クライアントがそれを行います。このパッケージは、各プラットフォームが持つ最も安全な場所にある鍵をそれに与えます。

使う理由

鍵はトークンと同じだけ生きなければならず (そうでなければ再起動のたびに新しいログインが必要になります)、アプリ自身のコードから決して読めてはなりません。スマートフォンでは、それはハードウェアを意味します。Secure Enclave や Android Keystore は、鍵を見せることなく署名します。

例

spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: neon-app
            redirect-uri: dev.neon.books:/oauth2/callback
            dpop: auto      # auto (デフォルト): プロバイダーが告知している場合。true: 常に。false: 決して

他には何も要りません。トークンのクライアント、ユーザーサービス、Feign のインターセプターは、自分で DPoPKey Bean を使います。

鍵の置き場所

パッケージは、アプリの DPoPKey Bean (platformDPoPKey、PlatformDPoPKey) を宣言します。それは起動時ではなく、最初のプルーフのときに作られます。

プラットフォーム 鍵の置き場所 署名するもの
iOS、macOS Secure Enclave (EC P-256、永続、<bundle id>.spring_dpop_key のタグ付き、最初のロック解除の後、このデバイスのみ) Secure Enclave
使える Secure Enclave のない iOS、macOS 同じタグと保護を持つ、キーチェーンのソフトウェアの鍵 システムの Security フレームワーク
Android Android Keystore (EC P-256)。スマートフォンにあれば StrongBox、なければ Trusted Execution Environment Keystore
Windows、Linux Dart で作られ、SecretStore に private JWK として保持される鍵 (oauth2.dpop-key) アプリ (SecretStoreDPoPKey)
Web、spa モード IndexedDB の取り出せない WebCrypto の鍵 (spa モード を参照) ブラウザー
Web、サーバーモード なし: ページはトークンを保持しない

PlatformDPoPKey.storage は、鍵がどこに置かれたかを示します (secureEnclave、keychain、strongBox、trustedEnvironment、software、secretStore)。鍵の素材、プルーフ、トークンがログに出ることはありません。

鍵を失ったとき

鍵がデバイスを離れることはありません。別のスマートフォンで復元されたアプリ、再インストールされた Android アプリ、消去された Keystore には鍵がありません。保存されたトークンはその鍵のサムプリントを持つので、読み込み時に捨てられ、restore() はログインを見つけず、ユーザーは再びログインします。キーチェーンの項目がアプリより長く生きる iOS では、インストールごとに ID が付きます。再インストール後の最初の起動で保存された値と鍵が取り除かれるので、再インストールされたアプリが前回のユーザーを再びログインさせることはありません。アップデートでそれらが失われることはありません。

ログアウト

logout() は、トークンを取り消して忘れた後に鍵を削除します。次のログインは新しい鍵を作るので、デバイス上の二つのログインを鍵で結び付けることはできません。SecretStore.deleteAll() はデスクトップの鍵 (ストアの値) を取り除きますが、Secure Enclave や Keystore のものは取り除きません。それらには PlatformDPoPKey.delete() を呼んでください。

独自の呼び出しと WebSocket のハンドシェイク

Feign のインターセプターは、Authorization: DPoP <token> とプルーフを自分で送ります。フレームワークが行わないリクエストでは、OAuth2 クライアントの OAuth2AccessTokenHeaders が、トークンの種類に応じてヘッダーを書きます。WebSocket のハンドシェイクでは、プルーフの htu は ws(s) の URL の http(s) の形です。

// アプリのハンドシェイクのインターセプター (spring_boot_starter_websocket)。
@Component()
class ChatHandshake implements WebSocketHandshakeInterceptor {
  ChatHandshake(this._tokens, this._dPoPKey);

  final OAuth2AuthorizedClientManager _tokens;
  final DPoPKey? _dPoPKey;

  @override
  Future<void> apply(WebSocketHandshake handshake) async {
    final user = SecurityContextHolder.getContext().authentication;
    if (user == null) return;
    final client = await _tokens.authorize(
      OAuth2AuthorizeRequest.withClientRegistrationId('keycloak')
          .principal(user)
          .build(),
    );
    final headers = await OAuth2AccessTokenHeaders(dPoPKey: _dPoPKey).of(
      client!.accessToken,
      method: 'GET',
      url: handshake.url,
    );
    headers.forEach(handshake.headers.set);
  }
}

ブラウザーは WebSocket のハンドシェイクにヘッダーを設定できません。サーバーモードのページは、それとともにセッション Cookie を送ります。

アプリは、鍵を別の場所に保持するために独自の DPoPKey Bean を宣言できます。その場合パッケージのものは身を引きます (そして logout() はアプリの鍵に触れません)。

プロパティ

キー 型 デフォルト 意味
spring.security.oauth2.client.registration.<id>.dpop auto、true、false auto auto は、プロバイダーのメタデータが DPoP を告知している場合 (Keycloak、Okta、Auth0 など) にトークンを結び付ける。true は常に、false は決して

Spring (Java) との対応

Spring Security 7 は、リソースサーバーでだけ DPoP のトークンを受け付けます。クライアント側の DPoP はなく、Java にはアプリもありません。

関連項目