Skip to content

Consumer guide

A consumer is a party that wants the user's documents or records. In the primary remote topology it is a separate site calling the vault's HTTP API as an OAuth client (see Remote consumers below); it can equally be an in-Drupal workflow on the vault site itself. Either way it is modeled by the Consumers module and identified (by its client id, or its OAuth token cross-site) before any access is granted.

You can exercise the same-site flows by hand from the Test Console. The underlying flows, common to both topologies, are:

Request access

The consumer asks the owner for one or more kinds in a single ceremony (e.g. "your id_card and your passport"). An access request appears in the owner's vault listing every requested kind. The owner reviews them together and decides per kind: bind a kind to one of their items (grant) or refuse it (deny). On approval the consumer holds a grant for each granted item.

The consumer can supply a return_url + state token at request time; once the owner submits their per-kind decisions, pdv redirects the browser back to that URL with state, correlation_id, granted[] and denied[] query parameters. This is the same cross-site round-trip the store-request flow performs.

Read

The consumer reads an item it is authorized for. A read succeeds when the consumer holds either:

  • a grant for that specific item, or
  • a read-trust for the item's kind (a standing pre-authorization the owner set up).

Without one, the read is denied. Reading a record returns its field values as JSON; reading a document returns the file bytes.

Store request ("Save to vault")

The consumer asks the vault to store an item (a file body or, equivalently, a record body -- a record is just an item without a filename). What happens depends on trust:

  • If the consumer holds a write-trust for the kind, the item is stored and granted immediately, with no consent page.
  • Otherwise the request is parked as a pending store request. The owner reviews it on their vault page and approves or declines. They may also choose to start trusting the consumer from there.

For a unique kind that already exists, a store request always parks for owner review so the replacement is explicit, even when the consumer is trusted.

Consent is always captured on the vault site, never asserted by the consumer. A pre-authorization ("trust") is the only way to skip the per-interaction prompt, and it too is created on the vault site by the owner.

Remote consumers (cross-site)

A remote consumer is a separate site using the pdv_client module. It runs the flows above over the HTTP API:

  1. Authenticate. It obtains an OAuth client-credentials token (its secret lives in a Key, not config). The token says which consumer is calling, nothing about a user.
  2. Link the user once. The user completes the consent ceremony, which returns an opaque handle for the (connection, user) pair; the client stores it in user.data (keyed vault_handle:<connection_id>, so a user linked on several connections keeps one handle each) and addresses the user by it thereafter (never by uid). The handle is the vault uid encrypted (AEAD) under a per-consumer key, so it is safe at rest: it reveals no uid and is useless without that connection's OAuth secret.
  3. Read and write through the API with that handle.

Read and write are orthogonal cross-site too. A read (prefill) needs a read grant/trust; a save-back needs a write grant/trust; neither implies the other. An unauthorized write does not park a store request (that is the same-site flow above) - the API answers consent_required with a consent URL, and the client sends the user through the ceremony to grant write access, then retries. To choose create vs. update without read access, a write-only consumer lists its writable items (scope=write).

With PDV Webform on the consumer, all of this is wired up: mapped fields prefill from the vault (read) and a ticked save-back consent writes them back (write), each prompting its own grant as needed. See Client-server configuration to set it up.