This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.
A did:web this realm publishes for a person
A person can have the realm create and publish a did:web for them from
their portal’s Self-issued IDs page. The DID is theirs to prefer, to have
released to applications they consent to, and — where their wallet holds the
key — to sign in with and to have credentials bound to. This is different
from a DID a person enrolls, which
names a DID they already control somewhere else.
It is off by default (did.personPublishing) and set per realm.
Features
The identifier
did:web:<host>[:realm:<realm id>]:users:<rid>
<rid> is 128 random bits in base64url (22 characters), drawn for each DID.
Nobody can find an account by probing addresses, and two DIDs of one person
cannot be linked to each other. In a service deployed as cells, twelve more
characters follow: a keyed tag naming the cell that minted the DID, so a
resolver reaching any cell is sent to the one that holds it. Without the
service’s key the tag is noise; all it shows is that two DIDs came from the
same cell, which every person homed there shares. The DID is fixed when it is created, from
the realm’s public base URL, and never changes after that, even when an
administrator moves the person to another cell: the cell that created it
looks up where the person lives now and answers with the document from
there. A realm-custody key moves with the person and is sealed again under
the new cell’s key.
- In product mode a DID is published only when the base is pinned:
global.publicBaseUrl, or the advertised listener of the verifiable credentials application. A request’sHostheader never becomes part of a stored identifier. - In development mode, with nothing pinned, the DID is built on the address the request arrived at, and that address is part of it for good.
The document
The did:web method resolves the DID to
GET https://<host>[/realm/<realm id>]/users/<rid>/did.json
which answers application/did+json with Cache-Control: no-store, like
every document carrying a key here. Each key is a JsonWebKey2020
verification method whose fragment is the key’s RFC 7638 thumbprint, listed
under authentication and assertionMethod.
Versions
Every change of keys appends a version, and no version is ever rewritten.
Each version records when it was created, its keys, the change (create,
add-key, rotate-key) and what authorized it.
?versionId=<n>and?versionTime=<YYYY-MM-DDThh:mm:ssZ>on the document’s address answer that version from the history. A version that does not exist answers 404, and a malformed one 400.- The realm’s DID resolver (
GET /vc-api/resolve?did=…, see W3C VC API) takes the same two parameters, as resolution options or as a DID URL’s query, and reports DID Core’sdidDocumentMetadata:created,updated,versionId,nextVersionIdand, when it applies,deactivated.
A credential bound to the DID names the version it was bound to
(<did>?versionId=<n>#<key>), so a verifier can check it against the key the
DID named then, for as long as the history is kept. See
Bound to the person’s DID.
Who holds the key
did.personCustody chooses one of three modes for the realm:
| Custody | The key | What the DID can do |
|---|---|---|
wallet (default) |
The person’s wallet proves its own key in a self-issued (SIOPv2) round trip. The realm publishes only the public half. | Preferred, released in the did claim, signs in, binds credentials. |
realm |
Generated by the realm and kept sealed. It never leaves the realm. | Preferred and released. It cannot sign a wallet in or bind a credential, because no wallet holds its key. |
download |
Generated by the realm. The private key is shown once as a file, and only the public half is kept. | Preferred and released. Once the person proves the key with their wallet it becomes a wallet DID and can sign in and bind credentials. |
Warning.
walletis the most secure choice. Withrealm, the realm holds a key that can act as the person. Withdownload, the private key passes through the browser once. Choose them only where that is acceptable.
Changing the keys
walletcustody takes two proofs in one act, each a wallet round trip started from the DID’s Add key or Rotate key:- the wallet signs as the DID, with a key its current version names. This authorizes the change, for ten minutes;
- the wallet proves the new key with its own
did:jwk,did:keyor JWK thumbprint subject. Prove the new key appears on the page once the change is authorized.
Both proofs are recorded on the new version. A change signed only by the new key has no authorization, and is refused. Add key keeps the current keys beside the new one, and Rotate key replaces them.
realmcustody: Add key and Rotate key are one act each, authorized by the person signed in to the portal. The new key is generated and sealed, and a rotated-out key is not kept.downloadcustody: prove the downloaded key first (Enrol a wallet, signing as the DID). The DID then changes keys as awalletone does.
A DID keeps at most 50 versions. To go further, publish a new DID and deactivate the old one.
Deactivation
A DID is deactivated when:
- the person deactivates it on their portal (removing it from the list of self-issued IDs does the same);
- an administrator deactivates it, from the person’s page under
Directory → Users or with
POST /admin-api/users/deactivate-published-did; - the person’s account is disabled. This is decided when the document is served, so enabling the account restores the DID.
A deactivated DID’s address answers 410 Gone with
{ "id": "<did>", "deactivated": true }, and the resolver reports
deactivated: true. The address is kept, and the id is never drawn again. A
DID deactivated by the person or an administrator stays deactivated. It no
longer signs anybody in, is not preferred, and is not released.
An administrator never creates or changes a person’s DID. That is the person’s act.
On the portal
/portal/self-issued shows, where the realm publishes DIDs:
- Publish a DID. In
walletcustody this is a link to the wallet round trip. In the other two it is a button, and indownloadcustody the answer carries the private key once, in its own pane; - each DID: the DID, a link to its document, who holds its key, its current version and the history of versions, and its state;
- Add key, Rotate key and Deactivate.
Development and product mode
| Development | Product | |
|---|---|---|
| The base a DID is minted on | The pinned base, or the request’s own address | The pinned base only (otherwise refused) |
A realm-custody private key at rest |
Kept as written: development’s key-encryption key does not outlive the process | Sealed under the key-encryption key; a key that cannot be sealed publishes nothing |
Everything else is the same in both modes.
Configuration
These are rows of common/config.js. The live source is the console’s
OpenID4VCI tab at /admin/vc and GET /admin-api/config.
| Setting | Environment variable | Default | Change while running? | What it does |
|---|---|---|---|---|
did.personPublishing |
STS_DID_PERSON_PUBLISHING |
false |
yes | Lets a person have this realm publish a did:web for them. Off, nothing new is published, and those already published are still served. |
did.personCustody |
STS_DID_PERSON_CUSTODY |
wallet |
yes | wallet, realm or download, as above. |
did.personMaxPerPerson |
STS_DID_PERSON_MAX_PER_PERSON |
3 |
yes | How many active published DIDs one person may hold. Deactivated ones do not count. |
did.personKeyAlgorithm |
STS_DID_PERSON_KEY_ALGORITHM |
ES256 |
yes | The algorithm of a key the realm generates (realm and download custody): ES256, ES384 or EdDSA. |
Design decisions
- A random identifier, not the username. The username would let anybody confirm an account exists by fetching an address, and would link every DID of one person.
- Deactivate, keep the URL. A relying party that resolves the DID later learns it was deactivated. A 404 would read as a DID that never existed.
- History, not a current document. Binding a credential to a
did:webis sound only where the key the credential names stays resolvable. A host elsewhere can change its document at any time. This realm keeps every version. - Two proofs for a change in
walletcustody. One by the current key, so a stolen session cannot replace the key; one by the new key, so nobody publishes a key they do not hold.
In the running service
GET /admin/sts-metadatalists the document endpoint under Decentralized Identifiers.GET /admin-api/users/published-dids?user=<name>lists a person’s DIDs: their versions, keys, custody and state, never a private key.- The audit log records every publication (
did.person.published), change (did.person.version), authorization (did.person.authorized) and deactivation (did.person.deactivated,admin.did.deactivated), refusals included, each with its error code (STS-VC-0161toSTS-VC-0176). - Shared Signals: a CAEP credential-change is sent when the DID is enrolled as a self-issued subject, re-pinned to a new version, and removed.
Related
- OpenID4VP and wallet sign-in: self-issued ID Tokens and the preferred DID
- OpenID4VCI: credentials bound to a DID
- Configure OIDC flows:
the
didclaim - Configuration: every setting