DPoP

A Bearer token works for whoever holds it. With DPoP (RFC 9449) the provider binds the tokens to a key pair of the app: every token request and every API call carries a short proof signed by the key, so a token copied out of the app (a log, a backup, a proxy) is useless without the device. The OAuth2 client does it when the registration's dpop says so; this package gives it the key, in the safest place each platform has.

Why

The key must live as long as the tokens, or a restart would mean a new login, and it should never be readable by the app's own code. On phones that means hardware: the Secure Enclave or the Android Keystore sign without ever showing the key.

Example

spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: neon-app
            redirect-uri: dev.neon.books:/oauth2/callback
            dpop: auto      # auto (default): when the provider announces it; true: always; false: never

Nothing else: the token clients, the user services and the Feign interceptor use the DPoPKey bean by themselves.

Where the key lives

The package declares the app's DPoPKey bean (platformDPoPKey, a PlatformDPoPKey). It is made at the first proof, not at startup.

Platform Where the key lives Who signs
iOS, macOS the Secure Enclave (EC P-256, permanent, tagged <bundle id>.spring_dpop_key, after the first unlock, this device only) the Secure Enclave
iOS, macOS without a usable Secure Enclave a software key of the Keychain with the same tag and protection the system's Security framework
Android the Android Keystore (EC P-256), in StrongBox when the phone has it, else the trusted execution environment the Keystore
Windows, Linux a key made in Dart, kept as a private JWK in the SecretStore (oauth2.dpop-key) the app (SecretStoreDPoPKey)
Web, spa mode a non-extractable WebCrypto key in IndexedDB (see Spa mode) the browser
Web, server mode none: the page holds no tokens

PlatformDPoPKey.storage says where the key ended up (secureEnclave, keychain, strongBox, trustedEnvironment, software, secretStore). No key material, proof or token is ever logged.

When the key is lost

The key never leaves the device: an app restored on another phone, an Android app reinstalled, or a wiped Keystore has none. The stored tokens carry the thumbprint of their key, so they are dropped when loaded, restore() finds no login, and the user logs in again. On iOS, where Keychain items outlive the app, each installation gets an id: the first start after a reinstall removes the stored values and the key, so a reinstalled app does not log the last user in again. An update never loses them.

Logout

logout() deletes the key after revoking and forgetting the tokens; the next login makes a new one, so two logins on the device cannot be linked by their key. SecretStore.deleteAll() removes the desktop key (a value of the store), not the Secure Enclave's or the Keystore's; call PlatformDPoPKey.delete() for those.

Calls of your own and WebSocket handshakes

The Feign interceptor sends Authorization: DPoP <token> and a proof by itself. For a request the framework does not make, OAuth2AccessTokenHeaders of the OAuth2 client writes the headers by the token's type. For a WebSocket handshake the proof's htu is the http(s) form of the ws(s) URL:

// A handshake interceptor of the app (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);
  }
}

Browsers cannot set headers on a WebSocket handshake: a page in server mode sends its session cookie with it.

An app declares its own DPoPKey bean to keep the key elsewhere; the package's then backs off (and logout() leaves the app's key alone).

The property

Key Type Default Meaning
spring.security.oauth2.client.registration.<id>.dpop auto, true, false auto auto binds the tokens when the provider's metadata announces DPoP (Keycloak, Okta, Auth0, ...); true always; false never

In Spring (Java)

Spring Security 7 accepts DPoP tokens on resource servers only; it has no DPoP on the client's side, and Java has no apps.

See also