Decentralized Identifiers and Verifiable Credentials (Complete Guide)
Decentralized identifiers (DIDs) are key-controlled identifiers that resolve to a DID document with verification methods and optional service endpoints. Verifiable credentials (VCs) are signed claims you can store in a wallet and present when needed, ideally with selective disclosure and offline status checks. This guide explains the mental model, method choices, issuance and verification flows, revocation design, privacy traps, Web2 interoperability, and on-chain integration patterns. The goal is practical: portable identity that stays useful to apps without becoming a surveillance layer.
TL;DR
- DIDs are identifiers controlled by keys and resolved into DID documents that define which keys are valid for which actions.
- VCs are signed claims: issuer signs, holder stores, verifier checks signature, policy, and status.
- Most real products use: wallet authentication (SIWE or equivalent) plus VC-based authorization (role, membership, compliance indicator).
- Privacy comes from pairwise identifiers, selective disclosure, and offline status checking that avoids phoning home.
- Presentations must be bound to a fresh challenge and an audience to stop replay and relay attacks.
- Revocation must scale: prefer signed status lists with caching and freshness rules.
- Use DIDs and VCs for signals and rights, not for secrets. Never put personal identity data on public chains.
The fastest way to break a DID and VC rollout is to treat it as “a new login button” and skip threat models. DIDs and VCs introduce new keys, new signing surfaces, and new privacy risks. If you design the system well, you unlock portable access, reusable compliance signals, and composable roles that do not depend on one vendor. If you design it poorly, you ship a tracking layer users avoid and attackers exploit.
1) What DIDs and VCs actually solve
Web2 identity is usually a platform account. Your identifier is controlled by a database. If you switch platforms, your identity fragments. Web3 wallets improved asset ownership, but identity remains messy: a wallet address is an identifier, yet it is not built to carry rich claims safely.
DIDs and VCs are complementary building blocks for portable identity. A DID is a global identifier you control through keys. It resolves to a DID document that tells verifiers which public keys are valid for which actions. A VC is a signed claim an issuer makes about a subject. The holder stores it in a wallet and later produces a verifiable presentation to satisfy a verifier’s request.
The critical design shift is that verification can happen without constantly calling the issuer. Verifiers validate signatures with issuer keys from DID resolution, then check revocation via signed, cacheable status lists. That reduces outages and reduces tracking.
2) Mental model you can build products with
A clean mental model prevents most implementation mistakes. Think in four layers: identifiers, resolution, credentials, and presentations. Each layer has a different security boundary.
A) Identifiers (DIDs)
A DID looks like did:<method>:<specific-id>. The method defines how the identifier is created, resolved, updated, and deactivated. DIDs are not “accounts.” They are references to keys and optional service hints.
B) Resolution (DID documents)
A DID resolves to a DID document (usually JSON) that lists verification methods and relationships such as authentication (login), assertionMethod (issuing claims), and keyAgreement (encryption). Correct relationship checks matter because not every key in the document should be trusted for every action.
C) Claims (Verifiable Credentials)
A VC is a signed claim like “completed training,” “member in good standing,” or “KYC indicator valid.” It usually includes an issuer identifier, a subject identifier, issuance and expiry metadata, and a status reference for revocation or suspension checks.
D) Proofs (Verifiable Presentations)
A verifiable presentation is what the holder generates for a verifier request. It should bind to a fresh challenge and an audience (domain) so captured proofs cannot be replayed somewhere else.
Wallet signatures prove control of a key. Credentials prove properties and rights. Mixing these layers causes two failures: over-disclosure or replayable authorization. A safer default flow is: wallet control proof, then a credential presentation bound to the same session challenge, then policy evaluation.
3) DID methods: choosing the right method for the job
There is no single perfect DID method. Method choice is a tradeoff between governance, rotation, infrastructure, and interoperability. For most teams, it helps to group methods into four practical buckets.
| Bucket | Typical DID | Best use | Rotation story | Main risk |
|---|---|---|---|---|
| Wallet derived | did:pkh:chain:address | Login and lightweight user IDs | Tied to wallet account model | Harder to express rich key roles |
| Web anchored | did:web:domain | Issuer identities, institutions | Update hosted DID document | Hosting compromise or outage |
| Registry anchored | did:ethr:chain:addr | Auditable key changes, delegation | On-chain key updates | Fees and chain dependency |
| Self describing | did:key:multibase | Pairwise, offline, private flows | New DID on rotation | Harder long-term continuity |
Method selection cheat sheet
- Issuers: start with did:web if you have domain control and want predictable rotation.
- Holders: use did:pkh for wallet-bound authorization signals, plus pairwise options for privacy.
- High privacy sessions: use did:key or pairwise DIDs so different verifiers cannot correlate users.
- Audit-heavy ecosystems: consider registry methods, but treat registry governance like production infrastructure.
4) DID documents: what matters for security
DID documents link identifiers to cryptographic material. The verifier failure mode is predictable: teams accept “any key in the DID document” rather than the correct relationship for the action. If an issuer signs credentials, verifiers should accept only keys under assertionMethod.
Verifier safety rules for DID documents
- Resolve issuer DID, then verify signatures with assertionMethod keys only.
- Pin accepted algorithms and reject unexpected suites.
- Cache DID documents, but enforce integrity checks and refresh rules.
- Log which issuer DID and key ID were used for the decision.
5) Verifiable credentials: formats, trust, and the part everyone underestimates
Signatures prove “issuer X signed this.” They do not prove “your app should accept it.” Acceptance is policy: which issuers are trusted for which credential types and schema versions, under which algorithms and freshness rules.
| Format family | Strength | Weakness | Best for |
|---|---|---|---|
| JWT VC | Compatibility, compact, familiar to OAuth teams | Selective disclosure needs extra technique | Fast adoption, enterprise rollouts |
| Data Integrity | Flexible proofs, extensible suites | More complexity in proof tooling | Mixed ecosystems and evolving standards |
| Anonymous credentials | Unlinkable proofs, predicates like “over threshold” | Heavier integration, wallet variance | High privacy gating |
6) Issuance: how credentials are delivered safely
Issuance is where privacy and support tickets are decided. A good issuance flow clearly shows issuer identity, credential scope, included fields, expiry, status rules, and privacy expectations. If you hide these, users sign blind and phishing becomes easier.
Issuer issuance checklist
- Show exact fields before issuance and collect explicit consent.
- Bind the credential to a holder key so a stolen link cannot steal the VC.
- Minimize attributes and avoid embedding sensitive personal data.
- Publish status with revocation or suspension and document refresh behavior.
- Operate issuer signing keys with hardened controls, not a hot laptop key.
7) Presentation and verification: making proofs non-replayable
The verifier should request the minimum evidence needed, require a fresh challenge, and enforce domain binding. Without challenge and audience binding, a captured presentation can be replayed or relayed.
Verifier checklist: minimum viable hardening
- Generate a strong nonce per request and store it server-side until consumed.
- Require audience binding that matches your service domain.
- Enforce a short freshness window for presentations.
- Allowlist issuers per credential type and schema version.
- Verify signatures using the correct DID relationship (assertionMethod for issuers).
- Check status via signed lists with freshness rules.
- Store decisions and audit traces, not raw credential payloads.
8) Revocation, suspension, expiry, and status lists
Credentials must support lifecycle controls. If you call an issuer API on every login, you create tracking and outages. If you never check status, you accept stale privileges. Signed status lists are the scalable middle ground.
| Mechanism | What it solves | What can go wrong | Best practice |
|---|---|---|---|
| Expiry | Time-bound claims | Confusing renewal UX | Clear renewal path and grace handling |
| Revocation | Permanent invalidation | Overuse breaks UX | Reserve for compromise and final decisions |
| Suspension | Temporary disable | Becomes indefinite limbo | Define max windows and appeals process |
| Status lists | Offline scalable checking | Stale caches accept revoked VCs | TTL rules plus signature validation |
9) Privacy and anti-correlation: stop identity from becoming surveillance
DIDs and VCs can either protect users or harm them. Harm usually comes from correlation and over-collection. Build privacy as a layered defense: pairwise identifiers, selective disclosure, fresh binding, and offline verification.
Privacy checklist for verifiers
- Request the minimum attributes needed for the decision.
- Require nonce and audience binding for every presentation.
- Prefer pairwise holder identifiers when possible.
- Verify status offline via signed lists, not issuer calls per login.
- Store decisions and minimal audit traces, not full VC payloads.
10) Bridging to Web2: SSO reality without a rewrite
Most organizations already run SSO with OIDC or SAML and role-based access control. A practical adoption pattern is an OIDC facade: verify VC presentations at a gateway, then mint standard OIDC tokens to downstream services. Downstream services remain unchanged while you gradually migrate to richer verification.
11) Using DIDs and VCs with on-chain apps
Smart contracts are not great at verifying complex JSON signatures economically. That pushes most DID and VC designs toward bridging patterns. The most common approach is off-chain verification plus minimal on-chain signals.
- Off-chain verify, on-chain attest: verifier checks the presentation, then writes a minimal “policy satisfied” attestation on-chain.
- Minimal on-chain indicators: keep sensitive attributes off-chain and use only a non-sensitive flag on-chain.
- Session keys: after verification, issue short-lived session keys with limited scope for smoother UX.
On-chain data is public and durable. If you need on-chain gating, use minimal indicators. Keep real attributes inside credentials and present them privately only when required.
12) Developer cookbook: copyable patterns and hardening steps
This is the section most teams revisit. It converts standards language into steps that reduce incidents and support churn.
A) Verifier checklist (production)
- Nonce: generate a nonce per request and store it server-side until used.
- Audience: require a domain binding that matches your service.
- Freshness: reject stale proofs beyond a short window.
- Issuer trust: allowlist issuer DIDs per credential type and schema version.
- Key relationship: verify issuer signatures with assertionMethod keys.
- Status: cache signed status lists and enforce freshness thresholds.
- Retention: log decisions and key IDs, not raw credentials.
B) Issuer checklist (production)
- Signer isolation: operate signing keys behind hardened controls.
- Rotation: publish rotation policy and overlap windows.
- Status lists: sign, timestamp, and host in cache-friendly ways.
- Schemas: version schemas and avoid silent meaning changes.
- Support: document issuance, revocation, and reissue processes.
13) Anti-patterns that silently destroy trust
- Presentations without nonce and audience: replay and relay become trivial.
- Calling issuers on every login: creates tracking and outages. Prefer signed status lists.
- Collecting full credentials: increases breach impact and breaks minimization.
- One identifier everywhere: correlation grows fast. Prefer pairwise or scoped identifiers.
- Hot issuer keys: compromises become catastrophic. Harden signing operations.
- Putting personal data on-chain: irreversible harm risk.
FAQs
Do I need a blockchain to use DIDs and verifiable credentials?
No. Some DID methods use blockchains, but others use HTTPS (did:web) or require no network (did:key). Credentials can be issued and verified without chain transactions if signatures and status mechanisms are in place.
Can a verifier validate a credential without contacting the issuer?
Yes. Resolve the issuer DID document to obtain keys, verify the credential signature, then check revocation or suspension using signed status lists cached locally.
How do I prevent replay attacks with verifiable presentations?
Require a fresh challenge (nonce) and an audience or domain binding in the presentation proof, store the nonce server-side until used, and enforce short validity windows.
What is the difference between a DID and a wallet address?
A wallet address is an account identifier on a chain. A DID resolves to a DID document that can express multiple keys and relationships for different actions.
Should I put “KYC verified” on-chain for gating?
Avoid putting personal identity details on-chain. If you need an on-chain gate, use a minimal indicator and keep real attributes inside credentials off-chain.
References
Official standards and reputable references you can use to go deeper:
- W3C DID Core
- W3C Verifiable Credentials Data Model
- W3C Verifiable Credentials Data Model 2.0
- EIP-4361: Sign-In with Ethereum (SIWE)
- Decentralized Identity Foundation (DIF)
Turn identity into safer, composable signals
The winning pattern is consistent: verify wallet control, present credentials with minimal disclosure, check status offline, and enforce trust policy explicitly. If you design for privacy, rotation, and incident response from day one, DIDs and VCs become a practical foundation for membership, roles, and compliance signals.
Conclusion: portable identity works when you design for minimization and change
DIDs and verifiable credentials are a toolkit for portable rights and signals. DIDs provide stable identifiers anchored in keys and documents. Credentials provide signed claims that can be verified without constant issuer calls. Presentations provide a safer way to prove eligibility without leaking everything.
A simple action plan: pick issuer and holder identifier strategies, write a trust policy, enforce nonce and audience binding, implement status lists with caching rules, and minimize retention. Do those consistently and you avoid most hidden traps.
Next: multisig wallets and MPC, practical shared control for teams and treasury vaults. Open the next guide.
