Roles & role mapping
How the abstract Issuer/Holder/Verifier roles map onto OpenResidency's concrete parties — the Provider, the code, relying parties, operators, and the deployer.
In plain terms. The previous page named three abstract roles. This page says who actually plays them in a real deployment — which body issues the credential, who carries it, and which office checks it at the counter.
The VC roles are abstract. This page maps them onto the concrete parties you'll meet in the code and in the field — including the ones that cause the most confusion.
The core mapping
| Concrete party | VC role | What it is |
|---|---|---|
| State Residency Platform (a deployment) | Issuer + OIDC Provider | The running, state-operated system that authenticates citizens and signs credentials. Identified by its issuer URL, e.g. https://id.katsina.gov.ng/oidc. |
| OpenResidency (the code) | — | The open-source software that makes a deployment an issuer/provider. It is the engine, not the authority. |
| Citizen / resident + wallet | Holder | Holds the credential; presents it to sign in or prove residency. |
| Sector services (Health, Tax, …) | Verifier (of SSO claims) | Relying parties that trust the provider's login instead of running their own. |
| Offline verifiers (clinic, checkpoint, bank) | Verifier | Anyone checking a credential against the published keys + status list. |
| Operators (staff) | — (act for the Issuer) | Government staff who enrol citizens and issue/revoke credentials. |
| Deployer (DevOps) | — (stands up the Issuer) | The day-0 actor who provisions config, keys, and secrets. |
Software vs deployment — say it precisely
A deployment is the OIDC Provider / Issuer; OpenResidency the code is what makes it one. "OpenResidency is the provider" is loose shorthand; the provider that exists in the world is the operated instance (its issuer URL, its keys, its client registry).
Provider vs Relying Party (the OIDC pair)
OpenID Connect has two sides, and both are "parties" — don't conflate them:
- OIDC Provider (OP / Identity Provider) — authenticates the user and issues tokens. This is
the residency platform. It owns the login screen and mints the
id_token. - Relying Party (RP / client) — a sector service that relies on the provider for identity
instead of logging users in itself. Registered as an OIDC client with a
client_id+ secret.
Everyday analogy: with "Sign in with Google," Google is the provider and the app is the relying party. Here the state platform is Google's role — "Sign in with <State>".
Each sector RP is distinct: its own client_id, its own sector scope (gating which residency
claims it may request), its own pairwise subject (a different opaque user id per service, so
two services can't correlate a citizen), and its own consent record. Defined declaratively in
each jurisdiction's YAML — see
config/countries/demo.yaml.
Operator vs Verifier — opposite ends of the credential
A frequent mix-up. They are different actors on opposite ends of the lifecycle:
- An operator is government staff who work for the issuer: they enrol citizens and issue or revoke credentials. Authenticated, role-scoped, named in the audit log. Input side.
- A verifier is whoever receives a credential and checks it — usually a third party, often anonymous, using the public keys + status list. Output side. A citizen never becomes an operator by signing in.
See the full principal list, tier by tier, in the Actor catalog.
In the code
- Provider (OIDC) →
sso/oidc.provider.ts, mounted at/oidcinmain.ts - Relying parties →
oidc.relyingPartiesin the country config - Operators →
core/operator/operator.ts+common/operator.guard.ts - Verifiers →
VcVerifier/VpVerifier(logic anyone can run; no account in OpenResidency)
The Verifiable Credentials model
Issuer, Holder, and Verifier — the three roles of the W3C Verifiable Credentials triangle, and the difference between verifying a credential and verifying a presentation.
The actor catalog
Every principal in OpenResidency, organised by authentication posture — anonymous, authenticated human, authenticated machine, and external system.