Skip to content

Commit 43af55d

Browse files
CDiezRodriguezCDiezRodriguez
authored
Merge pull request #221 from Alaitz1/feat(docs)/Developers-Documentation
chore: add developers guide and IdentityHub documentation
2 parents 718db13 + 96c1c9c commit 43af55d

File tree

4 files changed

+223
-0
lines changed

4 files changed

+223
-0
lines changed

‎docs/README.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Documentation Overview
2+
3+
This directory contains the complete documentation for the Identity Hub and Issuer Service components. The documentation is organized by target audience and functional area.
4+
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+
18+
---
19+
20+
## NOTICE
21+
22+
This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
23+
24+
* SPDX-License-Identifier: CC-BY-4.0
25+
* SPDX-FileCopyrightText: 2026 Contributors to the Eclipse Foundation
26+
* Source URL: <https://github.com/eclipse-tractusx/tractus-x-identityhub>

‎docs/developers/README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Developers Documentation
2+
3+
Welcome to the developer resources for the Identity components. This folder contains detailed data models and architectural overviews for the core services.
4+
5+
## Components
6+
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.
9+
10+
## Setup
11+
12+
* **[Linux](./setup/Linux.md)**: Linux setup and configuration guide.
13+
14+
---
15+
16+
## NOTICE
17+
18+
This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
19+
20+
* SPDX-License-Identifier: CC-BY-4.0
21+
* SPDX-FileCopyrightText: 2026 LKS Next
22+
* SPDX-FileCopyrightText: 2026 Contributors to the Eclipse Foundation
23+
* Source URL: <https://github.com/eclipse-tractusx/tractus-x-identityhub>

