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

Package-level declarations

Types

AttestationBasedClientAuthenticationService

class AttestationBasedClientAuthenticationService @JvmOverloads constructor(acceptedPopMethods: Set<OpenIdConstants.ClientAttestationPopMethod> = setOf(AttestationPopJwt), clientAttestationValidator: ClientAttestationValidator = ClientAttestationValidator(), verifyJwsSignatureWithCnf: VerifyJwsSignatureWithCnfFun = VerifyJwsSignatureWithCnf(), clock: Clock = Clock.System, timeLeeway: Duration = 5.minutes, maxAgePoP: Duration = 10.minutes, issuerIdentifier: String? = null, supportedSigningAlgorithms: Set<JwsAlgorithm.Signature> = DEFAULT_WALLET_ATTESTATION_ALGORITHMS, nonceService: NonceService = DefaultNonceService()) : ClientAuthenticationService

Client authentication service for an OAuth2.0 AS, based on Attestation-Based Client Authentication, see validate.

AuthenticatedClient

data class AuthenticatedClient(val clientId: String, val publicKey: CryptoPublicKey?) : ClientBinding

Authenticated OAuth 2.0 client

AuthorizationService

interface AuthorizationService

Provides interface for implementing an OAuth 2.0 Authorization Server, which may be used with an at.asitplus.wallet.lib.oidvci.OAuth2AuthorizationServerAdapter for a at.asitplus.wallet.lib.oidvci.OpenId4VciServer.

AuthorizationServiceStrategy

interface AuthorizationServiceStrategy

Strategy to implement authorization for credential requests (with scope or OpenIdAuthorizationDetails) in SimpleAuthorizationService.

BearerTokenGenerationService

class BearerTokenGenerationService @JvmOverloads constructor(nonceService: NonceService = DefaultNonceService(), accessTokenToValidatedAccessToken: MapStore<String, ValidatedAccessToken> = DefaultMapStore(), refreshTokenToValidatedAccessToken: MapStore<String, ValidatedAccessToken> = DefaultMapStore(), issueRefreshToken: Boolean = false) : TokenGenerationService

Simple bearer token generation (just a nonce) for an OAuth 2.0 authorization server.

BearerTokenService

class BearerTokenService(val generation: BearerTokenGenerationService, val verification: BearerTokenVerificationService, val dpopSigningAlgValuesSupportedStrings: Set<String>?, val supportsRefreshTokens: Boolean) : TokenService

Combines simple bearer tokens from BearerTokenGenerationService and BearerTokenVerificationService.

BearerTokenVerificationService

class BearerTokenVerificationService(tokenGenerationService: BearerTokenGenerationService) : TokenVerificationService

Verifies Bearer tokens that have been generated by BearerTokenGenerationService. This does only work for internal authorization servers, because we could not store the actual user data otherwise.

ClientAttestation

class ClientAttestation(val keyMaterial: KeyMaterial, val loadInstanceAttestation: suspend (OAuth2ProtocolClient.LoadInstanceAttestationInput) -> KmmResult<JwsCompactTyped<JsonWebToken>>)

How a client authenticates with OAuth 2.0 Attestation-Based Client Authentication: the instance attestation loaded by loadInstanceAttestation, and the keyMaterial it attests. Both belong together, as the attestation MUST reference keyMaterial in its cnf claim, which OAuth2ProtocolClient checks before using it.

ClientAttestationValidation

data class ClientAttestationValidation(val report: ValidationReport, val client: AuthenticatedClient?)

The report of a client attestation and its proof of possession, see ClientAttestationChecks, and the authenticated client, if it has been accepted.

ClientAuthenticationService

interface ClientAuthenticationService

Handles authenticating the OAuth 2.0 client for an OAuth 2.0 authorization server, see SimpleAuthorizationService and subclasses of this interface.

ClientAuthRequest

