Skip to main content

Verifier Concepts & Architecture

This document provides a conceptual introduction to the SIROS ID Verifier, explaining key concepts, components, and deployment models. For hands-on configuration, see Verifying Credentials.

Wallet Interoperability​

The SIROS ID Verifier is designed to accept credential presentations from any standards-compliant digital wallet—not just the SIROS ID Credential Manager. Any wallet implementing the OpenID4VP specification with supported credential formats can participate in verification flows.

Compatible wallets include:

  • SIROS ID Credential Manager (based on wwWallet) – used in examples throughout this documentation
  • EUDI Reference Wallet – the EU Digital Identity reference implementation
  • Native mobile wallets – iOS and Android applications with OID4VP support
  • Third-party wallets – any wallet implementing OID4VP and supported formats (SD-JWT VC, mDL)
Multi-Wallet Support

A single verifier deployment can accept presentations from multiple different wallet implementations simultaneously. Users choose their preferred wallet, and the protocols ensure consistent verification behavior.

What is a Credential Verifier?​

A credential verifier is a service that validates digital credentials presented by users and extracts verified claims for your applications. The verifier acts as a bridge between user wallets and your existing identity infrastructure, enabling privacy-preserving authentication based on verifiable credentials.

The verifier:

  • Requests specific credentials and claims from user wallets
  • Validates cryptographic signatures and issuer trust
  • Checks revocation status and credential expiration
  • Extracts claims and maps them to standard OIDC tokens
  • Integrates with existing IAM systems (Keycloak, Okta, etc.)

Core Concepts​

Credential Presentation​

A credential presentation is the process where a user shares verified claims from their wallet with a relying party. Unlike traditional authentication where users prove who they are, credential presentation proves specific attributes about the user.

Selective Disclosure​

Selective disclosure allows users to share only the specific claims needed for a transaction, not the entire credential. This is a fundamental privacy feature of modern credential systems.

ScenarioTraditional AuthSelective Disclosure
Age verificationShow full IDShare only "over_18: true"
Name verificationShare full profileShare only "given_name"
Nationality checkShare passportShare only "nationality"

Presentation Requests​

A presentation request specifies what credentials and claims the verifier needs. It can be defined using:

  1. OIDC Scopes – Simple mapping (openid pid): a scope selects a credential type configured on the verifier
  2. DCQL Queries – Fine-grained control over credential types and claims

DCQL is the only query language the verifier supports.

