vck-openid-ktor/at.asitplus.wallet.lib.ktor.openid/OpenId4VciKtorClient

OpenId4VciKtorClient

Implements the client side of OpenID for Verifiable Credential Issuance 1.0 from 2025-09-16 with ktor, by sending the requests of OpenId4VciProtocolClient and at.asitplus.wallet.lib.oauth2.OAuth2ProtocolClient, which implement the protocols, in the order of each flow. Supported features:

Pre-authorized grants
Authentication code flows
OAuth 2.0 Demonstrating Proof of Possession (DPoP)
OAuth 2.0 Attestation-Based Client Authentication
OAuth 2.0 Pushed Authorization Requests

Constructors

constructor(httpClient: HttpClient, oauth2Client: OAuth2Client, vciClient: OpenId4VciClient = OpenId4VciClient(proofCreators = listOf(JwtProofCreator(EphemeralKeyWithoutCert()))), clientAttestation: ClientAttestation? = null, dpopKeyMaterial: KeyMaterial = clientAttestation?.keyMaterial ?: EphemeralKeyWithoutCert(), issuerMetadataValidator: IssuerMetadataValidator = IssuerMetadataValidator())

constructor(engine: HttpClientEngine, cookiesStorage: CookiesStorage? = null, httpClientConfig: HttpClientConfig<*>.() -> Unit? = null, oid4vciClient: OpenId4VciClient = OpenId4VciClient(), oauth2InternalClient: OAuth2Client = OAuth2Client(clientId = oid4vciClient.clientId), oauth2Client: OAuth2KtorClient = OAuth2KtorClient( engine = engine, cookiesStorage = cookiesStorage, httpClientConfig = httpClientConfig, oAuth2Client = oauth2InternalClient, ))

Functions

loadCredentialMetadata

suspend fun loadCredentialMetadata(host: String): KmmResult<Collection<CredentialIdentifierInfo>>

Loads credential metadata info from host, call parseCredentialMetadata to parse it, returns a list of CredentialIdentifierInfo.

loadCredentialOffer

suspend fun loadCredentialOffer(input: String): KmmResult<CredentialOffer>

Loads the CredentialOffer from input, i.e. the content of a QR code or deep link: a JSON-encoded credential offer, or a credential offer URL with the offer embedded (credential_offer) or passed by reference (credential_offer_uri), which will be loaded from the credential issuer.

loadCredentialWithOfferReturningResult

suspend fun loadCredentialWithOfferReturningResult(credentialOffer: CredentialOffer, credentialIdentifierInfos: NonEmptyList<CredentialIdentifierInfo>, transactionCode: String? = null, authorizationServerMetadata: OAuth2AuthorizationServerMetadata? = null): KmmResult<CredentialIssuanceResult>

Loads some user-selected credentials with pre-authorized code from the OID4VCI credential issuer, with one token for all of them, as a pre-authorized code can usually be used only once

suspend fun loadCredentialWithOfferReturningResult(credentialOffer: CredentialOffer, credentialIdentifierInfo: CredentialIdentifierInfo, transactionCode: String? = null, authorizationServerMetadata: OAuth2AuthorizationServerMetadata? = null): KmmResult<CredentialIssuanceResult>

Loads a user-selected credential with pre-authorized code from the OID4VCI credential issuer

loadIssuerMetadata

suspend fun loadIssuerMetadata(credentialIssuer: String, policy: ValidationPolicy): KmmResult<LoadedIssuerMetadata>

Loads the metadata of credentialIssuer, preferring signed metadata, which are validated under policy, see OpenId4VciProtocolClient.loadIssuerMetadata. Pass them to parseCredentialMetadata, if the wallet accepts them, so that every CredentialIdentifierInfo carries the validated credential issuer.

parseCredentialMetadata

fun parseCredentialMetadata(issuerMetadata: IssuerMetadata): KmmResult<Collection<CredentialIdentifierInfo>>

Parses IssuerMetadata and returns a list of CredentialIdentifierInfo.

fun parseCredentialMetadata(loaded: LoadedIssuerMetadata): KmmResult<Collection<CredentialIdentifierInfo>>

Parses the metadata of loaded, see loadIssuerMetadata, and returns a list of CredentialIdentifierInfo, each with the credential issuer validated from signed metadata. Fails for signed metadata that have been rejected.

parseCredentialMetadataIgnoringTrust

fun parseCredentialMetadataIgnoringTrust(loaded: LoadedIssuerMetadata): KmmResult<Collection<CredentialIdentifierInfo>>

Parses the metadata of loaded also if signed metadata have been rejected, without a validated credential issuer, see OpenId4VciProtocolClient.parseCredentialMetadataIgnoringTrust: only to continue after showing the report to the user.

refreshCredentialReturningResult

suspend fun refreshCredentialReturningResult(refreshTokenInfo: CredentialRenewalInfo): KmmResult<CredentialIssuanceResult.Success>

Call to refresh a credential with a stored refresh token (that was received when issuing the credential for the first time, as returned in CredentialIssuanceResult.Success.refreshToken).

resumeWithAuthCode

suspend fun resumeWithAuthCode(url: String, context: ProvisioningContext): KmmResult<CredentialIssuanceResult.Success>

Called after getting the redirect back from the authorization server to the credential issuer.

startProvisioningWithAuthRequestReturningResult

suspend fun startProvisioningWithAuthRequestReturningResult(credentialIssuerUrl: String, credentialIdentifierInfos: NonEmptyList<CredentialIdentifierInfo>, reissuingStoreEntryId: Long? = null): KmmResult<CredentialIssuanceResult.OpenUrlForAuthnRequest>

Starts the issuing process at credentialIssuerUrl for all of credentialIdentifierInfos with one authorization, like the overload for one credential, so that the user authenticates only once.

suspend fun startProvisioningWithAuthRequestReturningResult(credentialIssuerUrl: String, credentialIdentifierInfo: CredentialIdentifierInfo, reissuingStoreEntryId: Long? = null): KmmResult<CredentialIssuanceResult.OpenUrlForAuthnRequest>

Starts the issuing process at credentialIssuerUrl. Clients need to handle the result, i.e. open the URL for user authentication or store the credentials, see CredentialIssuanceResult.Success.prepareCredentialStorage. Clients need to call resumeWithAuthCode after getting the authorization code back from the authorization server, e.g. by the Wallet app getting opened (see redirectUrl at oid4vciClient) after the browser being redirecting back from the authorization server.