data class ClientAuthRequest(val issuedCode: String, val userInfo: OidcUserInfoExtended, val scope: String? = null, val authnDetails: Collection<AuthorizationDetails>? = null, val codeChallenge: String? = null, val clientBinding: ClientBinding? = null, val configurationIds: Set<String>? = null, val transactionCode: String? = null)

Extracted information from at.asitplus.openid.AuthenticationRequestParameters, to store what the client has initially requested (which scope and/or authnDetails), and which userInfo is associated with that request.

ClientBinding

sealed interface ClientBinding

JwtTokenGenerationService

class JwtTokenGenerationService @JvmOverloads constructor(nonceService: NonceService, refreshTokenNonceService: NonceService, dpopNonceService: NonceService, publicContext: String = "https://wallet.a-sit.at/authorization-server", keyMaterial: KeyMaterial = EphemeralKeyWithoutCert(), signToken: SignJwtFun<OpenId4VciAccessToken> = SignJwt(keyMaterial, JwsHeaderCertOrJwk()), clock: Clock = System, issueRefreshToken: Boolean = false, jwtIdToUserInfoExtended: MapStore<String, OidcUserInfoExtended> = DefaultMapStore(), refreshTokenJwtIdToUserInfoExtended: MapStore<String, OidcUserInfoExtended> = DefaultMapStore(lifetime = 30.days)) : TokenGenerationService

Simple DPoP token generation for an OAuth 2.0 authorization server, with OpenId4VciAccessToken as payload.

JwtTokenService

class JwtTokenService(val generation: JwtTokenGenerationService, val verification: JwtTokenVerificationService, val dpopSigningAlgValuesSupportedStrings: Set<String>?, val supportsRefreshTokens: Boolean) : TokenService

Combines sender-constrained JWT tokens from JwtTokenGenerationService and JwtTokenVerificationService.

JwtTokenVerificationService

class JwtTokenVerificationService(nonceService: NonceService, refreshTokenNonceService: NonceService, dpopNonceService: NonceService, issuerKey: JsonWebKey, verifyJwsObject: VerifyJwsObjectFun = VerifyJwsObject(), verifyJwsSignatureWithKey: VerifyJwsSignatureWithKeyFun = VerifyJwsSignatureWithKey(), clock: Clock = System, timeLeeway: Duration = 5.minutes, maxAgePoP: Duration = 10.minutes, supportedSignatureAlgorithms: Collection<JwsAlgorithm.Signature> = setOf(JwsAlgorithm.Signature.ES256)) : TokenVerificationService

Verifies JWT tokens that have been generated by JwtTokenGenerationService, as OpenId4VciAccessToken.

NoopClientAuthenticationService

object NoopClientAuthenticationService : ClientAuthenticationService

Does not verify the client authentication at all

OAuth2Client

class OAuth2Client(val clientId: String = "https://wallet.a-sit.at/app", val redirectUrl: String = "/callback", stateToCodeStore: MapStore<String, String> = DefaultMapStore(), val signPushedAuthorizationRequest: SignJwtFun<AuthenticationRequestParameters>? = SignJwt(EphemeralKeyWithSelfSignedCert(), JwsHeaderCertOrJwk()), randomSource: RandomSource = RandomSource.Default)

Simple OAuth 2.0 client to authorize the client against an OAuth 2.0 Authorization Server and request tokens.

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)

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.

OAuth2Utils

object OAuth2Utils

OpenId4VciAccessToken

@Serializable

data class OpenId4VciAccessToken(val issuer: String? = null, val audience: String? = null, val notBefore: Instant? = null, val expiration: Instant? = null, val jwtId: String? = null, val confirmationClaim: ConfirmationClaim? = null, val scope: String? = null, val authorizationDetails: Set<AuthorizationDetails>? = null)

PushedAuthorizationRequest

data class PushedAuthorizationRequest(val request: AuthenticationRequestParameters, val clientBinding: ClientBinding)

Internal class used to store pushed authorization requests created for clients in SimpleAuthorizationService.requestUriToPushedAuthorizationRequest, which are referenced by a request_uri and fetched later on in the process.

RequestInfo