Presentation requests are defined in presentation_requests/*.yaml. Each file holds a templates: list; a template binds OIDC scopes to a DCQL query and a claim mapping:

templates:
- id: "pid_basic"
name: "PID - Basic Profile"
oidc_scopes: ["pid", "profile"]
dcql:
credentials:
- id: identity_credential
format: dc+sd-jwt
meta:
vct_values:
- urn:eudi:pid:1
claims:
- path: ["given_name"]
- path: ["family_name"]
- path: ["birthdate"]
claim_mappings:
"*": "*"

Trust Verification​

The verifier doesn't blindly accept credentials—it validates them against a trust framework to ensure they come from authorized issuers. This evaluation is delegated to an AuthZEN Policy Decision Point (PDP) such as go-trust, configured with verifier.trust.pdp_url.

A PDP is required for production

Without verifier.trust.pdp_url the verifier runs in "allow all" mode: every issuer is trusted, only did:key and did:jwk are resolved (locally; other DID methods are unavailable), and only a log warning is emitted. That mode may work for some things but is not supported: development and testing only.

Trust SourceStandardUse Case
ETSI TSLETSI TS 119 612EU trust services
LoTEETSI TS 119 602JSON-based trusted entity lists
OpenID FederationOpenID Federation 1.0OIDC ecosystems
X.509 ChainsRFC 5280Enterprise PKI
DID ResolutionW3C DIDDecentralized identity

RP Certificate Validation​

When presenting credentials to a verifier, the verifier may present an RP Registration Certificate (WRPRC) or RP Access Certificate (WRPAC) to prove its identity and entitlements. Go-Trust validates these certificates against the applicable profile (e.g., ETSI TS 119 411-8) and extracts:

  • RP identity — organization, country, subject type, contact information
  • Entitlements — which attributes the RP is authorized to request
  • Over-request detection — whether the RP is requesting more data than its entitlements allow

This information is returned to the wallet so the user can make an informed consent decision. See Over-Request Detection for details.

Verifier Components​

The SIROS ID Verifier is built as a modular system:

Component Descriptions​

ComponentPurposeProtocol/Standard
OIDC EndpointsStandard OIDC provider interfaceOpenID Connect 1.0
Session ManagerOAuth2 session and state managementOAuth 2.0
Token ServiceIssue ID tokens with verified claimsJWT, JWS
Request BuilderCreate OpenID4VP presentation requestsOpenID4VP
QR GeneratorGenerate QR codes for cross-device flow-
DC API HandlerW3C Digital Credentials API supportDC API
Response HandlerProcess wallet responsesOpenID4VP
Signature ValidatorVerify credential signaturesSD-JWT, mDL
Trust EvaluatorCheck issuer authorizationAuthZEN
Status CheckerVerify revocation statusToken Status List

Protocol Interfaces​

The verifier exposes two primary interfaces:

1. OpenID Connect Provider​

Standard OIDC interface that integrates with any IAM system:

Benefits:

  • Drop-in replacement for traditional IdPs
  • No code changes to existing applications
  • Works with any OIDC-compliant IAM

2. OpenID4VP Direct​

The verifier speaks OpenID4VP to wallets directly: the QR code, same-device link and Digital Credentials API all deliver an OpenID4VP request object that the wallet answers at the verifier's direct_post endpoint.

A presentation session is always created by the OIDC /authorize request, and the page that drives the wallet is served by the verifier itself. There is no separate endpoint that starts a session, and no API that hands a session to your backend; your application receives the verified claims through the OIDC code exchange.

Benefits:

  • Wallet-facing protocol is standard OpenID4VP
  • Customisable verifier page (themes, logo, credential preview)
  • QR, same-device and browser-native flows from one endpoint

Cross-Device vs Same-Device Flow​

Cross-Device Flow​

User authenticates on a desktop browser using their mobile wallet:

Same-Device Flow​

User authenticates on mobile using a wallet on the same device:

W3C Digital Credentials API​

Native browser integration (in browsers that implement the API):

Deployment Models​

Choose a deployment model based on your requirements:

Model 1: SIROS ID Hosted (SaaS)​

Use the SIROS ID cloud platform with minimal configuration.

AspectDetails
SetupMinutes – register via SIROS ID portal
MaintenanceFully managed by SIROS
Data locationSIROS ID cloud infrastructure
CustomizationPresentation requests, claim mapping
Best forQuick integration, SaaS model

Model 2: Self-Hosted (On-Premise)​

Deploy the full verifier stack in your own infrastructure.

AspectDetails
SetupHours – deploy containers/VMs
MaintenanceYour operations team
Data locationYour infrastructure
CustomizationFull control over all components
Best forData sovereignty, compliance, custom trust

Model 3: Hybrid​

Combine self-hosted verifier with hosted trust services.

AspectDetails
SetupVariable
MaintenanceShared responsibility
Data locationPresentations on-premise, trust in cloud
CustomizationSelective control
Best forRegulated environments needing external trust

Deployment Decision Matrix​

RequirementHostedSelf-HostedHybrid
Quick setup✅❌⚠️
Data sovereignty✅✅✅
Custom trust policies✅✅✅
High availability✅⚠️⚠️
Zero maintenance✅❌⚠️
GDPR compliance✅✅✅
EU/EES Hosting

All SIROS ID hosted services are operated from EU/EES infrastructure, ensuring data sovereignty and GDPR compliance for European customers.

Legend: ✅ Excellent | ⚠️ Possible with effort | ❌ Not recommended

Security Considerations​

Privacy by Design​

The verifier implements privacy-preserving practices:

FeatureDescription
Pairwise IdentifiersWith subject_type: pairwise, users get a different sub per relying party
Selective DisclosureOnly requested claims are revealed
Short-lived StorageVerified credentials and session context are cached only for the session (minutes) and then expire
Minimal DataRequest only what you need

Trust Evaluation​

Every credential is validated through the configured trust PDP (verifier.trust.pdp_url); without a PDP, issuer trust is not evaluated (development and testing only):

Session Security​

ProtectionImplementation
PKCERequired for every client registered via /register
StatePrevents CSRF attacks
NoncePrevents replay attacks
Short-lived codes5-minute authorization codes
Token bindingTokens bound to client

Next Steps​

Now that you understand the concepts:

  1. Verifying Credentials – Configure and deploy your verifier
  2. Keycloak Integration – Add to Keycloak as an IdP
  3. Direct OIDC Integration – Integrate as an OIDC RP
  4. Trust Services – Configure trust frameworks