vck-openid/at.asitplus.wallet.lib.oauth2/OAuth2ProtocolClient

OAuth2ProtocolClient

class OAuth2ProtocolClient @JvmOverloads constructor(val oAuth2Client: OAuth2Client, val clientAttestation: ClientAttestation? = null, dpopKeyMaterial: KeyMaterial = clientAttestation?.keyMaterial ?: EphemeralKeyWithoutCert(), randomSource: RandomSource = RandomSource.Secure, verifyTokenIntrospectionJwt: VerifyJwsObjectFun? = null, clock: Clock = Clock.System)(source)

Implements the client side of OAuth 2.0, without sending any HTTP request itself: every call returns an HttpExchange, whose requests the caller sends with any HTTP stack. The KDoc of each method lists the ProtocolRequests its exchange sends; brackets mark optional requests, and {1,3} means the first attempt plus up to two retries.

Supported features:

DPoP nonces and attestation challenges are tracked per origin in this instance, and shared by all its exchanges. DPoP nonces from the authorization server and from resource servers are kept apart, even when both share an origin.

Constructors

OAuth2ProtocolClient

@JvmOverloads

constructor(oAuth2Client: OAuth2Client, clientAttestation: ClientAttestation? = null, dpopKeyMaterial: KeyMaterial = clientAttestation?.keyMaterial ?: EphemeralKeyWithoutCert(), randomSource: RandomSource = RandomSource.Secure, verifyTokenIntrospectionJwt: VerifyJwsObjectFun? = null, clock: Clock = Clock.System)

Types

LoadInstanceAttestationInput

data class LoadInstanceAttestationInput(val authorizationServer: String, val credentialIssuer: String, val preferredClientStatusPeriod: Duration?)

Used in ClientAttestation.loadInstanceAttestation to provide information about the authorization server.

OpenUrlForAuthnRequest

data class OpenUrlForAuthnRequest(val url: String, val state: String)

Open the url in a browser (so the user can authenticate at the AS), and store state to use in next call.

Properties

clientAttestation

val clientAttestation: ClientAttestation?

Authenticates the client with an instance attestation, when the authorization server supports attestation-based client authentication; null for no client attestation.

oAuth2Client

val oAuth2Client: OAuth2Client

Implements OAuth2 protocol, redirectUrl needs to be registered by the OS for this application, so redirection back from browser works

Functions

accessTokenHeaders

@JvmOverloads

suspend fun accessTokenHeaders(tokenResponse: TokenResponseParameters, resourceUrl: String, httpMethod: HttpMethod, dpopNonce: String? = null): Headers

Headers to access resourceUrl with the access token from tokenResponse, i.e. HttpHeaders.Authorization and, for DPoP-bound tokens, HttpHeaders.DPoP. Uses dpopNonce, or the latest DPoP nonce that the resource server at that origin provided.

callTokenIntrospection

@JvmOverloads

fun callTokenIntrospection(oauthMetadata: OAuth2AuthorizationServerMetadata, request: TokenIntrospectionRequest, popAudience: String, issuerMetadata: IssuerMetadata? = null): HttpExchange<TokenIntrospectionResponse>

Calls the token introspection endpoint (OAuth2AuthorizationServerMetadata.introspectionEndpoint) to check whether the given token is active, finishes with the response on success, otherwise fails with InvalidToken. With verifyTokenIntrospectionJwt, it asks for a JWT response (RFC 9701 4.), and accepts it only with typ token-introspection+jwt, a verified signature, the authorization server as iss, and the client_id of oAuth2Client in aud (RFC 9701 5.).

loadAuthorizationServerMetadata

fun loadAuthorizationServerMetadata(authorizationServer: String): HttpExchange<OAuth2AuthorizationServerMetadata>

Loads OAuth2AuthorizationServerMetadata from authorizationServer.

requestTokenWithAuthCode

@JvmOverloads

fun requestTokenWithAuthCode(oauthMetadata: OAuth2AuthorizationServerMetadata, url: String, authorizationServer: String, state: String, scope: String? = null, authorizationDetails: Set<OpenIdAuthorizationDetails>? = null, issuerMetadata: IssuerMetadata? = null): HttpExchange<TokenResponseWithDpopNonce>

Uses the auth code to request an access token.

requestTokenWithPreAuthorizedCode

@JvmOverloads

fun requestTokenWithPreAuthorizedCode(oauthMetadata: OAuth2AuthorizationServerMetadata, authorizationServer: String, preAuthorizedCode: String, transactionCode: String?, scope: String?, authorizationDetails: Set<OpenIdAuthorizationDetails>, issuerMetadata: IssuerMetadata? = null): HttpExchange<TokenResponseWithDpopNonce>

Uses a pre-authorized code from the authorization server to request an access token.

requestTokenWithRefreshToken

@JvmOverloads

fun requestTokenWithRefreshToken(oauthMetadata: OAuth2AuthorizationServerMetadata, credentialIssuer: String, refreshToken: String, scope: String?, authorizationDetails: Set<OpenIdAuthorizationDetails>, issuerMetadata: IssuerMetadata? = null): HttpExchange<TokenResponseWithDpopNonce>

Uses the refresh token to request a new access token.

requestTokenWithTokenExchange

@JvmOverloads

fun requestTokenWithTokenExchange(oauthMetadata: OAuth2AuthorizationServerMetadata, authorizationServer: String, subjectToken: String, resource: String?, issuerMetadata: IssuerMetadata? = null): HttpExchange<TokenResponseWithDpopNonce>

Uses an access token from another client to request a new access token, see RFC8693 OAuth 2.0 Token Exchange.

startAuthorization

@JvmOverloads

fun startAuthorization(oauthMetadata: OAuth2AuthorizationServerMetadata, authorizationServer: String, state: String = uuid4().toString(), issuerState: String? = null, authorizationDetails: Set<OpenIdAuthorizationDetails>? = null, scope: String? = null, issuerMetadata: IssuerMetadata? = null): HttpExchange<OAuth2ProtocolClient.OpenUrlForAuthnRequest>

Builds the authorization request (AuthenticationRequestParameters) to start authentication at the authorization server.

userInfoRequest

fun userInfoRequest(userInfoEndpoint: String, tokenResponse: TokenResponseParameters): HttpExchange<JsonObject>

Loads the user info from userInfoEndpoint with the access token from tokenResponse.