data class RequestInfo @JvmOverloads constructor(val url: String, val method: HttpMethod, val headers: Headers? = null)

Holds information about the HTTP request the client has made, to validate client authentication.

ResponseWithDpopNonce

data class ResponseWithDpopNonce<T> @JvmOverloads constructor(val response: T, val dpopNonce: String?, val attestationChallenge: String? = null)

Implements RFC 9449 8.2.: Authorization servers may include a fresh DPoP nonce by including values in HTTP 200 responses, and OA-ABCA 6.2 likewise for attestation challenges.

SimpleAuthorizationService

class SimpleAuthorizationService @JvmOverloads constructor(strategy: AuthorizationServiceStrategy, codeService: CodeService = DefaultCodeService(), val publicContext: String = "https://wallet.a-sit.at/authorization-server", authorizationEndpointPath: String = "/authorize", tokenEndpointPath: String = "/token", pushedAuthorizationRequestEndpointPath: String = "/par", userInfoEndpointPath: String = "/userinfo", introspectionEndpointPath: String = "/introspect", challengeEndpointPath: String = "/challenge", issuerStateToCredentialOffer: MapStore<String, CredentialOffer> = DefaultMapStore(), codeToClientAuthRequest: MapStore<String, ClientAuthRequest> = DefaultMapStore(), refreshTokenToAuthRequest: MapStore<String, ClientAuthRequest> = DefaultMapStore(lifetime = 30.days), requestUriToPushedAuthorizationRequest: MapStore<String, PushedAuthorizationRequest> = DefaultMapStore(), tokenService: TokenService = TokenService.bearer(), clientAuthenticationService: ClientAuthenticationService = NoopClientAuthenticationService, requestParser: RequestParser = RequestParser( /** By default, do not retrieve authn requests referenced by `request_uri`. */ remoteResourceRetriever = { null }, /** Not necessary to load the authn request referenced by `request_uri`. */ buildRequestObjectParameters = { null } ), requirePushedAuthorizationRequests: Boolean = true, requestObjectSigningAlgorithms: Set<JwsAlgorithm.Signature>? = setOf(JwsAlgorithm.Signature.ES256), supportedSigningAlgorithms: Set<JwsAlgorithm.Signature> = DEFAULT_WALLET_ATTESTATION_ALGORITHMS, signIntrospectionJwt: SignJwtFun<TokenIntrospectionJwtPayload> = SignJwt(EphemeralKeyWithoutCert(), JwsHeaderCertOrJwk()), issuerStateService: CodeService = DefaultCodeService(), preAuthorizedCodeService: CodeService = DefaultCodeService(), supportTokenExchange: Boolean = false, clock: Clock = Clock.System) : OAuth2AuthorizationServerAdapter, AuthorizationService

Simple authorization server implementation, to be used for OpenId4VciServer, with the actual authentication and authorization logic for credential schemes implemented in strategy.

TokenGenerationService

interface TokenGenerationService

Strategy to generate access tokens, to use in SimpleAuthorizationService.

TokenResponseWithDpopNonce

data class TokenResponseWithDpopNonce(val params: TokenResponseParameters, val dpopNonce: String?, val attestationChallenge: String?)

TokenService

interface TokenService

Access token service that combines generation and verification, i.e., it is suitable to be used in an implementation of an OAuth 2.0 Authorization Server.

TokenVerificationService

interface TokenVerificationService

Verifies access tokens and refresh tokens, that may have been generated by a TokenGenerationService, or by any other OAuth 2.0 authorization server.

UnauthenticatedClient

data class UnauthenticatedClient(val clientId: String) : ClientBinding

Self-stated client ID, not verified in any way

ValidatedAccessToken

@Serializable

data class ValidatedAccessToken(val token: String, val userInfoExtended: OidcUserInfoExtended? = null, val authorizationDetails: Set<AuthorizationDetails>? = null, val scope: String? = null, val jwtId: String? = null)

Internal class representing issued tokens and tokens presented by clients that have been verified successfully.

Properties

DPoP

