Multiplatform library implementing the data models and protocols of the OpenID for Verifiable Credentials specifications, including OID4VCI, OID4VP and SIOPv2.
- Request and response data objects
- Parse and serialize to/from HTTP URI query parameters and/or HTTP form data or JSON data from request bodies
- Data structures defined by OpenID and DIF specifications
- Error handling
- Interfaces for state management and cryptographic operations
- Abstract base objects for issuer, verifier and wallet providers, implementing common business logic
To use it, depending on the kind of service provider you want to implement,
- Implement the abstract base class of the type of service provider you want to create (Issuer, Verifier or Wallet)
- Implement the interfaces for session management and cryptographic operations
- Implement a REST API providing the HTTP endpoints defined by the respective specification
The following examples show how to use the library, with simple, minimal implementations of Issuer, Verifier and Wallet REST endpoints and business logic, for processing the OpenID4VC protocols.
The examples are based on JVM and make use of ktor for the HTTP server endpoints and client-side request handling, and the waltid-ssikit for the cryptographic operations and credential and presentation handling.
For the full demo issuer implementation, refer to /src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt
For the OpenID4VCI issuance protocol, implement the following endpoints:
Well-defined endpoints:
These endpoints are well-defined, and need to be available under this exact path, relative to your issuer base URL:
-
GET /.well-known/openid-configuration
-
GET /.well-known/openid-credential-issuer
Returns the issuer provider metadata.
Other required endpoints
These endpoints can have any path, according to your requirements or preferences, but need to be referenced in the provider metadata, returned by the well-defined configuration endpoints listed above.
POST /par
Endpoint to
receive pushed authorization requests,
referenced in the provider metadata as pushed_authorization_request_endpoint
, see
also here.
GET /authorize
Authorization endpoint, referenced
in provider metadata as authorization_endpoint
, see here
Not required for the pre-authorized issuance flow.
POST /token
Token endpoint, referenced in provider
metadata as token_endpoint
, see here
POST /credential
Credential endpoint to fetch the
issued credential, after authorization flow is completed. Referenced in provider metadata as credential_endpoint
, as
defined [here](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-credential-issuer-metadata-p.
POST /credential_deferred
Deferred credential endpoint,
to fetch issued credential if issuance is deferred. Referenced in provider metadata as deferred_credential_endpoint
(missing in spec).
POST /batch_credential
Batch credential endpoint to
fetch multiple issued credentials. Referenced in provider metadata as batch_credential_endpoint
, as
defined [here](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-credential-issuer-metadata-p.
For the business logic, implement the abstract issuance provider
in src/commonMain/kotlin/id/walt/oid4vc/providers/OpenIDCredentialIssuer.kt
, providing session and cache management, as well, as
cryptographic operations for issuing credentials.
- Configuration of issuance provider
- Simple session management example
Here we implement a simplistic in-memory session management:
- Crypto operations and credential issuance
Token signing and credential issuance based on waltid-ssikit
For the full demo verifier implementation, refer to /src/jvmTest/kotlin/id/walt/oid4vc/VPTestVerifier.kt
Licensed under the Apache License, Version 2.0
sequenceDiagram
Issuer -->> Wallet: Issuance request (QR, or by request)
Wallet ->> Issuer: Resolve credential offer
Issuer -->> Wallet: Credential offer
Wallet ->> Issuer: fetch OpenID Credential Issuer metadata
Issuer -->> Wallet: Credential issuer metadata
Wallet ->> Wallet: Check if external authorization service (AS)
Wallet ->> AS: fetch OpenID provider metadata
AS -->> Wallet: OpenID provider metadata
Wallet ->> Wallet: resolve offered credential metainfo
Wallet ->> Wallet: Generate code verifier and code challenge
Wallet ->> AS: Authorization request, auth details and code challenge
AS -->> Wallet: Redirect to wallet with id_token request
Wallet ->> Wallet: Generate id_token
Wallet ->> AS: POST id_token response to redirect_uri
AS -->> Wallet: Redirect to wallet with authorzation code
Wallet ->> AS: POST token request with code and code verifier
AS -->> Wallet: Respond with access_token and c_nonce
loop Fetch offered credentials
Wallet ->> Wallet: generate DID proof
Wallet ->> Issuer: Fetch credentials from credential endpoint or batch-credential endpoint, with DID proof
Issuer -->> Wallet: Credential (and updated c_nonce)
end