How eclipse-tractusx/tractusx-identityhub works
1. Repository purpose
- This repo packages and deploys the Tractus-X IdentityHub stack as two Java services: IdentityHub and IssuerService.
- Both are DCP-oriented identity/credential services built on top of the Eclipse EDC extension model, with production and memory-only deployment variants.
2. Top-level system split
- The architecture is centered on two independent backend runtimes:
- runtimes/identityhub and runtimes/identityhub-memory
- runtimes/issuerservice and runtimes/issuerservice-memory
- These are the executable service compositions; the rest of the repo mainly provides shared extensions, database migrations, packaging, deployment, and a UI.
3. IdentityHub runtime responsibilities
- IdentityHub acts as the holder-side wallet/wallet-like service.
- It manages participant contexts, DIDs, key pairs, verifiable credentials, presentation queries, and self-issued token-related flows.
- It is the service that a dataspace connector talks to during credential presentation flows.
4. IssuerService runtime responsibilities
- IssuerService is the issuer-side service for creating credential definitions, attestations, holders, issuance processes, and credential lifecycle actions such as revocation/suspension/resumption.
- It is the counterpart in the credential issuance flow and exposes admin and issuance APIs used by IdentityHub and operators.
5. Shared extension layer
- The functional logic is mostly implemented as EDC service extensions under extensions/.
- Notable extension groups include:
- extensions/store/sql/migrations for PostgreSQL schema/versioning
- extensions/seed/super-user and extensions/identityhub/initial-participant for bootstrapping
- extensions/monitor/colored-jdk-monitor for runtime logging/formatting
- This indicates a modular, plugin-based backend rather than a single monolithic application.
6. Persistence boundary
- The production variants depend on PostgreSQL for durable state.
- The SQL migrations are organized by domain table set: participant context, key pairs, DID resources, credentials, credential definitions, issuance processes, holders, attestation definitions, STS client, and JTI validation.
- The memory variants replace these with in-memory stores for demo/testing and do not require the database.
7. Secret management boundary
- The README and deployment structure show HashiCorp Vault as the secret store for production deployments.
- Runtime configs and the API documentation imply that private keys and other sensitive material can be sourced from Vault rather than being generated/stored locally.
- This is a clear architectural boundary between durable business data in PostgreSQL and secrets in Vault.
8. API surface and protocol flows
- The repo documents several API families in docs/api/openAPI.yaml and Bruno collections:
- Identity API for participant contexts, DIDs, key pairs, credentials
- Issuance API for credential requests and issuer metadata
- Issuer Admin API for credential definitions, holders, issuance processes, revocation
- DID API, STS API, and StatusList API
- The key protocol flows are:
- Issuance flow: IdentityHub requests credentials from IssuerService via DCP
- Presentation flow: an EDC connector requests verifiable presentations from IdentityHub
9. Frontend/UI subsystem
- The ui/ directory is a separate React + TypeScript application with its own build, tests, and Nginx-based containerization.
- It provides operator/user screens for participants, credentials, DIDs, key pairs, and search.
- The UI talks to the backend services over HTTP and is configuration-driven at runtime via environment injection.
10. Deployment packaging
- Deployment is done primarily through Helm charts:
- charts/tractusx-identityhub
- charts/tractusx-identityhub-memory
- charts/tractusx-issuerservice
- charts/tractusx-issuerservice-memory
- Charts include deployment, service, ingress, HPA, logging config, PVCs, and test hooks, which means the repo is meant to produce deployable Kubernetes workloads rather than only libraries.
11. Local development and Docker composition
- deployment/docker/ contains Docker Compose-based local setups and component-specific configuration files.
- This includes container wiring for the services plus PostgreSQL initialization scripts, which makes local execution a first-class supported path alongside Kubernetes.
12. Operational and release tooling
- The .github/workflows area is extensive and covers linting, scanning, deployment tests, Helm validation, snapshot publishing, and release automation.
- This repo is therefore structured not only as source code but as a releaseable product with CI/CD, security scanning, and chart/image publishing.
13. Testing and verification
- End-to-end and API verification assets are stored under docs/api/bruno, tests/deployment, and scripts/verify-credential.py.
- These artifacts indicate the system is verified through a mix of backend tests, deployment checks, and API flow collections rather than only unit tests.
14. Main architectural diagram boundaries
- If you draw the architecture, the main boxes should be:
- IdentityHub runtime
- IssuerService runtime
- PostgreSQL
- Vault
- EDC connector / external dataspace participant
- Operator UI
- The critical arrows are:
- UI → backend APIs
- IdentityHub ↔ IssuerService for DCP issuance
- Connector ↔ IdentityHub for presentation
- Both runtimes → PostgreSQL, and production variants → Vault
- Deployment/CI → Helm charts, container images, and Kubernetes
Main entry points: identityhub IdentityHub · issuerservice IssuerService · ui Operator UI · workflows CI/CD
Components 17
Backend runtimes
Executable IdentityHub and IssuerService compositions, including memory variants.
- IdentityHub · Production holder-side runtime for participant contexts, DIDs, keys, credentials, and presentation flows.
runtimes/identityhub - IdentityHub memory · In-memory IdentityHub variant for demo and testing.
runtimes/identityhub-memory - IssuerService · Production issuer-side runtime for definitions, holders, issuance, and lifecycle actions.
runtimes/issuerservice - Issuer memory · In-memory IssuerService variant for demo and testing.
runtimes/issuerservice-memory
Shared extensions
Eclipse EDC service extensions for persistence, bootstrapping, and monitoring.
- Identity extensions · IdentityHub-specific extensions such as initial participant bootstrapping.
extensions/identityhub/initial-participant - Super-user seed · Bootstraps privileged or default identities for initial setup.
extensions/seed/super-user - Colored monitor · JDK logging formatter and runtime observability helper.
extensions/monitor/colored-jdk-monitor - SQL migrations · Flyway-backed PostgreSQL schema and versioning for participants, keys, DIDs, credentials, issuance, holders, attestations, STS, and JTI validation.
extensions/store/sql/migrations
Packaging and deploy
Helm charts, Docker composition, and release tooling.
- Helm charts · Kubernetes charts for production and memory variants of both services.
charts - Docker compose · Local container composition and PostgreSQL initialization scripts.
deployment/docker - CI/CD · GitHub Actions workflows for linting, scanning, testing, publishing, and release automation.
.github/workflows
Operator UI
React frontend for browsing and managing participants, credentials, DIDs, and keys.
- Operator UI · React + TypeScript frontend for managing participants, credentials, DIDs, key pairs, and search.
ui
API and verification
OpenAPI, Bruno collections, walkthroughs, and deployment verification assets.
- API docs · OpenAPI definitions and Bruno collections documenting Identity, Issuance, Admin, DID, STS, and StatusList APIs.
docs/api - E2E checks · Deployment tests, walkthroughs, and credential verification scripts.
tests/deployment
Other components
- PostgreSQL · Primary durable state for production runtime data.
- Vault · Secret backend for private keys and other sensitive runtime material.
- EDC connector · External dataspace participant that requests presentations and participates in DCP flows.
Connections 32
- IdentityHub → SQL migrations: uses schema · Production IdentityHub persists business state through the shared PostgreSQL migrations layer.
- IssuerService → SQL migrations: uses schema · Production IssuerService persists business state through the shared PostgreSQL migrations layer.
- SQL migrations → PostgreSQL: provisions · Migrations define and evolve the PostgreSQL schema used by both runtimes.
- IdentityHub → Vault: reads secrets · IdentityHub can source private keys and sensitive material from Vault in production.
- IssuerService → Vault: reads secrets · IssuerService can source private keys and sensitive material from Vault in production.
- IdentityHub → EDC connector: presentation · External connectors request verifiable presentations from IdentityHub.
- EDC connector → IdentityHub: DCP request · Presentation flow enters IdentityHub from an external dataspace participant.
- IdentityHub → IssuerService: issuance · IdentityHub requests credential issuance from IssuerService via DCP.
- IssuerService → IdentityHub: offers/metadata · IssuerService exposes issuance APIs and credential offer flows consumed by IdentityHub.
- Operator UI → IdentityHub: Identity APIs · UI manages participants, DIDs, key pairs, and credentials through IdentityHub HTTP APIs.
- Operator UI → IssuerService: Issuer APIs · UI manages definitions, holders, issuance processes, and lifecycle actions through IssuerService HTTP APIs.
- IdentityHub memory → IdentityHub: same service · Memory variant mirrors the IdentityHub runtime shape without durable persistence.
- Issuer memory → IssuerService: same service · Memory variant mirrors the IssuerService runtime shape without durable persistence.
- IdentityHub memory → Operator UI: dev target · UI can be pointed at the memory runtime for local development.
- Issuer memory → Operator UI: dev target · UI can be pointed at the memory runtime for local development.
- IdentityHub → Identity extensions: loads extensions · IdentityHub runtime is assembled from modular EDC extensions.
- IdentityHub → Super-user seed: bootstrap · Runtime can be seeded with privileged participant/user state.
- IssuerService → Super-user seed: bootstrap · IssuerService can be seeded with initial operator or super-user state.
- IdentityHub → Colored monitor: logging · Runtime uses the shared JDK monitor formatting extension.
- IssuerService → Colored monitor: logging · Runtime uses the shared JDK monitor formatting extension.
- Helm charts → IdentityHub: deploys · Charts package the production and memory IdentityHub workloads.
- Helm charts → IssuerService: deploys · Charts package the production and memory IssuerService workloads.
- Docker compose → IdentityHub memory: runs locally · Docker composition supports local IdentityHub execution.
- Docker compose → Issuer memory: runs locally · Docker composition supports local IssuerService execution.
- CI/CD → Helm charts: validates/publishes · CI validates, packages, and publishes Helm charts.
- CI/CD → Operator UI: builds · CI builds, tests, and publishes the frontend artifact.
- CI/CD → IdentityHub: builds · CI builds and scans the backend runtime images and artifacts.
- CI/CD → IssuerService: builds · CI builds and scans the backend runtime images and artifacts.
- API docs → IdentityHub: documents · API specs describe the backend service surfaces and protocol flows.
- E2E checks → IdentityHub: verifies · Deployment and API checks exercise IdentityHub flows.
- E2E checks → IssuerService: verifies · Deployment and API checks exercise IssuerService flows.
- E2E checks → Operator UI: smoke tests · Verification assets include end-to-end scenarios involving the UI and backend.