Issuer Concepts & Architecture

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

Wallet Interoperability

The SIROS ID Issuer is designed to work with any standards-compliant digital wallet—not just the SIROS ID Credential Manager. Any wallet implementing the OID4VCI specification with supported credential formats can receive credentials from a SIROS ID Issuer.

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 OID4VCI support
Third-party wallets – any wallet implementing OID4VCI and supported formats (SD-JWT VC, mDL/mdoc, W3C VC 2.0)

Multi-Wallet Support

A single issuer deployment can issue credentials to multiple different wallet implementations. The OID4VCI protocol ensures consistent behavior across all compliant wallets.

What is a Credential Issuer?

A credential issuer is a service that creates digitally signed credentials and delivers them to user wallets. The issuer acts as a bridge between your existing identity infrastructure and the emerging world of verifiable credentials.

The issuer:

Authenticates users via existing identity providers (SAML, OIDC) or API-based flows
Collects claims from your authoritative sources (via IdP or direct API integration)
Constructs credentials following standardized schemas
Signs credentials using cryptographic keys
Delivers credentials to user wallets via OID4VCI protocol

Integration Patterns

The SIROS ID Issuer supports two main integration patterns:

Pattern	Best For	Documentation
IAM-Centric	Existing IdPs, SSO, federation	SAML IdP, OIDC Provider
API-Centric	Backend systems, batch issuance, pre-authorized flows	API Integration

IAM-Centric Integration

Users authenticate via your identity provider (SAML or OIDC), and the issuer constructs credentials from the identity claims. This is the traditional model for organizations with established IdP infrastructure.

API-Centric Integration

Authentic sources (HR systems, registries, databases) push document data via REST/gRPC APIs. Users collect credentials using pre-authorized codes without additional authentication. This is ideal for:

Batch issuance: Provisioning credentials for many users at once
Non-IAM workflows: Where identity is established outside the IdP
Authentic source systems: Direct integration with authoritative data

Core Concepts

Verifiable Credentials

A verifiable credential is a tamper-evident digital document that makes claims about a subject (typically a person). Like a physical credential (passport, ID card, diploma), it contains:

Component	Description	Example
Issuer	Who issued the credential	`https://issuer.example.org`
Subject	Who the credential is about	The holder's identifier
Claims	Statements about the subject	Name, birth date, etc.
Proof	Cryptographic signature	Digital signature + public key
Validity	When the credential is valid	Issue date, expiration

Credential Formats

The SIROS ID Issuer supports multiple credential formats to meet different use cases:

Format	Standard	Best For	Selective Disclosure
SD-JWT VC	IETF SD-JWT VC	EU Digital Identity, general use	✅ Yes
mDL/mDoc	ISO 18013-5	Mobile driving licenses	✅ Yes
W3C VC 2.0 (`ldp_vc`)	W3C VC Data Model 2.0 with Data Integrity proofs	Linked-data ecosystems	Depends on cryptosuite
JWP (blind BBS)	IETF JSON Web Proof	Unlinkable presentations	✅ Yes

Recommended Format

SD-JWT VC is the recommended format for new deployments. It provides selective disclosure (users can share only necessary claims) and is the format specified by the EU Digital Identity Wallet Architecture Reference Framework (ARF).

Credential Types

A credential type defines the schema and semantics of a credential. Each type specifies:

VCT (Verifiable Credential Type): A unique identifier (URN or URL)
Claims: What information the credential contains
Display: How to present the credential in wallets
Trust framework: Which authorities can issue it

VCTM (Verifiable Credential Type Metadata)

Each credential type is defined by a VCTM file that specifies:

{
  "vct": "urn:eudi:pid:1",
  "name": "Person Identification Data",
  "description": "EU Person Identification Data credential",
  "display": [
    {
      "lang": "en-US",
      "name": "PID",
      "rendering": {
        "svg_templates": [...]
      }
    }
  ],
  "claims": [
    {
      "path": ["given_name"],
      "mandatory": true,
      "sd": "always",
      "display": [{"lang": "en-US", "label": "First name"}]
    }
  ]
}

Shipped Credential Types

The vc repository metadata/ directory ships type metadata for common types, which you reference from common.credential_metadata:

Type	VCT / doctype	File
PID	`urn:eudi:pid:1`	`vctm_pid.json`
EHIC	`urn:eudi:ehic:1`	`vctm_ehic.json`
PDA1	`urn:eudi:pda1:1`	`vctm_pda1.json`
Diploma	`urn:eudi:diploma:1`	`vctm_diploma.json`
ELM	`urn:eudi:elm:1`	`vctm_elm.json`
Microcredential	`urn:eudi:micro_credential:1`	`vctm_microcredential.json`
eduID	`urn:credential:eduid:1`	`vctm_eduid.json`
PID (mdoc)	`eu.europa.ec.eudi.pid.1`	`pid_mdoc.mdoc.json`
mDL (mdoc)	`org.iso.18013.5.1.mDL`	`mdl.mdoc.json`

Which schema a scope uses is determined by the VCTM (or MDDL) file it points at in common.credential_metadata.

Building the Claim Set

Turning authenticated user data into credential claims takes three pieces of configuration:

common.credential_metadata.<scope> declares the credential type — which VCTM (or MDDL, for mdoc) describes it, and which format to issue.
apigw.data_sources.<category>.scopes.<scope> says where the data comes from and which auth provider identifies the user.
apigw.auth_providers.<provider>.attribute_mapping normalises the provider's own attribute names to canonical claim names, with optional defaults. Mapping is a rename-and-presence step only; value transformations are derivations on the scope (see below).

