Token Binding (Driver Layer)#
To bind authorization codes and refresh tokens to a DPoP key pair held on the device, configure token binding when constructing HaapiTokenManager. For the concept and security trade-offs, see Token Binding .
Configuration#
let tokenBoundConfiguration = BoundedTokenConfiguration(
keyPairType: CryptoKeyType.secureEnclave
)
let haapiTokenManager = HaapiTokenManagerBuilder(
tokenEndpoint: tokenEndpoint,
clientId: clientId
)
.setTokenBoundConfiguration(config: tokenBoundConfiguration)
.build()Use CryptoKeyType.secureEnclave when available; fall back to CryptoKeyType.p256 (software-backed) when Secure Enclave is not viable — some boot-state scenarios make the Secure Enclave key inaccessible.
val tokenBoundConfiguration = TokenBoundConfiguration(
keyAlias = "token-bound-key",
keyPairAlgorithmConfig = KeyPairAlgorithmConfig.ES256,
storage = mySharedPrefsStorage,
currentTimeMillisProvider = { System.currentTimeMillis() }
)
val haapiTokenManager = HaapiTokenManager.Builder(
clientId = clientId,
tokenEndpointUri = tokenEndpointUri
)
.setTokenBoundConfiguration(tokenBoundConfiguration)
.build()The storage parameter is mandatory — supply a Storage implementation that persists key state across processes. The Android Keystore alone is not reliable enough for long-lived state.
Using the Bound Key at the Token Endpoint#
When binding is enabled, the OAuth token exchange must include a DPoP proof signed with the bound key. The Driver Layer surfaces the proof generator through haapiTokenManager.dpop (iOS) or haapiTokenManager.dpopHelper (Android), but the token-endpoint exchange itself happens at the SDK Layer through OAuthTokenManager. See OAuthTokenManager for the exchange call.
Omitting the DPoP proof on the token exchange when binding is enabled yields a server error invalid_dpop_proof. The client must always pass the active DPoP key when <issue-token-bound-authorization-code>true</issue-token-bound-authorization-code> is set on the server.
How to implement this: Token Binding (concept) · How to Configure Token Binding · HaapiTokenManager