‎docs/developers/components/IdentityHub.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# IdentityHub Data Models
2+
3+
This document provides an overview of the core data models in the IdentityHub component, based on the upstream **Eclipse EDC IdentityHub** project.
4+
5+
---
6+
7+
## Core Data Models
8+
9+
The IdentityHub manages several interconnected entities that work together to provide comprehensive identity and credential management functionality:
10+
11+
### 1. ParticipantContext
12+
13+
The `ParticipantContext` (specifically `IdentityHubParticipantContext`) represents a dataspace participant and serves as the top-level organizational unit.
14+
15+
* **Purpose:** Serves as the primary organizational entity that owns and manages all other resources (credentials, DIDs, key pairs) for a specific participant.
16+
* **Lifecycle Events:**
17+
18+
* `ParticipantContextCreated`: Emitted when a new context is created.
19+
* `ParticipantContextUpdated`: Emitted when context properties change.
20+
* `ParticipantContextDeleting`: Emitted before deletion to allow cleanup.
21+
22+
### 2. CredentialResource
23+
24+
The `CredentialResource` represents a verifiable credential stored in the IdentityHub.
25+
26+
* **Purpose:** Stores and manages verifiable credentials received from issuers, enabling participants to hold and present credentials during **DCP (Decentralized Claims Protocol)** flows.
27+
28+
### 3. KeyPairResource
29+
30+
The `KeyPairResource` represents a cryptographic key pair used for signing and verification operations.
31+
32+
* **Purpose:** Manages cryptographic key pairs for signing credentials and presentations. Supports key rotation and comprehensive lifecycle management.
33+
34+
#### Lifecycle States
35+
36+
| State | Code | Description |
37+
| :--- | :--- | :--- |
38+
| **CREATED** | 100 | Key pair created in database but not yet active. Private key in vault. |
39+
| **ACTIVATED** | 200 | Actively used for signing. Public key added to the DID document. |
40+
| **ROTATED** | 300 | Can still verify signatures but cannot sign new ones. Transitional state. |
41+
| **REVOKED** | 400 | Completely retired. Verification method removed from DID document. |
42+
43+
### 4. DidResource
44+
45+
The `DidResource` wraps a DID Document and represents its lifecycle in the IdentityHub.
46+
47+
* **Purpose:** Manages DIDs and their corresponding DID Documents, which contain public keys, service endpoints, and other metadata.
48+
* **Lifecycle:** DID Documents are automatically updated when `KeyPairResources` are activated or revoked.
49+
50+
---
51+
52+
## Relationships
53+
54+
The data models are interconnected as follows:
55+
56+
* **ParticipantContext (1)**
57+
* └── *owns* → **CredentialResource** (many)
58+
* └── *owns* → **KeyPairResource** (many)
59+
* └── *owns* → **DidResource** (many)
60+
* **CredentialResource**
61+
* └── *references* → `ParticipantContext` (via `participant_context_id`)
62+
* **KeyPairResource**
63+
* └── *references* → `ParticipantContext` (via `participant_context_id`)
64+
* └── *influences* → `DidResource` (verification methods)
65+
* **DidResource**
66+
* └── *references* → `ParticipantContext` (via `participant_context_id`)
67+
68+
---
69+
70+
## Data Flow
71+
72+
1. **Participant Onboarding:** A `ParticipantManifest` is submitted; a `ParticipantContext` is created with an API token.
73+
2. **DID and Key Creation:** `DidResource` and `KeyPairResource` entries are created based on the manifest.
74+
3. **Key Pair Activation:** Key pairs transition to `ACTIVATED`, and public keys are added to the DID Document.
75+
4. **Credential Reception:** `CredentialResource` entries are created when credentials are issued to the participant.
76+
5. **Credential Presentation:** During DCP flows, credentials are retrieved, wrapped in presentations, and signed using active keys.
77+
6. **Key Rotation:** Old key pairs transition to `ROTATED` (verify only), while new keys are `ACTIVATED`. After a duration, old keys become `REVOKED`.
78+
79+
---
80+
81+
## Additional Information
82+
83+
For more detailed information about the Eclipse EDC IdentityHub architecture, refer to the upstream documentation:
84+
85+
* **Architecture Overview:** [Identity Hub Architecture](https://github.com/eclipse-edc/IdentityHub)
86+
87+
---
88+
89+
## NOTICE
90+
91+
This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
92+
93+
* SPDX-License-Identifier: CC-BY-4.0
94+
* SPDX-FileCopyrightText: 2026 LKS Next
95+
* SPDX-FileCopyrightText: 2026 Contributors to the Eclipse Foundation
96+
* Source URL: <https://github.com/eclipse-tractusx/tractus-x-identityhub>

‎docs/developers/setup/Linux.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Linux Deployment Guide: IdentityHub and IssuerService
2+
3+
This guide combines the steps for Cluster Setup, Network Setup, and Installation for Linux users.
4+
5+
---
6+
7+
## 1. Cluster Setup
8+
9+
This guide provides instructions to set up a Kubernetes cluster required for running the IdentityHub and IssuerService Chart.
10+
11+
### Start Minikube
12+
13+
Start a Minikube cluster with the following command:
14+
15+
```bash
16+
minikube start
17+
```
18+
19+
## 2. Network Setup
20+
21+
This guide provides instructions to configure the network setup required for running the IdentityHub and IssuerService Chart in a Kubernetes cluster.
22+
23+
### Enabled Ingresses
24+
25+
To enable ingress for local access, use the following command with Minikube:
26+
27+
```bash
28+
minikube addons enable ingress
29+
```
30+
31+
Make sure that the **DNS** resolution for the hosts is in place:
32+
33+
```bash
34+
minikube addons enable ingress-dns
35+
```
36+
37+
And execute installation step [3 Add the `minikube ip` as a DNS server](https://minikube.sigs.k8s.io/docs/handbook/addons/ingress-dns) for your OS
38+
39+
### DNS Resolution Setup
40+
41+
Proper DNS resolution is required to map local domain names to the Minikube IP address.
42+
43+
#### Hosts File Configuration
44+
45+
1. Open the hosts file you find here `/etc/hosts` and insert the values from below.
46+
47+
```text
48+
<MINIKUBE_IP> identityhub.presentation.local
49+
<MINIKUBE_IP> identityhub.identity.local
50+
<MINIKUBE_IP> issuerservice.issuance.local
51+
<MINIKUBE_IP> issuerservice.did.local
52+
```
53+
54+
2. Replace `<MINIKUBE_IP>` with the output of the following command:
55+
56+
```bash
57+
minikube ip
58+
```
59+
60+
3. Test DNS resolution by pinging one of the configured hostnames.
61+
62+
## 3. Localhost Deployment
63+
64+
For detailed installation instructions, please refer to the [Installation Guide](../../..//INSTALL.md)
65+
66+
> [!IMPORTANT]
67+
> It is strongly recommended to deploy with **Ingress enabled**. In each component's `values.yaml`, there are two ingresses that have to be enabled to true. This allows you to use the internal URLs (e.g., `identityhub.presentation.local`) without additional configuration.
68+
> [!WARNING]
69+
> The path /.well-known is mandatory for did:web resolution. However, the Nginx Admission Webhook often blocks paths starting with a dot. You must edit the ingress.yaml file in the templates folder and change the pathType to ImplementationSpecific.
70+
71+
## NOTICE
72+
73+
This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
74+
75+
* SPDX-License-Identifier: CC-BY-4.0
76+
* SPDX-FileCopyrightText: 2026 LKS Next
77+
* SPDX-FileCopyrightText: 2026 Contributors to the Eclipse Foundation
78+
* Source URL: <https://github.com/eclipse-tractusx/tractus-x-identityhub>

0 commit comments

Comments
 (0)