val HttpHeaders.DPoP: String

DPoPNonce

val HttpHeaders.DPoPNonce: String

OAuthClientAttestation

val HttpHeaders.OAuthClientAttestation: String

OAuthClientAttestationChallenge

val HttpHeaders.OAuthClientAttestationChallenge: String

OAuthClientAttestationPop

val HttpHeaders.OAuthClientAttestationPop: String

Functions

accepts

fun ClientBinding.accepts(presented: ClientBinding): Boolean

attestationChallenge

fun OAuth2Error?.attestationChallenge(headers: Headers): String?

Extracts the header OAuth-Client-Attestation-Challenge from the headers of an error response, if the error is use_attestation_challenge.

dpopNonce

fun OAuth2Error?.dpopNonce(headers: Headers): String?

Extracts the header DPoP-Nonce from the headers of an error response, if the authorization server responded with the error use_dpop_nonce, or the resource server did so in the header WWW-Authenticate.

toHttpResponse

fun AttestationChallengeResponse.toHttpResponse(): PreparedHttpResponse

Converts the challenge to the response of the challenge endpoint: status 200 with the challenge as JSON, and Cache-Control: no-store (OA-ABCA 6.1).

fun OAuth2AuthorizationServerMetadata.toHttpResponse(): PreparedHttpResponse

Converts the authorization server metadata to the response of /.well-known/oauth-authorization-server (and /.well-known/openid-configuration): status 200 with the metadata as JSON (RFC 8414 3.2).

fun TokenIntrospectionResult.toHttpResponse(): PreparedHttpResponse

Converts the result of the token introspection endpoint to its response: status 200 with the TokenIntrospectionResponse as JSON (RFC 7662 2.2), or the JWT of the TokenIntrospectionJwtResponse as application/token-introspection+jwt (RFC 9701 5.).

@JvmName(name = "pushedAuthorizationToHttpResponse")

fun ResponseWithDpopNonce<PushedAuthenticationResponseParameters>.toHttpResponse(): PreparedHttpResponse

Converts the result of the pushed authorization request endpoint to its response: status 201 with the parameters as JSON (RFC 9126 2.2), and the headers DPoP-Nonce and OAuth-Client-Attestation-Challenge, if present.

@JvmName(name = "tokenToHttpResponse")

fun ResponseWithDpopNonce<TokenResponseParameters>.toHttpResponse(): PreparedHttpResponse

Converts the result of the token endpoint to its response: status 200 with the token response as JSON, the headers Cache-Control: no-store and Pragma: no-cache (RFC 6749 5.1), and the headers DPoP-Nonce and OAuth-Client-Attestation-Challenge, if present.

@JvmName(name = "userInfoToHttpResponse")

fun ResponseWithDpopNonce<JsonObject>.toHttpResponse(): PreparedHttpResponse

Converts the result of the userinfo endpoint to its response: status 200 with the user info as JSON (OpenID Connect Core 5.3.2), and the header DPoP-Nonce, if present.

fun OAuth2Exception.toHttpResponse(): PreparedHttpResponse

Converts this error of an authorization server endpoint (pushed authorization request, token, token introspection, attestation challenge, authorization) to the response to send: status 400 with the toOAuth2Error as JSON (RFC 6749 5.2), including the header DPoP-Nonce for OAuth2Exception.UseDpopNonce (RFC 9449 8.) and OAuth-Client-Attestation-Challenge for OAuth2Exception.UseAttestationChallenge (OA-ABCA 7.4).

fun AuthenticationResponseResult.Redirect.toHttpResponse(): PreparedHttpResponse

Converts the result of the authorization endpoint to its response: a redirect with status 302 to the client's redirect URI in Location (RFC 6749 4.1.2).

toResourceServerHttpResponse

fun OAuth2Exception.toResourceServerHttpResponse(authorizationHeader: String?): PreparedHttpResponse

Converts this error of a resource endpoint accessed with an access token (credential, userinfo) to the response to send, with the toOAuth2Error as JSON: