eduID Wallet Matching Portal

Privacy-preserving identity matching portal that connects eduID wallet credentials with institutional identities via SURFconext federation. Both federated login (OIDC via SURFconext) and wallet-based login (OID4VP) produce identical OIDC tokens from the Security Token Service, so downstream systems are unaware of which authentication method was used.

Documentation

Full documentation is available at docs.sphereon.com/eduid-wallet-matching-portal.

Topics covered:

• System Architecture
• Authentication Flows (federated, wallet fast-path, wallet reconciliation)
• Identity Matching (HMAC-SHA256 hashing, identity link bindings)
• Reconciliation (selector rules, material profiles, IDV sessions)
• Encryption & Key Management (Keys A, B, C, AES-256-GCM, key rotation)
• REST APIs (OID4VP sessions, external API, STS endpoints)
• Database Schema (7 tables, SqlDelight)
• Deployment & Configuration
• Security & Privacy

Quick Start

cd deploy/docker
docker compose up

Portal: http://localhost:3000 | STS: http://localhost:8092 | Auth Bridge: http://localhost:8090

Architecture

Service	Port	Technology	Purpose
Portal (BFF)	3000	Next.js 15, NextAuth.js v5	Frontend, session management, BFF proxy
Service-STS	8092	Kotlin/JVM, Ktor, IDK	OAuth2/OIDC authorization server
Service-Auth-Bridge	8090	Kotlin/JVM, Ktor, IDK	OID4VP, identity matching, reconciliation
PostgreSQL	5432	PostgreSQL 15	Encrypted identity storage

Key Design Principles

• Zero plaintext identifiers in the database (HMAC-SHA256 hashed, AES-256-GCM encrypted)
• Domain-separated keys (Key A for holder hashing, Key B for institution hashing, Key C for encryption)
• GDPR-by-architecture (data minimization, crypto-shredding, right to erasure)
• Standard OIDC output (downstream systems don't know which auth method was used)
• Configuration-driven reconciliation (no code changes for new providers or rules)

License

Apache-2.0. Copyright Sphereon International B.V.