Issuer Configuration

This guide provides detailed configuration options for the SIROS ID credential issuer. For conceptual background, see Concepts & Architecture. For deployment setup, see Deployment.

After reading this guide, you will understand how to:

• Connect your identity provider to the issuer
• Configure credential types
• Issue credentials to wallets
• Deploy your own issuer (optional)

Endpoints

The SIROS ID issuer exposes standard OID4VCI endpoints. For a self-hosted or on-premise deployment at issuer.example.org:

Endpoint	URL
Credential Offer	https://issuer.example.org/credential-offer
Token	https://issuer.example.org/token
Credential	https://issuer.example.org/credential
Metadata	https://issuer.example.org/.well-known/openid-credential-issuer

SIROS Hosted Service

When using the SIROS ID hosted service, issuers use subdomain-based multi-tenancy:

https://<instance>.<tenant>.issuer.id.siros.org

For example, tenant acme-corp with issuer instance pid:

• https://pid.acme-corp.issuer.id.siros.org/credential-offer
• https://pid.acme-corp.issuer.id.siros.org/.well-known/openid-credential-issuer

Each tenant has isolated configuration, and each issuer instance has its own credential types and signing keys.

Deployment Options

Option	Best For	Requirements
SIROS ID Hosted	Quick start, SaaS model	API credentials only
Self-Hosted (Docker)	On-premise, data sovereignty	Docker, MongoDB
Self-Hosted (Binary)	Custom infrastructure	Go 1.25+, MongoDB

Recommendation

Start with the hosted service for development and testing. Move to self-hosted when you need data sovereignty or custom integrations.

Overview

The SIROS ID issuer implements the OpenID for Verifiable Credential Issuance (OID4VCI) specification. This allows any OID4VCI-compatible wallet to receive credentials from your issuer.

Authentication Methods

The SIROS ID issuer supports multiple ways to authenticate users before issuing credentials:

1. OpenID Connect (OIDC)

Connect any OIDC-compliant identity provider to issue credentials:

# Example OIDC configuration
issuer:
  authentication:
    type: oidc
    client_id: "your-client-id"
    client_secret: "your-client-secret"
    issuer_url: "https://your-idp.example.com"
    scopes:
      - openid
      - profile
      - email

2. SAML 2.0

Use existing SAML 2.0 identity federations. See SAML IdP Integration for detailed configuration:

SAML requires full image

SAML support requires the -full image variant: vc-issuer-full

# SAML is configured in the issuer section
issuer:
  saml:
    enabled: true
    entity_id: "https://issuer.example.org/sp"
    acs_endpoint: "https://issuer.example.org/saml/acs"
    certificate_path: "/pki/sp-cert.pem"
    private_key_path: "/pki/sp-key.pem"
    # Use MDQ for federation metadata lookup
    mdq_server: "https://mds.swamid.se/entities/"
    credential_mappings:
      pid:
        credential_config_id: "urn:eudi:pid:arf-1.8:1"
        attributes:
          "urn:oid:2.5.4.42":
            claim: "given_name"
            required: true

3. Client Credentials

For server-to-server issuance (e.g., automated credential provisioning):

issuer:
  authentication:
    type: client_credentials
    clients:
      - id: "your-system-id"
        secret: "your-system-secret"
        scopes:
          - ehic
          - diploma

Supported Credential Types

SIROS ID supports issuing credentials in multiple formats:

Format	Description	Specification	Use Case
SD-JWT VC	SD-JWT Verifiable Credential	draft-ietf-oauth-sd-jwt-vc	EU Digital Identity, general VCs
mDL/mDoc	ISO 18013-5 mobile document	ISO/IEC 18013-5:2021	Mobile driving licenses
JWT VC	JWT-encoded credential	W3C VC Data Model	Legacy systems

Built-in Credential Types

The SIROS ID platform includes preconfigured schemas for common EU credential types based on the EUDI Wallet Architecture Reference Framework:

Credential	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 (complete)

Credential Type Aliases

For backwards compatibility with some systems, the generic VCT urn:eudi:pid:1 may be accepted and mapped to the appropriate ARF version based on configuration.

Integration Steps

Step 1: Configure Your Identity Provider

Configure your IdP to allow the issuer as a client:

For OIDC IdPs:

1. Register a new OIDC client
2. Set redirect URI to: https://issuer.example.org/callback
3. Enable required scopes (openid, profile, email, etc.)

For SAML IdPs:

1. Import issuer SP metadata
2. Configure attribute release (name, email, etc.)

Step 2: Map Identity Claims to Credential Attributes

Configure how user identity maps to credential claims using the credential_constructor section. Each entry defines a credential type with its Verifiable Credential Type Metadata (VCTM):

credential_constructor:
  ehic:
    # Verifiable Credential Type identifier (appears in issued credential)
    vct: "urn:eudi:ehic:1"
    # Path to VCTM JSON file defining credential schema and display
    vctm_file_path: "/metadata/vctm_ehic.json"
    # Authentication method: "basic" for simple auth, "pid_auth" to require PID
    auth_method: basic
    # Optional: attribute transformations
    attributes:
      given_name:
        source: ["$.claims.given_name"]
      family_name:
        source: ["$.claims.family_name"]

