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, JWT VC)

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
JWT VC	W3C VC Data Model	Legacy systems	❌ No

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:arf-1.8:1",
  "name": "Person Identification Data",
  "description": "EU Person Identification Data credential (ARF 1.8)",
  "display": [
    {
      "lang": "en-US",
      "name": "PID",
      "rendering": {
        "svg_templates": [...]
      }
    }
  ],
  "claims": [
    {
      "path": ["given_name"],
      "mandatory": true,
      "sd": "always",
      "display": [{"lang": "en-US", "label": "First name"}]
    }
  ]
}

Built-in Credential Types

SIROS ID includes pre-configured types based on EU standards:

Type	VCT	Description
PID (ARF 1.5)	`urn:eudi:pid:arf-1.5:1`	Person Identification Data (ARF 1.5)
PID (ARF 1.8)	`urn:eudi:pid:arf-1.8:1`	Person Identification Data (ARF 1.8+)
EHIC	`urn:eudi:ehic:1`	European Health Insurance Card
PDA1	`urn:eudi:pda1:1`	Portable Document A1
Diploma	`urn:eudi:diploma:1`	Educational credentials
ELM	`urn:eudi:elm:1`	European Learning Model
Microcredential	`urn:eudi:micro_credential:1`	Short learning achievements
OpenBadge	`urn:eudi:openbadge_complete:1`	Open Badges 3.0

ARF Version Selection

SIROS ID supports both ARF 1.5 and ARF 1.8 PID schemas. The configuration credential_constructor key determines which schema is used. The generic VCT urn:eudi:pid:1 is accepted for compatibility but maps to a configured ARF version.

Credential Constructor

The credential constructor is the component that transforms user identity data into credential claims. It:

Receives authenticated user attributes (from SAML/OIDC)
Maps external attributes to credential claims
Applies transformations and defaults
Validates against the VCTM schema
Produces the claim set for signing

# Example: Map SAML attributes to PID claims
credential_constructor:
  pid_1_8:
    vct: "urn:eudi:pid:arf-1.8:1"
    vctm_file_path: "/metadata/vctm_pid_arf_1_8.json"
    attributes:
      given_name:
        source: ["$.claims.given_name", "$.saml.urn:oid:2.5.4.42"]
      family_name:
        source: ["$.claims.family_name", "$.saml.urn:oid:2.5.4.4"]
      birthdate:
        source: ["$.claims.birthdate"]
        transform: "date_iso8601"

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	gRPC + REST
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 can run as a single process or as separate microservices:

Single Process Mode

All components in one binary—simplest deployment for development and small-scale production.

Microservices Mode

Separate services for independent scaling and 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 deployment for testing or air-gapped environments.

Aspect	Details
Setup	Minutes – single Docker container
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)​

Built-in Credential Types​

Credential Constructor​

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​