Skip to content

Overview

Purpose and scope

This page provides a high-level overview of TrustDeck: an open-source identity management and pseudonymization platform designed for research and data processing environments. It summarizes the system’s purpose, core capabilities, major components, technology stack, and deployment model.

What is TrustDeck?

TrustDeck is a Spring Boot service that provides pseudonymization and identity/entity management features with integrated security and auditability. It is designed for:

  • Trusted third party / admin workflows (interactive use)
  • Automated processing pipelines (programmatic REST usage)

TrustDeck exposes a REST API, authenticates requests using OIDC/JWT (Keycloak), and persists data in PostgreSQL.

Key capabilities

Capability Description
Pseudonymization Generate pseudonyms from identifiers using configurable algorithms (e.g., cryptographic hashing, random generation, sequential schemes) with domain-specific settings.
Domain hierarchy Semantically cluster pseudonyms and organize pseudonymization rules in a tree of domains with inheritance of configuration properties.
Entity management Register and manage entities using flexible type definitions (schema-driven).
Access control OAuth2/OIDC authentication with Keycloak and role-based authorization; permissions can be expressed per domain/project-endpoint-user context.
Auditing All API requests are automatically logged with who did what, when, and from where, enabling reliable traceability and data-state reconstruction.
Integration REST-first design for integration into data pipelines and other services.

High-level architecture

TrustDeck follows a layered design:

  • REST API layer
    Exposes endpoints for domain management, pseudonym operations, and entity/project operations.

  • Security layer
    Validates JWT tokens and enforces authorization rules for operations (role-based and context-aware).

  • Business services
    Implements core rules (domain configuration, pseudonym generation, entity/project handling).

  • Pseudonymization engine
    Selects and executes the configured pseudonymization algorithm based on domain settings.

  • Persistence and caching
    Uses PostgreSQL for durable storage and an in-memory cache for performance-sensitive lookups (where configured).

Core modules: ACE and KING

TrustDeck contains two main functional areas that run within the same application:

ACE (pseudonymization / confidentiality engine)

The Advanced Confidentiality Engine (ACE) focuses on pseudonymization driven by domain configuration.

Typical responsibilities:

  • Create and maintain domains (with inheritance)
  • Generate pseudonyms for identifiers within a domain
  • Support bulk/batch pseudonym operations (where exposed)
  • Support cross-domain linking (where configured/available)

KING (entity and project management)

The Key Index of Names and General Identification Numbers (KING) component focuses on projects and entities, enabling structured registration and lifecycle management.

Typical responsibilities:

  • Manage projects as containers for entities
  • Define entity types (schema-driven)
  • Register entity instances and manage their lifecycle

Technology stack (short)

  • Java
  • Spring Boot
  • PostgreSQL
  • jOOQ
  • Keycloak

Deployment model

TrustDeck is typically deployed as three services:

  • trustdeck-backend (Spring Boot application)
  • trustdeck-postgresql (database)
  • trustdeck-keycloak (OIDC provider)

Additionally, a frontend can be added as a fourth service.

Two common modes exist:

Dev mode

  • Postgres + Keycloak run via Docker Compose
  • Backend runs locally via Maven

Prod-like mode

  • Postgres + Keycloak + backend all run via Docker Compose
  • Backend runs as a container built from the packaged JAR

See: Getting Started

Security model overview (OIDC/JWT)

TrustDeck uses the OAuth2 Resource Server pattern:

  • Clients obtain an access token from Keycloak
  • Clients call TrustDeck with: Authorization: Bearer <ACCESS_TOKEN>
  • TrustDeck validates the token (issuer + signature keys) and enforces permissions

See: Authentication

Where to go next

  1. Start and run the service: Getting Started
  2. Obtain a token and call protected endpoints: Authentication
  3. Explore endpoints and models: Swagger UI
  4. Explore Java APIs and internal types: Javadoc