Skip to content

Commit 62ec170

Browse files
CDiezRodriguezCDiezRodriguez
authored
Merge pull request #222 from AYaoZhan/docs/issuerServiceDocs
docs: issuer service docs
2 parents 43af55d + ff07f92 commit 62ec170

File tree

6 files changed

+549
-55
lines changed

6 files changed

+549
-55
lines changed

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ For changes in other Tractus-X components, see the [Eclipse Tractus-X Changelog]
1010
## [Unreleased]
1111

1212
### Added
13+
- Add documentation about IssuerService by @AYaoZhan in [#222](https://github.com/eclipse-tractusx/tractusx-identityhub/pull/222)
14+
- Add documentation about IdentityHub, Developers and setup guide by @Alaitz1 in [#221](https://github.com/eclipse-tractusx/tractusx-identityhub/pull/221)
1315
- Add colored logger and logger persistence by @AYaoZhan in [#149](https://github.com/eclipse-tractusx/tractusx-identityhub/pull/149)
1416
- Add CHANGELOG.md file following TRG 1.03 standards by @CDiezRodriguez in [#151](https://github.com/eclipse-tractusx/tractusx-identityhub/pull/151)
1517
- Add installation and deployment documentation, enhance documentation structure, fix header and list formatting, add license headers and NOTICE files, set key signing alias default configuration by @AYaoZhan in [#147](https://github.com/eclipse-tractusx/tractusx-identityhub/pull/147)

‎README.md‎

Lines changed: 128 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,151 @@
11

22
# Tractus-X IdentityHub - a comprehensive DCP Wallet
33

4-
| [!WARNING] this project is under heavy development, expect bugs, problems and radical changes! |
5-
|------------------------------------------------------------------------------------------------|
4+
> [!WARNING]
5+
> This project is under heavy development, expect bugs, problems and radical changes!
66
7-
Welcome Contributor! Feel free to join our Identity Hub Weeklys if you want to contibute, or our office hours.
7+
Welcome Contributor! Feel free to join our Identity Hub Weeklys if you want to contribute, or our office hours.
88
You will find the links here: https://eclipse-tractusx.github.io/community/open-meetings/#Identity%20Hub%20Weekly
99

1010
Also feel free to contact us on our matrix chat: https://matrix.to/#/#tractusx-identity-hub:matrix.eclipse.org
1111

1212
We are working at the moment to bring the current implemented functionalities from the upstream identity hub, test and integrate them here to offer a deployment in Helm Charts and publish our images in docker hub, so you can use also this wallet.
1313

14+
## Table of Contents
15+
16+
1. [About The Project](#about-the-project)
17+
2. [System Architecture](#system-architecture)
18+
3. [Components](#components)
19+
- [IdentityHub](#identityhub)
20+
- [IssuerService](#issuerservice)
21+
4. [Getting Started](#getting-started)
22+
- [IdentityHub](#identityhub-1)
23+
- [IssuerService](#issuerservice-1)
24+
5. [Deployment](#deployment)
25+
- [Helm Chart](#helm-chart)
26+
- [Localhost](#localhost)
27+
6. [Documentation Hub](#documentation-hub)
28+
7. [License](#license)
29+
30+
---
31+
1432
## About The Project
1533

16-
The Tractus-X IdentityHub is a specialized variant of
17-
the [IdentityHub project](https://github.com/eclipse-edc/IdentityHub/).
18-
It contains a DCP CredentialService implementation and a SecureTokenService, preconfigured for use in Tractus-X.
34+
The Tractus-X IdentityHub is a specialized, production-ready distribution of the upstream [Eclipse EDC IdentityHub project](https://github.com/eclipse-edc/IdentityHub/), tailored specifically for the Tractus-X ecosystem.
35+
36+
This project provides deployable versions of two core components:
37+
38+
- **IdentityHub**: A comprehensive DCP (Decentralized Claims Protocol) wallet that manages verifiable credentials and decentralized identities
39+
- **IssuerService**: A service for issuing verifiable credentials to participants in the dataspace
40+
41+
Both components implement the Decentralized Claims Protocol (DCP) specification, ensuring interoperability and standardized credential exchange within the Tractus-X ecosystem. The project offers ready-to-deploy Helm charts with PostgreSQL and HashiCorp Vault integration for production environments, as well as memory-based variants for development and testing.
42+
43+
## System Architecture
44+
45+
The Tractus-X IdentityHub consists of two main components that work together to provide complete credential lifecycle management:
46+
47+
```mermaid
48+
flowchart LR
49+
subgraph Issuer["Issuer"]
50+
direction TB
51+
IS[tractusx-issuerservice<br/>Issuer]
52+
IS_DB[(PostgreSQL<br/>Database)]
53+
IS_VAULT[HashiCorp Vault<br/>Secret Storage]
54+
55+
IS -->|Store Data| IS_DB
56+
IS -->|Store Secrets| IS_VAULT
57+
end
58+
subgraph Holder["Holder"]
59+
direction TB
60+
IH[tractusx-identityhub<br/>Holder]
61+
IH_DB[(PostgreSQL<br/>Database)]
62+
IH_VAULT[HashiCorp Vault<br/>Secret Storage]
63+
64+
IH -->|Store Data| IH_DB
65+
IH -->|Store Secrets| IH_VAULT
66+
end
67+
subgraph DataSpace["Data Space Participant"]
68+
direction TB
69+
CONN[Tractus-X EDC<br/>Connector]
70+
end
71+
%% Issuance Flow
72+
IH <-->|DCP Protocol<br/>Credential Request & Delivery| IS
73+
%% Presentation Flow
74+
CONN <-->|Presentation Query<br/>/presentation/query| IH
75+
style IH fill:#e1f5ff
76+
style IS fill:#fff4e1
77+
style CONN fill:#d4edda
78+
style IH_DB fill:#336791
79+
style IS_DB fill:#336791
80+
style IH_VAULT fill:#000000,color:#ffffff
81+
style IS_VAULT fill:#000000,color:#ffffff
82+
```
83+
84+
**Key Interactions:**
85+
86+
1. **Credential Issuance (IssuerService ↔ IdentityHub)**:
87+
- Holder's IdentityHub requests credentials from IssuerService via DCP Issuance Flow
88+
- IssuerService evaluates attestations and rules
89+
- Credentials are signed and delivered to holder's IdentityHub for storage
90+
91+
2. **Credential Presentation (Connector ↔ IdentityHub)**:
92+
- Tractus-X EDC Connector requests credential presentation via `/presentation/query` endpoint
93+
- IdentityHub creates verifiable presentations from stored credentials
94+
- Presentations are sent to connector for validation during dataspace interactions
95+
96+
## Components
97+
98+
### IdentityHub
99+
100+
The IdentityHub serves as a comprehensive identity wallet and credential management system. Its primary purposes are:
101+
102+
- **Credential Storage**: Securely store and manage verifiable credentials received from issuers
103+
- **Identity Management**: Manage decentralized identities (DIDs) and their associated key pairs
104+
- **Credential Presentation**: Present credentials to verifiers during DCP flows
105+
- **Self-Issued ID Tokens**: Create and manage self-issued ID Tokens
106+
107+
### IssuerService
108+
109+
The IssuerService is responsible for the issuance of verifiable credentials to dataspace participants. Its primary purposes are:
110+
111+
- **Credential Issuance**: Issue verifiable credentials to participants based on predefined credential definitions
112+
- **Attestation Management**: Define and manage attestation requirements for credential issuance
113+
- **Credential Lifecycle**: Handle the complete lifecycle of issued credentials, including revocation
114+
- **Standards Compliance**: Ensure all issued credentials comply with DCP specifications and dataspace policies
115+
116+
## Getting Started
117+
118+
This project provides Helm charts for deploying both IdentityHub and IssuerService components. Each component is available in two variants:
119+
120+
### IdentityHub
121+
122+
1. [`tractusx-identityhub`](./charts/tractusx-identityhub/README.md): The recommended, production-ready version that uses PostgreSQL as database and HashiCorp Vault as secret storage.
123+
2. [`tractusx-identityhub-memory`](./charts/tractusx-identityhub-memory/README.md): An ephemeral, memory-only version that stores data and secrets in memory. **Please only use this for demo or testing purposes!**
124+
125+
### IssuerService
126+
127+
1. [`tractusx-issuerservice`](./charts/tractusx-issuerservice/README.md): The recommended, production-ready version that uses PostgreSQL as database and HashiCorp Vault as secret storage.
128+
2. [`tractusx-issuerservice-memory`](./charts/tractusx-issuerservice-memory/README.md): An ephemeral, memory-only version that stores data and secrets in memory. **Please only use this for demo or testing purposes!**
129+
130+
## Deployment
19131

20-
## Getting started
132+
### Helm Chart
21133

22-
As all Tractus-X applications, IdentityHub is distributed as helm chart, of which there are two variants:
134+
To deploy using Helm charts, please refer to the documentation for each variant listed in the [Getting Started](#getting-started) section above. Each chart provides detailed configuration options, prerequisites, and deployment instructions.
23135

24-
1. `tractusx-identityhub`: the recommended, production-ready version that uses PostgreSQL as database and Hashicorp
25-
Vault as secret storage.
26-
2. `tractusx-identityhub-memory`: an ephemeral, memory-only version that stores data and secrets in memory. **Please
27-
only use this for demo or testing purposes!**
136+
> [!NOTE]
137+
> This project is still under heavy development. For the most up-to-date deployment experience, it is recommended to follow the [Localhost](#localhost) deployment instructions below.
28138
29-
Please refer to the respective [documentation](./charts/tractusx-identityhub/README.md) for more information on how to
30-
run it.
139+
### Localhost
31140

32-
As all Tractus-X applications, IssuerService is distributed as helm chart, of which there are two variants:
141+
For detailed deployment instructions in a localhost environment, please refer to the [Installation Guide](./INSTALL.md).
33142

34-
1. `tractusx-issuerservice`: the recommended, production-ready version that uses PostgreSQL as database and Hashicorp
35-
Vault as secret storage.
36-
2. `tractusx-issuerservice-memory`: an ephemeral, memory-only version that stores data and secrets in memory. **Please
37-
only use this for demo or testing purposes!**
143+
> [!NOTE]
144+
> While running the applications natively as Java processes or directly as Docker images is possible, it is highly recommended to deploy using the official Helm charts with PostgreSQL and HashiCorp Vault. The Helm chart deployment ensures proper configuration, security, and scalability.
38145
39-
Please refer to the respective [documentation](./charts/tractusx-issuerservice/README.md) for more information on how to
40-
run it.
146+
## Documentation Hub
41147

42-
> Note that running the application natively as Java process, or directly as Docker image is possible, but is not
43-
> supported by the Tractus-X IdentityHub team. Please use the official Helm chart.
148+
For developer resources, as well as best practices for development and testing, can be found [in this file](./docs/README.md).
44149

45150
## License
46151

‎docs/README.md‎

Lines changed: 47 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,59 @@
1-
# Documentation Overview
1+
# Developer Documentation Hub
22

33
This directory contains the complete documentation for the Identity Hub and Issuer Service components. The documentation is organized by target audience and functional area.
44

5-
## Directory Structure
6-
7-
* **[admin/](./admin/)**: Contains administrative guides, including the [Migration Guide](./admin/migration-guide.md).
8-
* **[api/](./api/README.md)**: API specifications and testing collections.
9-
* `openAPI.yaml`: The OpenAPI 3.0 specification file.
10-
* `bruno/`: Bruno API collection.
11-
* `postman/`: Postman collections for Eclipse Tractus-X Identity Hub.
12-
* **[developers/](./developers/README.md)**: Deep-dive technical documentation for contributors and system integrators.
13-
* [components/](./developers/components/): Core component documentation.
14-
* [IdentityHub.md](./developers/components/IdentityHub.md): Identity Hub data models and lifecycles.
15-
* [setup/](./developers/setup/): Setup and configuration guides.
16-
* [Linux.md](./developers/setup/Linux.md): Linux setup and configuration guide.
17-
5+
## Required Knowledge
6+
7+
To effectively work with this project, familiarity with the following technologies is recommended:
8+
9+
- **Kubernetes**: Container orchestration platform for deploying and managing the applications
10+
- **Minikube**: Local Kubernetes environment for development and testing
11+
- **Helm**: Package manager for Kubernetes, used for deploying the charts
12+
- **PostgreSQL**: Relational database used for persistent storage
13+
- **HashiCorp Vault**: Secrets management system for secure credential storage
14+
15+
## Best Practices
16+
17+
- Use the official Helm charts for all deployments
18+
- Follow the [Installation Guide](../INSTALL.md) for local development setup
19+
- Test API endpoints using the provided Postman or Bruno collections
20+
21+
> [!NOTE]
22+
> When testing, it is recommended to enable ingress to avoid working with port-forwarding. Refer to the respective chart documentation for ingress configuration options, including hostname, TLS settings, and annotations.
23+
24+
## Documentation Resources
25+
26+
### [Developer Documentation](./developers/README.md)
27+
28+
Technical documentation for understanding the core data models, architecture patterns, and implementation details of both IdentityHub and IssuerService components.
29+
30+
This section provides detailed information about entity relationships, state machines, and complete workflow diagrams.
31+
Additionally, includes setup guides for configuring development environments.
32+
33+
### [API Documentation](./api/README.md)
34+
35+
Complete API reference and testing resources, including:
36+
37+
- **OpenAPI Specification**: Full API documentation with endpoints, schemas, and authentication requirements
38+
- **Postman Collection**: Ready-to-use Postman collection for issuance flow testing
39+
- **Bruno Collection**: Lightweight, Git-friendly API collection for Bruno
40+
- **Testing Guide**: Instructions for setting up and running API tests
41+
42+
### [Migration Guide](./admin/migration-guide.md)
43+
44+
Administrator guide for migrating between chart versions, including:
45+
46+
- Chart version migration instructions
47+
- Bitnami dependency updates and image repository changes
48+
- PostgreSQL version compatibility notes
49+
1850
---
1951

2052
## NOTICE
2153

2254
This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
2355

2456
* SPDX-License-Identifier: CC-BY-4.0
57+
* SPDX-FileCopyrightText: 2026 LKS Next
2558
* SPDX-FileCopyrightText: 2026 Contributors to the Eclipse Foundation
2659
* Source URL: <https://github.com/eclipse-tractusx/tractus-x-identityhub>

‎docs/developers/README.md‎

Lines changed: 49 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,59 @@
11
# Developers Documentation
22

3-
Welcome to the developer resources for the Identity components. This folder contains detailed data models and architectural overviews for the core services.
3+
Welcome to the developer resources for the Tractus-X Identity components. This documentation provides in-depth technical information about the data models, architecture patterns, and implementation details for both IdentityHub and IssuerService.
4+
5+
## Overview
6+
7+
This documentation is designed for developers who need to:
8+
9+
- Understand the internal data models and their relationships
10+
- Implement custom extensions or integrations
11+
- Debug and troubleshoot issues at the data model level
12+
- Contribute to the core codebase
13+
- Design systems that interact with these components
414

515
## Components
616

7-
* **[Identity Hub](./components/IdentityHub.md)**: Manages participant contexts, DIDs, and verifiable credentials.
8-
* **[Issuer Service](./components/IssuerService.md)**: Responsible for the validation of issuance requests and generation of credentials.
17+
### [Identity Hub](./components/IdentityHub.md)
18+
19+
The IdentityHub serves as a decentralized identity wallet managing credentials and identities for dataspace participants.
20+
21+
**Key Topics Covered:**
22+
- **Core Data Models**: ParticipantContext, CredentialResource, KeyPairResource, DidResource
23+
- **Data Relationships**: Entity relationship diagrams showing how models interconnect
24+
- **Data Flow**: Complete workflows from participant onboarding to credential presentation
25+
- **Storage Architecture**: How credentials, keys, and DIDs are persisted and managed
26+
27+
**Use Cases:**
28+
- **Credential Storage & Retrieval**: How verifiable credentials are stored and queried within the wallet
29+
- **Participant Onboarding**: Complete participant lifecycle from creation to activation
30+
- **DID Management**: Decentralized identifier creation, resolution, and key pair management
31+
- **Credential Presentation**: Requesting and verifying credential presentations during dataspace interactions
32+
33+
### [Issuer Service](./components/IssuerService.md)
34+
35+
The IssuerService handles the complete credential issuance workflow, from request validation to credential delivery.
36+
37+
**Key Topics Covered:**
38+
- **Core Data Models**: AttestationDefinition, CredentialDefinition, IssuanceProcess, Holder
39+
- **Issuance Workflow**: Complete credential request and delivery flow
40+
- **Credential Status & Revocation**: BitstringStatusList implementation for credential revocation
41+
- **Data Relationships**: How attestations, definitions, and processes work together
42+
- **DCP Protocol Integration**: Implementation of the Decentralized Claims Protocol
43+
44+
**Use Cases:**
45+
- **Attestation Configuration**: Defining custom attestation sources for claim validation
46+
- **Credential Templates**: Creating credential definitions with issuance rules and data mappings
47+
- **Credential Revocation**: Implementing BitstringStatusList for credential status management
48+
- **Holder Registry**: Managing entities authorized to receive credentials
49+
50+
## Setup Guides
951

10-
## Setup
52+
### [Linux](./setup/Linux.md)
1153

12-
* **[Linux](./setup/Linux.md)**: Linux setup and configuration guide.
54+
Comprehensive setup and configuration guide for Linux-based development environments, including:
55+
- Development environment setup
56+
- Local testing configurations
1357

1458
---
1559

0 commit comments

Comments
 (0)