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. See OIDC Provider Integration for detailed configuration:

# Example OIDC configuration
apigw:
  oidcrp:
    enabled: true
    client_id: "your-client-id"
    client_secret: "your-client-secret"
    provider_metadata_url: "https://your-idp.example.com/.well-known/openid-configuration"
    scopes:
      - openid
      - profile
      - email
    credential_config_id: "urn:eudi:pid:arf-1.8:1"

2. SAML 2.0

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

# SAML is configured under apigw.saml
apigw:
  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:
      - credential_config_id: "urn:eudi:pid:arf-1.8:1"
        entity_ids:
          - "https://idp.example.org/idp/shibboleth"
        attributes:
          "urn:oid:2.5.4.42":
            claim: "given_name"
            required: true
          "urn:oid:2.5.4.4":
            claim: "family_name"
            required: true

3. Pre-Authorized Code

For server-to-server issuance (e.g., automated credential provisioning), use the pre-authorized code flow:

issuer:
  # Pre-authorized code flow is enabled by default
  # Credentials are issued via API with pre-generated codes
  enabled: true

Pre-authorized codes are generated via the API and can be used once to retrieve a credential without additional authentication.

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):

The auth_method field determines how the user is authenticated before the credential is issued:

auth_method	Description
basic	Internal lookup from the issuer's own datastore
pid_auth	User proves identity by presenting a Verifiable Credential (PID) via OpenID4VP
saml	User is redirected to a SAML IdP; claims from the assertion become credential attributes. Requires apigw.saml
oidc	User is redirected to an OIDC Provider; claims from the ID token become credential attributes. Requires apigw.oidcrp

credential_constructor:
  # Basic auth – identity from local datastore
  pid_1_5:
    vctm_file_path: "/metadata/vctm_pid_arf_1_5.json"
    auth_method: basic
    format: "dc+sd-jwt"
  
  # PID-based auth – wallet presents a Verifiable Credential
  ehic:
    vctm_file_path: "/metadata/vctm_ehic.json"
    auth_method: pid_auth
    format: "dc+sd-jwt"

  # SAML auth – redirect to SAML IdP, claims from assertion
  diploma:
    vctm_file_path: "/metadata/vctm_diploma.json"
    auth_method: saml
    format: "dc+sd-jwt"

  # OIDC auth – redirect to OIDC Provider, claims from ID token
  eduid:
    vctm_file_path: "/metadata/vctm_eduid.json"
    auth_method: oidc
    format: "dc+sd-jwt"

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
/deferred_credential	Deferred credential endpoint
/nonce	Nonce endpoint for proof binding
/notification	Credential notification 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 issuer image (includes SAML, OIDC, and all credential formats)
docker pull ghcr.io/sirosfoundation/vc-issuer:latest

Docker Compose

Create a docker-compose.yaml:

services:
  issuer:
    image: ghcr.io/sirosfoundation/vc-issuer:latest
    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 (optional: go-trust service)
  trust:
    pdp_url: "http://go-trust:6001"

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/SUNET/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
          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