VCTM Files

The VCTM file defines the credential schema, including claim definitions, display names, and localization. Example files are available in the vc repository metadata directory.

Step 3: Configure Trust

Establish trust with the SIROS ID ecosystem. See Trust Services for details on:

• ETSI TSL registration
• OpenID Federation
• X.509 certificate chains

Step 4: Test the Integration

1. Obtain a test wallet: Use the SIROS ID web app at id.siros.org
2. Trigger issuance: Navigate to your issuer's credential offer page
3. Scan QR code: Use the wallet to scan and accept the credential
4. Verify: Check that the credential appears in the wallet

Credential Offer Methods

QR Code

Generate a QR code containing a credential offer:

openid-credential-offer://?credential_offer_uri=https://issuer.example.org/offers/abc123

Deep Link

For mobile apps, use a deep link:

openid-credential-offer://issuer.example.org/offers/abc123

Pre-authorized Flow

For server-initiated issuance (e.g., when user completes registration):

credential_offer:
  type: pre_authorized
  pin_required: true  # Optional: require PIN confirmation

API Reference

The issuer exposes OpenID4VCI-compliant endpoints:

Endpoint	Description
/.well-known/openid-credential-issuer	Credential issuer metadata
/.well-known/oauth-authorization-server	OAuth2 metadata
/authorize	Authorization endpoint
/token	Token endpoint
/credential	Credential endpoint
/batch_credential	Batch credential endpoint

Swagger Documentation

Full API documentation is available at:

https://issuer.example.org/swagger/index.html

Security Considerations

1. Key Management: The issuer signs credentials with keys managed in secure HSMs
2. Revocation: Configure status lists for credential revocation
3. Audit Logging: All issuance events are logged for compliance

Self-Hosted Deployment

If you need to run the issuer in your own infrastructure, you can deploy it using Docker or as a standalone binary.

Docker Deployment (Recommended)

The issuer is available as a Docker image:

# Pull the standard issuer image
docker pull ghcr.io/sirosfoundation/vc-issuer:latest

# Or pull the full image with SAML IdP and VC 2.0 support
docker pull ghcr.io/sirosfoundation/vc-issuer-full:latest

Image Variants

Use vc-issuer-full if you need SAML IdP authentication or W3C VC 2.0 format support. See Docker Images for details.

Docker Compose

Create a docker-compose.yaml:

services:
  issuer:
    image: ghcr.io/sirosfoundation/vc-issuer:latest  # or vc-issuer-full for SAML support
    restart: always
    ports:
      - "8080:8080"
    volumes:
      - ./config.yaml:/config.yaml:ro
      - ./pki:/pki:ro
      - ./metadata:/metadata:ro
    environment:
      - VC_CONFIG_YAML=config.yaml
    depends_on:
      - mongo

  mongo:
    image: mongo:7
    restart: always
    volumes:
      - mongo-data:/data/db
    ports:
      - "27017:27017"

volumes:
  mongo-data:

Issuer Configuration

Create config.yaml:

issuer:
  api_server:
    addr: :8080
    tls:
      enabled: false  # Use reverse proxy for TLS in production
  
  external_url: "https://issuer.example.com"
  
  # Signing key for credentials
  signing:
    key_path: "/pki/issuer_key.pem"
    algorithm: "ES256"
  
  # Authentication backend
  authentication:
    type: oidc
    client_id: "issuer-client"
    client_secret: "${OIDC_CLIENT_SECRET}"
    issuer_url: "https://your-idp.example.com"
    scopes:
      - openid
      - profile

  # Trust configuration
  trust:
    authzen_endpoint: "http://go-trust:8081"  # Optional: go-trust service

common:
  mongo:
    uri: mongodb://mongo:27017
  production: true

Start the Service

# Start all services
docker compose up -d

# Check logs
docker compose logs -f issuer

# Verify health
curl http://localhost:8080/health

Binary Deployment

For non-Docker environments:

# Clone the repository
git clone https://github.com/dc4eu/vc.git
cd vc

# Build the issuer
make build-issuer

# Run
export VC_CONFIG_YAML=config.yaml
./bin/vc_issuer

Kubernetes Deployment

For production Kubernetes deployments:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: issuer
spec:
  replicas: 2
  selector:
    matchLabels:
      app: issuer
  template:
    metadata:
      labels:
        app: issuer
    spec:
      containers:
        - name: issuer
          image: ghcr.io/sirosfoundation/vc-issuer:latest  # or vc-issuer-full
          ports:
            - containerPort: 8080
          env:
            - name: VC_CONFIG_YAML
              value: /config/config.yaml
          volumeMounts:
            - name: config
              mountPath: /config
            - name: pki
              mountPath: /pki
          livenessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 10
          readinessProbe:
            httpGet:
              path: /health
              port: 8080
      volumes:
        - name: config
          configMap:
            name: issuer-config
        - name: pki
          secret:
            secretName: issuer-pki

Next Steps

• Configure Trust Services
• Set up Credential Verification
• Keycloak Verifier Integration