//HAAPI Android Driver Documentation

HAAPI Android Driver Documentation

android jvm

Android library with classes and functions required to access Curity Identity Server Hypermedia Authentication API (HAAPI) from android devices. The library handles client attestation and provides the building blocks to issue HAAPI requests, namely obtaining DPoP access tokens.

Usage examples

Start by creating an HaapiTokenManager

    // 0 - Create a HaapiTokenManager\
    val tokenEndpointUri: URI = ...\
    val clientId: String = ...\
    val haapiTokenManager = HaapiTokenManager(tokenEndpointUri, clientId) {\
        // define additional configuration properties \

Using the OkHttp client library

When using the OkHttp HTTP client library, it is possible to include an interceptor that will automatically add all required request headers and manage the session identifier. This includes DPoP tokens and managing the associated nonces.

    // 1 - Create an OkHttpClient using haapiTokenManager \
    val httpClient = OkHttpClient.Builder()\
        // define other builder properties\
    // 2 - Use httpClient to access HAAPI resources\
    // access token, proof tokens, associated nonces and session identifiers will be handled automatically \
    // when doing requests with httpClient

Using HaapiTokenManager directly

Otherwise, the DPoP tokens and associated nonces need to be explicitly requested from the HaapiTokenManager and added to the outgoing HAAPI requests:

    // 1 - use the HaapiTokenManager to retrieve the DPoP access and proof tokens\
    // required for the outgoing HTTP request\
    val httpRequestMethod: String = ...\
    val httpRequestTargetUri: URI = ...\
    val tokens = tokenManager.getDPoPTokensFor(httpRequestMethod, httpRequestTargetUri)\
    val authorizationHeaderValue = "DPoP ${tokens.accessTokenString}"\
    val dpopHeaderValue = tokens.proofTokenString\
    // Any Identity Server response may contain a DPoP-Nonce header with a nonce string. \
    // This nonce needs be provided to all subsequent calls to this method.\
    val dpopNonceHeaderValue = tokens.dpopNonce\
    // 2 - add authorizationHeaderValue, dpopHeaderValue and dpopNonceHeaderValue to the Authorization, \
    // DPoP request headers and DPoP nonce headers respectively\

In this case, the session identifier also needs to be handled explicitly.

⚠️ When using <use-legacy-dpop>false</use-legacy-dpop>in the Identity Server configuration and receiving a 401 status code.

If a response with a 401 status code is received, www-authenticate header should be checked.

If this key is present and contains error="use_dpop_nonce", the new DPoP nonce should be extracted from the dpop-nonce header. The failed request should be retried using the new nonce.