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’s Host header 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.

Changing global.publicBaseUrl, or the realm’s path, does not rewrite a DID already published. It keeps the host and path it was minted on, and it stops resolving if that address no longer reaches this realm. The setting’s description on the console says so.

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.

The document is public. Anyone who learns the DID can resolve it and recognise the person by it, including across applications. It is a public signing identity, and the portal says that where it is created.

The key it names is not a key already enrolled for sign-in. In wallet custody the wallet proves a key that is not one of the person’s sign-in subjects (STS-VC-0178). The published DID is then enrolled as its own subject and can sign in; the document is not a public copy of a key the person already signed in with. A key the realm generates (realm and download custody) is new, so it is not one of those subjects.

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’s didDocumentMetadata: created, updated, versionId, nextVersionId and, 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. wallet is the most secure choice. With realm, the realm holds a key that can act as the person. With download, the private key passes through the browser once. Choose them only where that is acceptable.

Changing the keys

  • wallet custody takes two proofs in one act, each a wallet round trip started from the DID’s Add key or Rotate key:
    1. the wallet signs as the DID, with a key its current version names. This authorizes the change, for ten minutes;
    2. the wallet proves the new key with its own did:jwk, did:key or 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.

  • realm custody: 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.
  • download custody: prove the downloaded key first (Enrol a wallet, signing as the DID). The DID then changes keys as a wallet one 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 wallet custody this is a link to the wallet round trip. In the other two it is a button, and in download custody 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:web is 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 wallet custody. 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. The new key is also not one already enrolled for sign-in (STS-VC-0178). The keys the current version already names are refused on their own (STS-VC-0170).
  • Not a public copy of a sign-in key. The document anyone can fetch names a key. Publishing a key the person already signs in with would publish that key. The published DID is its own subject and can sign in afterwards.

In the running service

  • GET /admin/sts-metadata lists 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-0161 to STS-VC-0178).
  • 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.