APIGW then validates the resulting claim set against the VCTM schema before sending it to the issuer for signing.

common:
  credential_metadata:
    pid:
      vctm_file_path: "/metadata/vctm_pid.json"
      format: "dc+sd-jwt"

apigw:
  auth_providers:
    saml:
      enable: true
      # Map SAML attribute OIDs onto canonical claim names
      attribute_mapping:
        "urn:oid:2.5.4.42":
          claim: "given_name"
          required: true
        "urn:oid:2.5.4.4":
          claim: "family_name"
          required: true
        "urn:oid:0.9.2342.19200300.100.1.3":
          claim: "email_address"

  data_sources:
    # The SAML assertion's claims ARE the credential data
    assertion:
      scopes:
        pid:
          auth_provider: saml
          # Value transformations are derivations on the scope
          derivations:
            - lowercase:
                input: email_address

default: supplies a value when the attribute is absent, and as_array: true wraps a scalar in a single-element array. Available derivation primitives are age_over_thresholds, lowercase, uppercase, trim, country_alpha2, country_alpha3, yyyymmdd_to_iso, swamid_highest_assurance_level and random. Derivations are supported on datastore, assertion, external_api and presentation scopes; each takes an input claim name and, where applicable, an output (default: in place). See the VC Configuration Reference for each primitive's parameters.

Removed configuration

Earlier releases had a top-level credential_constructor section. It no longer exists — use the three sections above instead.

Issuer Components

The SIROS ID Issuer is built as a modular system with distinct components:

Component Descriptions

Component	Purpose	Protocol/Standard
HTTP Server	Exposes OID4VCI endpoints	OpenID4VCI
SAML SP	Service Provider for SAML federations	SAML 2.0
OIDC RP	Relying Party for OIDC providers	OpenID Connect
Session Manager	OAuth2 session and state management	OAuth 2.0
Issuer API	Core credential operations (called by apigw; the REST datastore API is served by apigw)	gRPC
Credential Constructor	Builds credentials from claims	Internal
Signing Service	Cryptographic signing (SW or HSM)	JWS, COSE
Status Lists	Revocation status tracking	Token Status List
Audit Log	Compliance and monitoring	Internal

Service Architecture

The issuer runs as three separate services (apigw, issuer and registry, each its own binary and container image) that talk gRPC to each other and share a MongoDB:

All three can run on one host (for example with Docker Compose, see Deployment) or be scaled independently for high availability.

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.

Aspect	Details
Setup	Minutes – configure via SIROS ID portal
Maintenance	Fully managed by SIROS
Data location	SIROS ID cloud infrastructure
Customization	Credential types, branding
Best for	Quick deployment, SaaS model

Model 2: Self-Hosted (On-Premise)

Deploy the full issuer stack in your own infrastructure.

Aspect	Details
Setup	Hours to days – deploy containers/VMs
Maintenance	Your operations team
Data location	Your infrastructure
Customization	Full control over all components
Best for	Data sovereignty, compliance, custom integrations

Model 3: Hybrid

Combine hosted and self-hosted components.

Aspect	Details
Setup	Variable
Maintenance	Shared responsibility
Data location	Credentials on-premise, trust in cloud
Customization	Selective control
Best for	Regulated environments with external trust requirements

Model 4: Standalone Issuer

Minimal single-host deployment for testing or air-gapped environments: the same three services and MongoDB, run together on one machine.

Aspect	Details
Setup	Minutes – one Docker Compose file
Maintenance	Minimal
Data location	Local
Customization	Development/testing
Best for	Development, demos, isolated testing

Deployment Decision Matrix

Requirement	Hosted	Self-Hosted	Hybrid	Standalone
Quick setup	✅	❌	⚠️	✅
Data sovereignty	✅	✅	✅	✅
HSM key storage	✅	✅	✅	❌
Custom trust	✅	✅	✅	❌
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

Key Management

The issuer's signing keys are the most critical security asset. Choose the appropriate key storage based on your security requirements:

Key Storage	Interface	Security Level	Use Case
Software Keys	Encrypted file	Development	Local testing, demos
HSM	PKCS#11	Production	Standard production deployments
Certified HSM	PKCS#11 (QSCD)	High Assurance	eIDAS qualified signatures, government issuers

Trust Chain

Credentials are only valuable if verifiers can trust them:

See Trust Services for configuring trust frameworks.

Next Steps

Now that you understand the concepts:

Issuing Credentials – Configure and deploy your issuer
SAML IdP Integration – Connect SAML federations
OIDC Provider Integration – Connect OIDC providers
Trust Services – Configure trust frameworks

Wallet Interoperability​

What is a Credential Issuer?​

Integration Patterns​

IAM-Centric Integration​

API-Centric Integration​

Core Concepts​

Verifiable Credentials​

Credential Formats​

Credential Types​

VCTM (Verifiable Credential Type Metadata)​

Shipped Credential Types​

Building the Claim Set​

Issuer Components​

Component Descriptions​

Service Architecture​

Deployment Models​

Model 1: SIROS ID Hosted (SaaS)​

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

Model 3: Hybrid​

Model 4: Standalone Issuer​

Deployment Decision Matrix​

Security Considerations​

Key Management​

Trust Chain​

Next Steps​