Skip to main content
Version: v0.25.0 (Latest)

OpenID for Verifiable Credential Issuance (OpenID4VCI)

The IDK implements the OpenID4VCI issuer: metadata, credential offers, wallet-facing protocol handlers for /credential, /credential_deferred, /nonce, /notification, the DI graph wiring, and in-memory stores for a self-contained issuer. The protocol primitives and basic handler extension points remain in the IDK OpenID4VCI issuer guide.

The EDK adds the enterprise issuance runtime around that protocol. The issuer gets claim values through a connector-native PipelineConfiguration: automatic integration is expressed as ConnectorInvocationBinding records bound to named OID4VCI lifecycle stages. A binding can enrich fields, export selected data, write evidence to a vault, send notifications, or orchestrate a connector route. The session has an encrypted attribute bag and connector-field map; the pipeline contract is connector invocation bindings, not a parallel source model.

The Mental Model​

An EDK issuance is an IssuancePipelineSession. The session carries:

  • an attribute bag: resolved fields that can become credential claims,
  • connector fields: correlation and integration inputs such as email, employee_id, identity_id, AS claims, or callback handles,
  • protocol status: where the session is in issuance, deferral, approval, and completion.

The session passes through OID4VCI phases. Connector invocations can run before or during offer creation, authorization, pre-authorized issuance, token exchange, credential request, pre-issue, deferred polling, post-issuance, and notification receipt. Each invocation sees the accumulated fields and can add fields for later phases.

When the wallet calls /credential, the EDK runs the credential-request and pre-issue connector phases, assembles claims from the bag, and hands the result to the IDK protocol handler to sign. If required data is not available synchronously, the wallet can receive a deferred response; later connector or callback work can complete the session before /credential_deferred returns the credential.

What the EDK Adds​

A registered PipelineConfiguration per issuance flow. It declares invocationBindings, credential bindings, and expected initial connector fields. See Attribute Pipeline.

Connector invocation bindings. A binding connects an OID4VCI stage to a connector route, connector instance, or operation binding. It carries role, exchange mode, subset mapping, execution policy, logical context, governance metadata, Party anchors, and materialization policy. See Connector Invocations.

Pipeline session management endpoints. The EDK adds REST endpoints under /oid4vci/sessions/... for creating sessions, manually contributing attributes, evaluating completeness, approving issuance, failing an integration, and reading accumulated state. These endpoints are operator/backend surfaces; the wallet-facing OID4VCI endpoints remain protocol endpoints. See REST API.

Manual contribution surfaces. POST /api/oid4vci/v1/backend/sessions/{correlationId}/attributes and POST /api/oid4vci/v1/backend/credential/offers can push data into the session using compact groups. In those request bodies, contributorId is record provenance for manually supplied data. It is not the automatic integration contract; automatic runtime integration uses PipelineConfiguration.invocationBindings.

Async and deferred execution. Connector execution policies can be inline, optional, deferred async, or durable outbox. The EDK can hold /credential open for a configured sync window and fall through to deferred issuance when an integration cannot complete in time. Callback ingress is still secured by an opaque capability token scoped to one session and contribution.

Deferral and approval gates. Each credential binding carries deferral and approval policy. AWAITING_DEFERRED and AWAITING_APPROVAL are observable separately from the protocol-level deferred credential response.

Encrypted session persistence. Sessions carry sensitive data. The EDK provides plaintext mode for development, platform-encrypted mode under a tenant KEK, and client-bound mode tied to the session correlation id. See Persistence.

Tenant-aware issuer paths. Protocol endpoints can optionally be reached through a tenant slug path, while host-based tenant resolution continues to work.

How a Developer Builds an Issuer​

  1. Define credential designs. The credential design system is the source of truth for credential configurations, claim policy, status lists, and display/render data.

  2. Register connector invocation bindings for the stages where issuance needs integration. A typical employee credential pipeline might bind OID4VCI_START for audit, OID4VCI_AUTHORIZATION for authenticated-user context, OID4VCI_TOKEN to resolve an external identifier, OID4VCI_CREDENTIAL_REQUEST to fetch the HR record, OID4VCI_PRE_ISSUE for final enrichment or policy state, and OID4VCI_POST_ISSUANCE for vault retention.

  3. Register the PipelineConfiguration with invocationBindings, credential bindings, and expected initial connector fields.

  4. Let the IDK/EDK protocol handlers run the phases at the correct OID4VCI moments. You only call the pipeline REST API when backend code needs to seed, observe, approve, or manually contribute to a session.

You write code only when you need a new connector implementation, a custom route executor, or a custom claim mapper.

Where Things Live​

ConcernModule
Issuer protocol service, DSL, handlerscom.sphereon.idk:lib-openid-oid4vci-issuer-public / -impl
Issuer REST endpointscom.sphereon.idk:services-oid4vci-issuer-rest plus EDK tenant adapters
Pipeline session and command typescom.sphereon.edk:lib-credential-issuance-pipeline-public
Attribute bag and phase typescom.sphereon.idk:lib-attribute-flow-public
Connector invocation contractscom.sphereon.edk:lib-connector-public
Pipeline command implementations and OID4VCI connector bridgecom.sphereon.edk:lib-credential-issuance-pipeline-impl
VDX durable connector registry, routes, grants, throttling, run lineage, and invocation binding REST/admin surfacecom.sphereon.vdx:vdx-data-store-connector-*
Tenant-aware path adaptercom.sphereon.edk:lib-openid-oid4vci-issuer-rest-tenant
Service contractscom.sphereon.edk:lib-openid-oid4vci-issuer-contract
Deployable containercom.sphereon.edk:services-oid4vci-issuer

Next Steps​