VC

A Go-based microservices backend for issuing and verifying digital credentials, originally created within the DC4EU (Digital Credentials for Europe) project.

The platform implements the OpenID4VCI and OpenID4VP protocols to issue and verify credentials in SD-JWT VC, W3C Verifiable Credentials 2.0, and ISO/IEC 18013-5 mdoc formats.

Quick Start

# 1. Generate development PKI certificates
make pki

# 2. Start all services (MongoDB + microservices)
make start

# 3. Verify everything is running
docker compose ps

The services will be available on the internal Docker network (172.16.50.0/24):

Service	Address
API Gateway	`http://apigw.vc.docker:8080`
UI	`http://ui.vc.docker:8080`
Issuer	`http://issuer.vc.docker:8080`
Verifier	`http://verifier.vc.docker:8080`
Registry	`http://registry.vc.docker:8080`
Mock AS	`http://mockas.vc.docker:8080`
MongoDB	`mongodb://mongo.vc.docker:27017`

To access a service from the host, use its container IP directly (e.g. http://172.16.50.2:8080 for apigw) or publish ports in docker-compose.yaml.

To stop everything: make stop

Minimal configuration

A minimal config file is provided at config_minimal.yaml for getting started with sensible defaults. To use it, set the environment variable before starting:

export VC_CONFIG_YAML=config_minimal.yaml

The full configuration with all options is in config.yaml. See docs/CONFIGURATION.md for details.

Prerequisites

Docker and Docker Compose
GNU Make

Services

Service	Description
apigw	API Gateway with optional SAML and OIDC RP support for relying party integration
issuer	Issues verifiable credentials via OpenID4VCI with VCTM schema validation
verifier	Verifies credential presentations via OpenID4VP, DCQL, and the W3C Digital Credentials API
registry	Credential registry and status list management
mockas	Mock Authorization Server for development and testing
ui	Web UI for credential issuance and presentation

Architecture

Credential Verification

A relying party (e.g. Keycloak) connects to the Verifier as a standard OIDC Provider. The Verifier translates the OIDC request into an OpenID4VP presentation request toward the wallet.

  ┌────────────┐         OIDC            ┌──────────────────────────┐
  │  Relying   │ ──────────────────────► │        VERIFIER          │
  │  Party     │  authorize, token,      │                          │
  │ (Keycloak) │  userinfo              │  OIDC Provider (OP)      │
  └────────────┘ ◄────────────────────── │  OpenID4VP Verifier      │
                                         └────────────┬─────────────┘
                                                      │
                                                      │ OpenID4VP
                                                      │ (present credential)
                                                      ▼
                                         ┌──────────────────────────┐
                                         │         WALLET           │
                                         │       (phone app)        │
                                         └──────────────────────────┘

Credential Issuance — Two Paths

PID issuance and non-PID issuance follow different authentication paths determined by auth_method in the credential configuration.

                           Wallet requests credential
                           via OpenID4VCI (PAR → Authorize)
                                       │
                          ┌────────────┴────────────┐
                          │                         │
                   auth_method: basic        auth_method: pid_auth
                          │                         │
               ┌──────────▼──────────┐   ┌──────────▼───────────────┐
               │  PATH 1: PID        │   │  PATH 2: OTHER           │
               │  (pid_1_5, pid_1_8) │   │  (ehic, diploma, pda1,   │
               │                     │   │   elm, eduid, micro...)   │
               │  User authenticates │   │                           │
               │  via external IdP:  │   │  Wallet presents existing │
               │                     │   │  PID credential back to   │
               │  • SAML IdP         │   │  APIGW via OpenID4VP      │
               │  • OIDC Provider    │   │                           │
               │  • Username/Pass    │   │  APIGW verifies PID,      │
               │    (dev/test)       │   │  extracts identity, looks  │
               │                     │   │  up document in datastore  │
               └──────────┬──────────┘   └──────────┬────────────────┘
                          │                         │
                          └────────────┬────────────┘
                                       │
                                       ▼
                          ┌──────────────────────────┐
                          │          APIGW            │
                          │   OAuth AS (OpenID4VCI)   │
                          │   Consent → Token →       │
                          │   Credential              │
                          └─────┬──────────────┬──────┘
                                │ gRPC         │
                                ▼              ▼
                     ┌──────────────┐  ┌──────────────┐
                     │   ISSUER     │  │  REGISTRY    │
                     │              │  │              │
                     │  Signs cred  │  │  Token       │
                     │  (SD-JWT VC, │  │  Status List │
                     │  mdoc,       │  │  (revocation)│
                     │  W3C VC)     │  │              │
                     └──────────────┘  └──────────────┘

Full System Overview

                                                                ┌────────────┐
                                                                │ SAML IdP / │
  ┌────────────┐                                                │ OIDC IdP   │
  │  Relying   │                                                │ (external) │
  │  Party     │                                                └──────┬─────┘
  │ (Keycloak) │                                                       │
  └─────┬──────┘                                   SAML / OIDC RP      │
        │ OIDC                                     (PID issuance auth) │
        ▼                                                              │
  ┌──────────────────┐        OpenID4VP         ┌──────────────┐       │
  │    VERIFIER      │ ◄─────────────────────── │              │       │
  │                  │   (present credential)   │              │       │
  │  OIDC Provider   │ ───────────────────────► │    WALLET    │       │
  │  OpenID4VP       │   (request presentation) │  (phone app) │       │
  └──────────────────┘                          │              │       │
                                                │              │       │
                 OpenID4VCI                      │              │       │
                 (receive new credential)        │              │       │
          ┌──────────────────────────────────────┤              │       │
          │      OpenID4VP                       │              │       │
          │      (present PID for non-PID issue) │              │       │
          │  ┌───────────────────────────────────┤              │       │
          │  │                                   └──────────────┘       │
          ▼  ▼                                                         │
  ┌────────────────────────────────────────────────────────────────┐    │
  │                           APIGW                                │    │
  │                                                                │◄───┘
  │  OAuth AS (OpenID4VCI)   — issue credentials to wallet         │
  │  OpenID4VP Verifier      — verify PID before non-PID issuance  │
  │  SAML SP (optional)      — authenticate for PID issuance       │
  │  OIDC RP (optional)      — authenticate for PID issuance       │
  └──────────┬──────────────────────────────┬──────────────────────┘
             │ gRPC                         │
             ▼                              ▼
  ┌──────────────────┐           ┌──────────────────┐
  │     ISSUER       │           │    REGISTRY      │
  │  Signs creds     │           │  Token Status    │
  │  (SD-JWT VC,     │           │  List            │
  │   mdoc, W3C VC)  │           │  (revocation)    │
  └──────────────────┘           └──────────────────┘

  ┌──────────────────┐           ┌──────────────────┐
  │       UI         │           │    MOCK AS       │
  │  Admin web       │──────────►│  Test users &    │
  │  interface       │           │  bootstrapping   │
  └──────────────────┘           └──────────────────┘

Component	Server Role	Client Role
Verifier	OIDC Provider (OP) toward relying parties	OpenID4VP verifier toward wallets
APIGW	OAuth AS (OpenID4VCI) toward wallets	SAML SP + OIDC RP toward external IdPs (PID issuance)
	OpenID4VP verifier (non-PID issuance auth)
Issuer	gRPC credential signing service	—
Registry	Token Status List (revocation)	—

Capabilities

Issue verifiable credentials via OpenID4VCI 1.0
Verify credential presentations via OpenID4VP 1.0 with direct_post response mode
SD-JWT VC (draft-ietf-oauth-sd-jwt-vc-13), W3C Verifiable Credentials 2.0, and ISO/IEC 18013-5 mdoc credential formats
Browser-native credential presentation via the W3C Digital Credentials API (navigator.credentials.get())
DCQL (Digital Credentials Query Language) for flexible presentation requests
Credential revocation via Token Status List (draft-ietf-oauth-status-list) with JWT (RFC 7519) and CWT (RFC 8392) formats
VCTM schema validation before credential issuance (draft-ietf-oauth-sd-jwt-vc-13 §6)
PKCS#11 / HSM support for hardware-backed key protection
SAML 2.0, OpenID Connect Core 1.0, and OAuth 2.0 Relying Party authentication with PKCE (RFC 7636), DPoP (RFC 9449), and JAR (RFC 9101)
gRPC inter-service communication
Kafka-based message brokering
MongoDB storage backend
OpenTelemetry distributed tracing
Static Linux/amd64 binaries for containerized deployment

Docker release version

latest tracks the latest tag available and is built from branch main.

Branches

main is the stable development branch.

How to build

Build targets

Service	Command	Description
All	`make build`	Build all services
apigw	`make build-apigw`	API Gateway
issuer	`make build-issuer`	Credential Issuer
verifier	`make build-verifier`	Credential Verifier
registry	`make build-registry`	Registry
mockas	`make build-mockas`	Mock Authentication Service
ui	`make build-ui`	Web UI
vc20-test-server	`make build-vc20-test-server`	W3C VC 2.0 test server

All standard builds produce static binaries (CGO_ENABLED=0) for linux/amd64. Output goes to ./bin/.

Build tags

Optional features are enabled via Go build tags. The following tags are available:

Tag	Description	Affected service(s)	CGO	Make target
`saml`	SAML IdP support	apigw	static	`make build-apigw-saml`
`oidcrp`	OpenID Connect Relying Party	apigw	static	`make build-apigw-oidcrp`
`saml,oidcrp`	All optional apigw features	apigw	static	`make build-apigw-all`
`pkcs11`	PKCS#11 HSM signing	issuer	dynamic	`make build-issuer-hsm`
`vc20`	W3C Verifiable Credentials 2.0	vc20-test-server	static	`make build-vc20-test-server`

Note: The pkcs11 tag requires CGO (CGO_ENABLED=1) and produces a dynamically linked binary.

Docker

For convenience all services can be built inside a Docker container.

Command	Description
`make docker-build`	Build all Docker images
`make docker-build-<service>`	Build a specific service image
`make docker-build-apigw-saml`	apigw image with SAML support
`make docker-build-apigw-oidcrp`	apigw image with OIDC RP support
`make docker-build-apigw-all`	apigw image with all features
`make docker-build-issuer-hsm`	issuer image with PKCS#11 HSM support
`make docker-push`	Push all standard images to registry
`make docker-push-apigw-saml`	Push apigw SAML image
`make docker-push-apigw-oidcrp`	Push apigw OIDC RP image
`make docker-push-apigw-all`	Push apigw all-features image
`make docker-push-issuer-hsm`	Push issuer HSM image
`make docker-tag`	Tag all images

Set the image version with VERSION=x.x.x (default: latest).

Start, Stop & Restart

Command	Description
`make start`	Start all services via docker-compose
`make stop`	Stop all services
`make restart`	Restart all services
`make pki`	Generate PKI infrastructure
`make pki-clean`	Remove PKI material

Testing

Command	Description
`make test`	Run all service tests
`make test-saml`	Test with `saml` build tag
`make test-oidcrp`	Test with `oidcrp` build tag
`make test-vc20`	Test with `vc20` build tag
`make test-pkcs11`	Test with `pkcs11` build tag (requires `make test-env`)
`make test-all-tags`	Test with all build tags
`make test-env`	Install test dependencies (softhsm2, opensc)

Development Tools

Command	Description
`make install-tools`	Install protoc, swag, and Go gRPC plugins
`make vscode`	Full VS Code dev environment setup
`make proto`	Regenerate protobuf files
`make swagger`	Regenerate Swagger documentation
`make gosec`	Run security scanner
`make staticcheck`	Run static analysis
`make vulncheck`	Run vulnerability checker

Swagger

Endpoint

GET http://<apigw-url>/swagger/doc.json

or with web browser: http://<apigw-url>/swagger/index.html

Name		Name	Last commit message	Last commit date
Latest commit History 1,641 Commits
.devcontainer		.devcontainer
.github		.github
.vscode		.vscode
bootstrapping		bootstrapping
cmd		cmd
credentials		credentials
developer_tools/scripts		developer_tools/scripts
dockerfiles		dockerfiles
docs		docs
images		images
internal		internal
metadata		metadata
pkg		pkg
presentation_requests		presentation_requests
proto		proto
scripts		scripts
standards		standards
test/didcomm_interop		test/didcomm_interop
testdata		testdata
vendor		vendor
.dockerignore		.dockerignore
.gitignore		.gitignore
.jenkins.yaml		.jenkins.yaml
CHANGELOG.md		CHANGELOG.md
LICENSE.md		LICENSE.md
Makefile		Makefile
README.md		README.md
ROADMAP.md		ROADMAP.md
VERSION		VERSION
config.saml.example.yaml		config.saml.example.yaml
config.yaml		config.yaml
config_minimal.yaml		config_minimal.yaml
didcomm_coverage.out		didcomm_coverage.out
docker-compose.yaml		docker-compose.yaml
go.mod		go.mod
go.sum		go.sum
secrets.example.yaml		secrets.example.yaml
sonar-project.properties		sonar-project.properties
users_paris.csv		users_paris.csv
users_paris.xlsx		users_paris.xlsx

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

VC

Quick Start

Minimal configuration

Prerequisites

Services

Architecture

Credential Verification

Credential Issuance — Two Paths

Full System Overview

Capabilities

Docker release version

Branches

How to build

Build targets

Build tags

Docker

Start, Stop & Restart

Testing

Development Tools

Swagger

Endpoint

About

Uh oh!

Releases 7

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

VC

Quick Start

Minimal configuration

Prerequisites

Services

Architecture

Credential Verification

Credential Issuance — Two Paths

Full System Overview

Capabilities

Docker release version

Branches

How to build

Build targets

Build tags

Docker

Start, Stop & Restart

Testing

Development Tools

Swagger

Endpoint

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 7

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages