OpenID for Verifiable Credential Issuance
iya-sts is a Credential Issuer for
OpenID4VCI 1.0,
and its own authorization server is the one the issuer metadata names by
default. It mints three credential formats — SD-JWT VC
(RFC 9901 and
draft-ietf-oauth-sd-jwt-vc),
jwt_vc_json and ldp_vc with bbs-2023 — and publishes a status for every
credential it issues, in an IETF
Token Status List
and two W3C Bitstring Status Lists.
Every trust realm is an issuer of its own, with its own
metadata, keys, offers, status lists and settings.
The other half — asking a wallet to present a credential, and signing in with one — is OpenID4VP.
Features
The issuer metadata
GET /.well-known/openid-credential-issuer is the Credential Issuer Metadata.
It names the credential, nonce, deferred credential and notification
endpoints, the batch size, the request and response encryption parameters,
five credential configurations, and a signed_metadata JWT of the same
document. GET /.well-known/jwt-vc-issuer is the SD-JWT VC key-resolution
document (issuer and jwks_uri). Both also carry an issuer_did member,
which is an extension: see The issuer named by a DID below.
The claims each configuration advertises are built from the same selection
the credentials are built from (/admin/vc), so the metadata cannot describe a
credential this issuer no longer mints. As OpenID4VCI 1.0 section 12.2.4 has
it, a configuration’s display and claims sit inside its
credential_metadata object, not at the top of the configuration.
A realm’s issuer is https://host/realm/<id>, and its metadata is at the
path-inserted form section 12.2.2 gives,
/.well-known/openid-credential-issuer/realm/<id> (and likewise
/.well-known/jwt-vc-issuer/realm/<id>); the document at that path is the
realm’s own, whose credential_issuer is exactly that identifier.
An issued credential’s nbf is rounded down to the hour and its exp up to
the hour, so the credentials of one batch do not share a precise issuance
instant that would let verifiers link them (RFC 9901 section 10.1).
Six credential configurations
| Configuration | Format | Scope | Holder binding |
|---|---|---|---|
IdentityCredential |
dc+sd-jwt, vct urn:iya:sts:sd-jwt-vc:identity |
identity_credential |
jwk |
IdentityCredentialJwtVcJson |
jwt_vc_json |
identity_credential_jwt |
jwk |
IdentityCredentialLdpVc |
ldp_vc, secured with bbs-2023 |
identity_credential_ldp |
did:jwk |
IdentityCredentialDid |
dc+sd-jwt, issuer named by did:web |
identity_credential_did |
jwk |
IdentityCredentialLdpVcDid |
ldp_vc, issuer named by did:web |
identity_credential_ldp_did |
did:jwk |
IdentityCredentialMdoc |
mso_mdoc, docType urn:iya:sts:mdoc:identity |
identity_credential_mdoc |
cose_key |
The two …Did configurations are cloned from their plain siblings and differ
only in how the issuer names itself, so both routes can be compared against
one issuer.
The holder binding in the table is the default. Any configuration named in
oid4vci.didHolderBinding binds instead to a DID the person proved
(did:jwk, did:key), as described in
Bound to the person’s DID.
An mso_mdoc is signed by this realm’s document signer, COSE ES256 (-7)
or ESP256 (-9), and the proof a wallet presents at issuance stays a jwt
of ES256. The document signer chains to an ECDSA Issuing Authority CA minted
on first use and published at GET /oid4vci/mdoc-iaca. The credential names
its status at GET /oid4vci/status-lists/mdoc. oid4vci.mdocDoctype,
oid4vci.mdocNamespace, oid4vci.mdocValidityDays,
oid4vci.mdocAgeThresholds, oid4vci.mdocIssuingCountry and
oid4vci.mdocIssuingAuthority are that configuration’s settings.
dc+sd-jwt and jwt_vc_json credentials are signed with
oid4vci.credentialSigningAlgorithm (RS256 by default; ML-DSA, SLH-DSA and
the composites are allowed and are signed in the worker pool, unless the realm
is in wallet compatibility mode, which
refuses them with credential_request_denied). ldp_vc is
signed with the realm’s BBS key as a W3C bbs-2023 base proof (W3C Data
Integrity BBS Cryptosuites v1.0), whose mandatory statements are
oid4vci.ldpVcMandatoryPointers (and oid4vci.ldpVcDidMandatoryPointers for
the did:web configuration). The key is published as a Multikey at
/bbs/keys/{kid} and in the DID document, and rotates like any other signing
key. A credential
and the Token Status List Token its status names carry the certificate chain
of their signing key inline, in x5c — oid4vci.credentialCertificateHeader,
x5c by default since 2026-10-16. SD-JWT VC finds an issuer’s key by x5c,
by JWT VC Issuer Metadata or by a DID, and never by x5u; a Status List
Token carries no iss to look metadata up by; and HAIP 1.0 requires x5c on
both. Until then the default was x5u, and a wallet that does not follow it
(eudi-dev’s) could check neither the status list nor, without the issuer’s
metadata, the credential. The x5c stops short of the service Root, the
trust anchor, which HAIP 1.0 sections 6.1 and 6.1.1 forbid there: a wallet or
verifier is given the Root to trust (/pki), and the chain in the token
reaches it. Since 1.1.0 the key is one the realm keeps for credentials alone.
Its certificate names the credential issuer as a URI subjectAltName and
carries id-kp-documentSigning, with no DNS name and no TLS usage
(keys.credentialSigner; see
The credential-signing certificate).
The trusted list (GET /oid4vci/trusted-list, 2026-10-17). A wallet in
the EUDI ecosystem takes its anchors from a signed List of Trusted Entities
(ETSI TS 119 602), not from a bare certificate. This is one, in the
standard’s JSON binding: a compact JWS (application/jwt) signed ES256 where
that key is certified (else RS256), with the signer’s chain in x5c
(oid4vci.trustedListCertificateHeader, x5c by default, Root left off) and
x5t#S256. It names this credential issuer as its one trusted entity, with
an …/Issuance and an …/Revocation service each listing the service Root
— the certificate a credential’s x5c and its Status List Token’s both end
under. The scheme’s URIs (list type, status determination approach,
community rules, service types) are under the list’s own URL, because none
of the standard’s Annexes D to H is a list of credential issuers. It carries
ListIssueDateTime, NextUpdate (oid4vci.trustedListLifetimeH, 24 h),
DistributionPoints, a pointer to itself and SchemeTerritory where
oid4vci.trustedListTerritory is set. It is kept, one row per realm
(vc_trusted_list.state), and signed again with the next
LoTESequenceNumber only when what it says changes or NextUpdate is near.
A wallet still has to be told once to trust the list’s operator: the
service Root, as a list-operator CA. For eudi-dev that is eudi trust add-ca
--list trusted-list-ca --ca root.pem (or wallet serve --trusted-list-ca),
after which eudi trust add-list https://<host>/oid4vci/trusted-list (or the
decoder’s trusted-list URL) anchors the credentials and their status lists.
What a credential says
A credential carries claims chosen from a catalogue of LDAP attribute
types, and each value is read from the person’s own directory entry. What
the Credential claims tab at /admin/vc#vc-tab-claims selects applies to the
five configurations other than the mdoc. An mso_mdoc reads a fixed set of
that entry (given name, family name, birth date, document number, and the
configured age_over_NN thresholds). An ldp_vc credential
can carry only the terms its JSON-LD context defines, and the page names the
claims it cannot express.
A wallet may ask for a subset of the claims, in the claims member of an
openid_credential entry of authorization_details (section 5.1.1). The
selection travels inside the access token, so a wallet cannot widen it later.
A malformed claims, a claim described twice, or a path this issuer does not
advertise is refused with invalid_authorization_details. No claims member
means the whole configured set.
Wallet-initiated and issuer-initiated issuance
- Authorization code flow. The wallet asks
/oauth2/authorizefor a configuration’s scope or forauthorization_detailsof typeopenid_credential. This is the flow described on OAuth 2.0 and OpenID Connect. - Credential Offers (section 4, Appendix H). The service draws no issuer
page of its own; an issuer’s web site makes the offer and hands it to the
wallet:
- same-device (H.1): an
authorization_codegrant; the wallet signs the person in at this service’s authorization server; - cross-device (H.2): a pre-authorized code with a Transaction Code
(
tx_code), which a person makes for their own wallet on/portal/wallet(below). The offer is passed by value or by reference, served at/oid4vci/credential-offer/{id}; - deferred (H.3): the same, for a credential that takes time to produce.
In development, the companion is a click-through issuer page: it reads
/.well-known/openid-credential-issuer, makes a same-device offer itself (noissuer_state), and links the person to/portal/walletfor a pre-authorized one. Until #594 the service drew that page at/issuerand/issuer/offer. - same-device (H.1): an
- A credential about yourself, into your own wallet (
/portal/wallet, #589). A person signed in to the user portal chooses a credential configuration and now (H.2) or later (H.3, deferred), and the page shows the offer as a QR code, the Transaction Code beside it, and a link that opens it in a wallet on the same device. It is the account API’s two operations, in both modes:GET /account-api/credentials/offerable: the configurations this realm’s issuer offers, named as its metadata names them, the two modes, how long an offer lives,batchSize(oid4vci.batchSize), andissued— the credentials this realm still records as issued to the person, ONE ENTRY PER ISSUANCE, newest first: with batch issuance on, one issuance gives the wallet several copies, each bound to a different key of the wallet’s so that verifiers cannot link its presentations by the key, and they are listed together in the entry’scopies(each with its position, the RFC 7638 thumbprint of the key it is bound to — and forldp_vcthe holder’sdid:jwk— and its status-list index). Each entry has its state (valid,suspended,revoked,removed,signed-out,expired, ormixedwithcountswhen its copies differ) and the last event their wallet sent to the Notification Endpoint with the Credential Response’snotification_id(credential_accepted,credential_failure,credential_deleted; it changes nothing else), twenty issuances to a page (page, andpagingin the answer);POST /account-api/credentials/removewith{ "id": "…" }(the page’s Remove): an issuance’sidremoves every copy of it, a copy’sidremoves that copy alone. Each copy removed is revoked — its Token Status List entry INVALID, its issued-register row revoked, refused at wallet sign-in — and one CAEPcredential-changerevokeis sent. It is not deleted from the wallet: OpenID4VP is a verifier asking for a presentation and OpenID4VCI’s notification runs from wallet to issuer, so neither lets an issuer delete a credential from a wallet, and the page tells the person to delete it there. An id that is not one of the caller’s is refused (STS-PORTAL-0591);POST /account-api/credentials/offerswith{ "configuration": "…", "mode": "cross-device" | "deferred", "signingAlg": "…" }(signingAlgoptional: one of the configuration’ssigningAlgsfrom the GET — every algorithmoid4vci.credentialSigningAlgorithmallows fordc+sd-jwtandjwt_vc_json, the post-quantum ML-DSA, SLH-DSA and composite drafts among them; the configured one and RS256 for a DID-named configuration;bbs-2023forldp_vc— left out, the configured default; the realm’s Status List Token keeps the configured one): a pre-authorized offer for the token’s person (nobody else can be named), answered once — the Credential Offer, the offer by value (openid-credential-offer://?credential_offer=…) and by reference (credential_offer_uri), the configured web wallet’s link whereoid4vci.walletUrlis set,expiresAt, andtxCode.
The offer is handed to a wallet APP under
openid-credential-offer://(OpenID4VCI 1.0 section 4.1), or HAIP’shaip-vci://whereoid4vci.walletInvocationsays so: the QR code carries it by reference, and Open in a wallet on this device by value. No web wallet is offered unlessoid4vci.walletUrlnames one. If nothing opens, the page says to scan the QR code with the wallet on a phone, or to install a wallet that supports OpenID4VCI. With a third-party wallet: sign in to the portal, open Add to your wallet, choose a credential (Identity Credential,dc+sd-jwt, is the one most wallets hold), scan the QR code with the wallet, and type the Transaction Code it asks for. The wallet redeems the pre-authorized code at the token endpoint without naming a client — the authorization server’s metadata sayspre-authorized_grant_anonymous_access_supported: true(section 12.3) — fetches a nonce from/oid4vci/nonce, and asks for the credential with ajwtkey proof. A wallet that names a client of its own is judged as that client, which product mode refuses unless it is registered.The offer is made on the sign-on session the portal’s token was issued on, and is reported over CAEP as
session-presentednaming OpenID4VCI. A token whose session is no longer known, or a session that continued without signing in, is refused (STS-PORTAL-0590); a configuration the issuer does not offer is refused (STS-PORTAL-0589). - Pre-authorized code grant. The token endpoint redeems a pre-authorized
code once. The Transaction Code has
oid4vci.txCodeLengthdigits, drawn from a CSPRNG and compared in constant time. The token request may carryauthorization_details, because the pre-authorized flow has no authorization request to send them in. The access token’ssubis the offered person’surn:uuid:subject, resolved at redemption. A wallet may redeem the code without aclient_id(section 6.1). Because RFC 9068 section 2.2 requires the claim, the token then carriesclient_idurn:sts:oid4vci:anonymous-wallet, never an empty string. If the directory holds no entry for the offered person, the grant is refused withinvalid_grant(STS-OAUTH-0938).
The Credential Request
POST /oid4vci/noncehands out ac_nonce, validoid4vci.cNonceTtlS.POST /oid4vci/credentialtakes the access token as a Bearer or DPoP token and acredential_configuration_idor a grantedcredential_identifier. A batch of up tooid4vci.batchSizeproofs returns that many credentials. The errors are section 8.3.1.2’s:unknown_credential_configuration,unknown_credential_identifier,invalid_proof, andinvalid_noncefor a proof whosec_noncethis issuer does not hold (the wallet fetches a new one).- Proofs (section 8.2.1, Appendix F): the
jwtproof type (openid4vci-proof+jwt, every asymmetric algorithm this service signs with, post-quantum included except in wallet compatibility mode) and theattestationproof type. Ac_nonceis spent once across the whole cluster. A proof’siatmust be withinoid4vci.proofIatWindowSof now. - The key, by value or by DID (Appendix F.1). A
jwtproof names its key withjwk, or with akidthat is a DID URL naming adid:jwkordid:keyverification method (did:jwk:…#0,did:key:z…#z…). Both DID methods resolve from the identifier, so nothing is fetched. The method has to be listed under the DID document’sauthentication, which rules out adid:jwkwhose key saysuse: "enc". Appendix F.1 says thatjwkandkidMUST NOT both be present, so such a proof is refused, and so is adid:webkid, except one this realm publishes for the person (below). A configuration bound to a key binds to the key akidnames in the same way it binds to ajwk. - Key attestations (Appendix D). An attestation in a
jwtproof’skey_attestationheader, or as anattestationproof, is verified againstoid4vci.keyAttestationTrustedCertificatesand recorded.oid4vci.keyAttestationRequiredrequires one and says so in the metadata. What it attests decides what a wallet sign-in may later claim (see OpenID4VP). - Encryption. A request may be a JWE to the realm’s own RSA-OAEP-256 key
(
credential_request_encryption), and a wallet may ask for an encrypted response (credential_response_encryption): RSA-OAEP-256 to an RSA key, ECDH-ES to an EC key on P-256, P-384 or P-521 (#187), compressed withzipDEF first when the wallet asks (zip_values_supported). Theencvalues offered are A128GCM and A256GCM. Either direction can be made mandatory. A request is never decompressed, so the request side advertises nozip. - Deferred issuance. A credential request on the access token from a
deferred offer is answered
202with atransaction_idand anintervalinstead of a credential.POST /oid4vci/deferred_credential, with the same access token, answers202with the sametransaction_iduntiloid4vci.deferredReadyMshave passed, and then the credential; theintervalisoid4vci.deferredIntervalS. - Notifications.
POST /oid4vci/notificationtakes the wallet’snotification_idevents. Two Admin Read operations read them back:GET /admin-api/oid4vci/notifications?id=<notification_id>answers theevent,event_descriptionandnotified_atthe wallet sent (404 for an unknown id), andGET /admin-api/oid4vci/last-requesthow the last credential request arrived — its media type, and for an encrypted one the JWE’skid,algandenc, never the request itself (seen: falsebefore any).
Status lists
Every credential carries a status reference. The JOSE formats carry a Token
Status List claim (status.status_list), the W3C formats carry a Bitstring
Status List entry per purpose, and a jwt_vc_json credential carries both.
| Document | Path | Media type |
|---|---|---|
| Status List Token | /oid4vci/status-lists/1 |
application/statuslist+jwt, or application/statuslist+cwt (a COSE_Sign1) when Accept asks for it |
| Status List Aggregation | /oid4vci/status-lists |
application/json |
| Bitstring Status List credentials | /oid4vci/status-lists/bitstring/revocation and …/suspension |
application/vc+jwt, or JSON-LD with an eddsa-rdfc-2022 proof when Accept asks for JSON-LD or JSON (more) |
The Token Status List uses two bits per credential and carries ttl and exp.
Each Bitstring Status List has 131,072 entries, the specification’s minimum.
Every credential gets one index, the same in every list. It is chosen at
random and freed when the credential expires.
A credential’s status is VALID, INVALID or SUSPENDED. It is computed from
the credential’s own status and from whether an administrator revoked it, so
every page that shows it agrees. Four things change it: a suspension,
reinstatement or revocation on Monitoring → Verifiable Credentials
(/admin/vc/monitor), a revocation or restore on
/admin/tokens, an administrator’s global sign-out, and a disabled account.
The person’s own Global logout on /logout changes none of them.
oid4vci.statusListTtlS is how long a verifier may keep a list (it is also the
HTTP max-age), and oid4vci.statusListLifetimeS how long the list says it is
valid. This realm’s own Verifier consults the lists
for every presentation — this realm’s from its own store, a trusted foreign
issuer’s by fetching it and verifying it against the certificate that verified
the credential — and refuses a credential whose status cannot be established.
The issued-credentials register
When a credential is issued for a person, the realm records it in a register: the subject, the holder key’s thumbprint, the format and the expiry, never the credential itself. A row is written only when the access token:
- verified against this realm’s key and was not revoked,
- named a
urn:uuid:subject whose directory entry exists, and - was granted for credential issuance.
This register, and not the credential’s own sub, is what decides whom a
presentation may sign in. A credential
issued on any other token is still issued, but it signs nobody in.
Bound to the person’s DID
A configuration named in oid4vci.didHolderBinding (none by default) binds
its credentials to a DID the person proved, not to a bare key. That means
a did:jwk or did:key the person enrolled by proving it with their wallet
on /portal/self-issued (see OpenID4VP). For such a
configuration:
- the metadata’s
cryptographic_binding_methods_supportedis["did:jwk", "did:key"](section 12.2.4’sdid:method names), andproof_types_supporteddoes not change; - every proof has to name its key by a
kidDID URL. Ajwkproof or theattestationproof type is refused withinvalid_proof; - the access token has to name a person this realm verified: verified
here, not revoked, granted for credential issuance, and naming an
account. Otherwise the request is refused with
credential_request_denied, as it is when the account is disabled; - each DID has to be one of that person’s proved subjects. A DID an
administrator enrolled by value, somebody else’s DID, and a DID enrolled
for nobody (including one removed after the offer) are refused with
invalid_proof. A deferred issuance is checked again when it is collected.
What the credential carries:
| Format | The DID is in |
|---|---|
dc+sd-jwt |
cnf.kid, the DID URL (RFC 7800 section 3.4). sub is unchanged: SD-JWT VC requires no binding between sub and cnf |
jwt_vc_json |
credentialSubject.id and sub (the DID), and cnf.kid (the DID URL) |
ldp_vc |
credentialSubject.id, the person’s DID, where it used to be the did:jwk of the key |
Every copy is linkable. A batch’s copies all carry the same DID, and so does every later credential from that configuration. Ordinary key binding (one key per copy, rounded validity times) exists to prevent exactly that. This is the trade a configuration makes by opting in, so the binding is opt-in per configuration and never the default. The nonces and rounded validity times are unchanged.
A did:web is offered only when this realm publishes it. The service
pins a did:web’s key at enrolment, but a host elsewhere can still change its
document between the proof and the moment a relying party resolves the DID to
check a presentation, so a did:web hosted anywhere else is refused
(invalid_proof). A did:web this realm publishes for the person
(Published DIDs) is different: every version of its keys is
kept and never rewritten. With did.personPublishing on, a DID-bound
dc+sd-jwt or jwt_vc_json configuration adds did:web to
cryptographic_binding_methods_supported. The proof’s kid names
<did>#<key> in the DID’s current version, and the credential’s cnf.kid
names that version: <did>?versionId=<n>#<key>. A relying party resolves
that version at any time, and this service’s own Verifier resolves it from the
realm’s history without fetching anything. Only a DID the person proved with a
wallet binds. A DID whose key the realm keeps, or a downloaded key nobody has
proved yet, is refused. An ldp_vc names its holder by the bare DID, with no
version, so it is never bound to a did:web.
The Verifier reads the key that cnf.kid and a did:key subject name, so a
DID-bound credential signs its holder in
in every format.
The issuer named by a DID
Two configurations name the issuer by did:web. The DID document and the DIF
domain linkage are on the OpenID4VP
page. oid4vci.sdJwtIssuerDid and oid4vci.ldpVcIssuerDid move the plain
configurations to the DID as well — what a deployment that had gone to DIDs
throughout would look like. Both are off: SD-JWT VC defines no DID-based
issuer key resolution, so for dc+sd-jwt the DID route is an extension, and
the specification’s own route has to go on being exercised.
The two formats stand differently. ldp_vc is DID-native: VC Data Model
2.0 and Data Integrity assume a DID issuer. dc+sd-jwt is not:
draft-ietf-oauth-sd-jwt-vc says that “a DID-based mechanism is not explicitly
provided herein but still possible via profile/extension”, and defines only
/.well-known/jwt-vc-issuer and inline x509. So for SD-JWT VC a DID issuer is
an extension, and is labelled as one everywhere it appears. The DID
identifies the issuer only: holder binding stays cnf.jwk, because a DID
there would be nobody’s convention. (RFC 9101 is JWT-Secured Authorization
Request and has nothing to do with DIDs; it is used here only for OpenID4VP’s
request by reference.)
One decision per configuration says which identifier its credentials carry, and
both the metadata and the credential read it, so they cannot disagree about
who issued a credential. The …Did configurations are cloned from their plain
siblings when the metadata is built, so a claim or proof type added to one
cannot go missing from the other.
Three documents make the DID discoverable rather than merely asserted, and they answer different questions:
| Document | Member | Answers |
|---|---|---|
/.well-known/openid-credential-issuer |
issuer_did, and issuer_identifier per configuration |
which DID this issuer answers to, and which identifier this configuration’s credentials carry. Both are extensions; OpenID4VCI registers neither |
/.well-known/jwt-vc-issuer |
issuer_did beside jwks_uri |
the same DID, named from SD-JWT VC’s own key-resolution document. Its issuer stays the https identifier: a verifier inserts the well-known path into the credential’s iss and requires this document’s issuer to equal what it started from, and a DID cannot be the subject of that rule — which is exactly why the DID route is an extension |
/.well-known/did-configuration.json |
the DIF Well Known DID Configuration | why the DID should be believed to be the same entity as the origin. The only one of the three that is a real specification and is checkable |
The third is the point. For did:web the other two only look like an answer:
resolving did:web:example.com means fetching from example.com, so reading a
DID document off that origin to decide whether the DID belongs to it is
circular. The Domain Linkage Credential is not: the DID signs, with its own
key, a credential naming the origin, and a verifier resolves the DID
independently, checks the signature against the keys the DID authorises to
assert, and requires credentialSubject.origin to be the origin the
document came from. A verifier must also insist the linkage is for the DID
it asked about: an origin that links its own DID has not vouched for anybody
else’s, and without that check “linked” would be a property of the file
existing rather than of what it says. (That consumer-side check is the parent
project’s wallet’s; this service publishes a document that survives it.)
The Domain Linkage Credential is served in the JWT form, not the Linked
Data Proof form (the specification allows either): it is signed with the same
key and algorithm as the credentials (oid4vci.credentialSigningAlgorithm) and
verifies against the same keys, where the LD form would need
JsonWebSignature2020 over URDNA2015 canonicalization for nothing more learned.
Two details of the JWT form are what a JWT library gets wrong for you, and
both produce a document that looks right: the header must not carry typ
(it carries only alg and a kid that is a DID URL, so no x5c or x5u
either), and the payload permits no member beyond iss, sub, nbf, exp
and vc — no iat. A verifier meeting an LD-proof entry should report it as
unverifiable, not invalid: it is somebody else’s conforming document.
Not implemented
- No historical status lists:
?time=on the status list endpoint answers 501. - A key attestation certificate with a post-quantum key. (A trusted issuer certificate may hold one; see OpenID4VP.)
Development and product mode
| Development | Product | |
|---|---|---|
| Access token at the credential, deferred and notification endpoints | Any token is accepted and its claims read unverified, because OpenID4VCI lets the authorization server be somebody else | A token that does not verify against this realm’s key, or that this realm revoked, is refused invalid_token (401) |
| Claim values | What the entry lacks is invented from the username, deterministically, in fictional ranges | Nothing is invented; an attribute the entry does not hold is absent |
/portal/wallet (POST /account-api/credentials/offers) |
A pre-authorized offer for the signed-in person, on their sign-on session | The same |
| Wrong Transaction Codes | Not counted | Counted across the cluster; the oid4vci.txCodeMaxAttemptsth spends the code |
| The credential signing keys | Regenerated on every start; nothing is rotated | Kept in the store and rotated on a schedule — the BBS key and a credential-only JWS key on signing.credentialRotationIntervalDays |
A credential issued in development on an unverified token cannot sign anybody in, in either mode. See What is not checked.
Under paranoid PKI mode, on by default in product mode, the x5c of a key attestation is a real path, so a wallet provider’s intermediates count where outside this mode only one hop does. Revocation is asked where the chain names a source; where it names none there is no check to perform. A certificate in oid4vci.keyAttestationTrustedCertificates that signs the attestation itself must hold its own fields. pki.paranoidVcKeyAttestation turns this row off.
Configuration
| Setting | Environment variable | Default | Runtime? | What it does |
|---|---|---|---|---|
oid4vci.walletUrl |
OID4VCI_WALLET_URL |
(empty) | yes | A web wallet offered beside the wallet app link, where one is configured. |
oid4vci.walletInvocation |
OID4VCI_WALLET_INVOCATION |
openid-credential-offer |
yes | The scheme an offer is handed to a wallet app under: openid-credential-offer or haip-vci. |
oid4vci.walletIssuancePath |
OID4VCI_WALLET_ISSUANCE_PATH |
(empty) | yes | The page under the web wallet’s URL an offer is handed to (/vc-issuance-1.html for the embedded debugger’s). |
oid4vci.authorizationServer |
OID4VCI_AUTHORIZATION_SERVER |
(empty) | yes | A separate authorization server to advertise; empty means this service. |
oid4vci.offerUsername |
OID4VCI_OFFER_USERNAME |
diploma.student |
yes | Whom a pre-authorized offer names when whoever makes it names nobody. No door does since the demonstration issuer left the service (#594): the portal’s offer names the person signed in. |
oid4vci.offerTtlS |
OID4VCI_OFFER_TTL_S |
600 |
yes | How long an offer, its issuer_state, its pre-authorized code and a notification_id stay usable. |
oid4vci.txCodeLength |
OID4VCI_TX_CODE_LENGTH |
5 |
yes | Digits in the Transaction Code. |
oid4vci.txCodeMaxAttempts |
OID4VCI_TX_CODE_MAX_ATTEMPTS |
5 |
yes | In product mode, how many wrong Transaction Codes a pre-authorized code survives. |
oid4vci.batchSize |
OID4VCI_BATCH_SIZE |
4 |
yes | How many proofs, and so credentials, one request may carry. |
oid4vci.deferredReadyMs |
OID4VCI_DEFERRED_READY_MS |
4000 |
yes | How long a deferred credential stays pending (answered 202). |
oid4vci.deferredIntervalS |
OID4VCI_DEFERRED_INTERVAL_S |
2 |
yes | The interval a wallet is asked to wait between deferred polls. |
oid4vci.requestEncryptionRequired |
OID4VCI_REQUEST_ENCRYPTION_REQUIRED |
false |
yes | Refuse a credential request that is not a JWE. |
oid4vci.requestEncryptionKeyBits |
OID4VCI_REQUEST_ENCRYPTION_KEY_BITS |
2048 (3072 in product) |
yes | The RSA modulus of the realm’s request-encryption key; reaches keys made after the change. |
oid4vci.requestEncryptionEncValues |
OID4VCI_REQUEST_ENCRYPTION_ENC_VALUES |
A128GCM,A256GCM |
yes | Content encryption algorithms offered for requests; only these two are implemented. |
oid4vci.responseEncryptionEncValues |
OID4VCI_RESPONSE_ENCRYPTION_ENC_VALUES |
A128GCM,A256GCM |
yes | Content encryption algorithms offered for responses. |
oid4vci.responseEncryptionRequired |
OID4VCI_RESPONSE_ENCRYPTION_REQUIRED |
false |
yes | Refuse a request that does not ask for an encrypted response. |
oid4vci.credentialLifetimeS |
OID4VCI_CREDENTIAL_LIFETIME_S |
2592000 |
yes | How long every minted credential is valid (thirty days). |
oid4vci.credentialSigningAlgorithm |
OID4VCI_CREDENTIAL_SIGNING_ALGORITHM |
RS256 |
yes | The JWS algorithm for dc+sd-jwt and jwt_vc_json credentials, the status lists and the Domain Linkage Credential — the default a /portal/wallet offer may change for its own credential. |
oid4vc.walletCompatibility |
OID4VC_WALLET_COMPATIBILITY |
false |
yes | Wallet compatibility mode: no post-quantum or composite algorithm offered, signed with or accepted in OpenID4VCI and OpenID4VP. |
oid4vci.credentialCertificateHeader |
OID4VCI_CREDENTIAL_CERTIFICATE_HEADER |
x5c |
yes | Whether a credential and its Status List Token carry their signing key’s chain: x5c (inline, without the Root), x5u, both or none. |
oid4vci.signedMetadataCertificateHeader |
OID4VCI_SIGNED_METADATA_CERTIFICATE_HEADER |
x5u |
yes | The same for the metadata’s signed_metadata. |
oid4vci.trustedListCertificateHeader |
OID4VCI_TRUSTED_LIST_CERTIFICATE_HEADER |
x5c |
yes | Whether the trusted list carries its signer’s chain; x5c or both, or the list is not served. |
oid4vci.trustedListTerritory |
OID4VCI_TRUSTED_LIST_TERRITORY |
(empty) | yes | The trusted list’s SchemeTerritory (ISO 3166-1 alpha-2, or EU); empty leaves it out. |
oid4vci.trustedListLifetimeH |
OID4VCI_TRUSTED_LIST_LIFETIME_H |
24 |
yes | Hours from the list’s issue to its NextUpdate. |
oid4vci.proofIatWindowS |
OID4VCI_PROOF_IAT_WINDOW_S |
600 |
yes | How far a proof’s iat may be from now, either way. |
oid4vci.cNonceTtlS |
OID4VCI_C_NONCE_TTL_S |
300 |
yes | How long a c_nonce may be quoted in a proof. |
oid4vci.cNonceCacheSize |
OID4VCI_C_NONCE_CACHE_SIZE |
10000 |
yes | How many c_nonce values a realm holds; past it the oldest is dropped. |
oid4vci.keyAttestationRequired |
OID4VCI_KEY_ATTESTATION_REQUIRED |
false |
yes | Require a key attestation with every credential request, and advertise it. |
oid4vci.keyAttestationTrustedCertificates |
OID4VCI_KEY_ATTESTATION_TRUSTED_CERTIFICATES |
(empty) | yes | PEM certificates of the Wallet Providers whose key attestations are believed; empty trusts none. |
oid4vci.didHolderBinding |
OID4VCI_DID_HOLDER_BINDING |
(empty) | yes | The configurations bound to the person’s proved did:jwk or did:key instead of to a key. |
oid4vci.statusListTtlS |
OID4VCI_STATUS_LIST_TTL_S |
300 |
yes | The ttl (and HTTP max-age) of this realm’s status lists. |
oid4vci.statusListLifetimeS |
OID4VCI_STATUS_LIST_LIFETIME_S |
86400 |
yes | How long a status list token, or a Bitstring Status List credential, says it is valid. |
oid4vci.issuerDisplayName |
OID4VCI_ISSUER_DISPLAY_NAME |
Iya STS Credential Issuer |
yes | The metadata’s display.name. |
oid4vci.domainLinkageLifetimeS |
OID4VCI_DOMAIN_LINKAGE_LIFETIME_S |
31536000 |
yes | How long the Domain Linkage Credential says it is valid. |
oid4vci.sdJwtIssuerDid |
OID4VCI_SD_JWT_ISSUER_DID |
false |
restart | Name the plain dc+sd-jwt configuration’s issuer by did:web. |
oid4vci.ldpVcIssuerDid |
OID4VCI_LDP_VC_ISSUER_DID |
false |
restart | The same for the plain ldp_vc configuration. |
signing.credentialRotationIntervalDays |
STS_SIGNING_CREDENTIAL_ROTATION_INTERVAL_DAYS |
365 |
yes | In product mode, how long the credential signing key works before its successor is promoted, when that key signs no tokens; 0 turns rotation off. |
See Configuration for how a value is resolved. Every
oid4vci.* setting is on the OpenID4VCI settings tab at
/admin/vc#vc-tab-oid4vci in the realm it applies to, and can be changed with
POST /admin-api/config/set.
Design decisions
- Values come from the directory entry, and in development what is missing is
invented. An issued credential is only as true as the entry behind it. In
development the invented values are deterministic and obviously fictional
(RFC 2606 mail domains,
555-01xxnumbers). Nothing in this service reads a credential claim back to decide anything. - The claim catalogue is attribute types, not claim names. A claim’s value
is the value on the person’s entry, so
/admin/vcchooses attributes, and saving a selection also populates the directory. An LDAP client and a wallet therefore describe the same person. - The metadata and the credential are built from one selection. An issuer that advertised five claims and minted fourteen would teach every wallet author that the metadata is not worth reading.
- A requested subset is refused, not trimmed, when it is wrong. A wallet whose selection was quietly dropped would get a credential with claims it did not ask for, or without ones it did, and nothing would say why.
- Every single-use value is spent once across the cluster. The
pre-authorized code, each
c_nonce, and every wrong Transaction Code are claimed in the shared store. A store that cannot be asked refuses the request (STS-VC-0051) rather than risk a second use. - In product the Transaction Code has a budget. Five digits could otherwise be guessed at the token endpoint within the offer’s lifetime, so the last allowed wrong code spends the pre-authorized code.
- An offer that authorizes something is gated in product. A cross-device or deferred offer carries a pre-authorized code, which is an authorization. Minting one for a fixed user for anybody who loads the page is a test control.
- One status index per credential, and the bit is computed. The same index
in every list, and a status derived from the credential’s own entry and its
revocation mark, means
/admin/tokens, Monitoring → Verifiable Credentials at/admin/vc/monitor, an administrator’s global sign-out and the sign-in door cannot disagree. The person’s own Global logout on/logoutleaves the credential’s status as it was. - The sign-in register is written at issuance, where the facts are known.
In development the credential endpoint accepts tokens it did not issue, so a
credential’s
subcould name anybody. Only the realm’s own record of a verified, undisowned, issuance-scoped token can say whom a credential represents. - The request-encryption key belongs to the realm. Each realm publishes and decrypts with its own key, kept sealed in the store in product mode. It is a plain key and not a certificate, because section 10 publishes a bare JWK that a wallet trusts from the metadata it fetched.
- A holder key no cryptosuite can prove is refused at issuance
(
STS-VC-0080). Anldp_vcbound to such a key would verify and never be presentable. - The DID configurations sit beside the plain ones instead of replacing them. A server-wide switch would test either the DID route or the specification’s own route, never both.
In the running service
- Protocols → Verifiable Credentials (
/admin/vc) is one tabbed page. The Metadata tab lists the issuer and verifier endpoints. The OpenID4VCI tab holds the issuer’s settings, including which wallet an offer links to, which authorization server is advertised, the batch size, deferred timings, encryption, and the DID choices. API:GET /admin-api/oid4vci-settings. - Its Credential claims tab selects which claims an issued credential
carries, from the LDAP attribute catalogue, for the five configurations
other than the mdoc. Saving also populates the directory. API:
GET /admin-api/credential-claimsandPOST /admin-api/credential-claims/select. - Monitoring → Verifiable Credentials (
/admin/vc/monitor) shows this realm’s status lists, where they are served, and every issued credential’s index and status, with Suspend, Reinstate and Revoke and a Publish now for each Bitstring Status List. It was the Credential status tab of/admin/vcuntil #752, and its old address,/admin/vc#vc-tab-status, opens it. API:GET /admin-api/vc-statusandPOST /admin-api/vc-status/{suspend,reinstate,revoke,publish}. - Tokens (
/admin/tokens): issued credentials among everything else this realm issued, with the revocation that disowns one. - The live metadata at
/.well-known/openid-credential-issueris the authoritative list of what this issuer offers./admin/sts-metadatalists every endpoint (see Endpoints). - Every failure is recorded under an
STS-VC-NNNNcode; see Error codes.
Related
- Verifiable credentials and wallets (OID4VC): the overview, the recipes, and connecting a web or native wallet
- OpenID4VP, wallet sign-in and DIDs
- OAuth 2.0 and OpenID Connect, whose authorization and token endpoints issue the access token
- OAuth security profiles, for DPoP
- PKI, for the certificate chains
x5uandx5cname - Signing out, for which sign-out disowns a credential
- Trust realms
- What is not checked