Skip to content

Commit 402be5e

Browse files
Phil91evegufy
Phil91
and
evegufy
authored
docs: add architecture documentation (eclipse-tractusx#132)
Refs: eclipse-tractusx#119 Co-authored-by: Evelyn Gurschler <[email protected]>
1 parent f4c1bca commit 402be5e

19 files changed

+1407
-25
lines changed

‎README.md

+4
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22

33
This repository contains the backend code for the SSI Credential Issuer written in C#.
44

5+
For **information about the SSI Credential Issuer**, please refer to the documentation, especially the context and scope section in the [architecture documentation](./docs/architecture).
6+
7+
For **installation** details, please refer to the [README.md](./charts/ssi-credential-issuer/README.md) of the provided helm chart.
8+
59
## How to build and run
610

711
Install the [.NET 8.0 SDK](https://www.microsoft.com/net/download).

‎docker/notice-credential-issuer-service.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ DockerHub: [https://hub.docker.com/r/tractusx/ssi-credential-issuer-service](htt
44

55
Eclipse Tractus-X product(s) installed within the image:
66

7-
__Policy Hub Service__
7+
__SSI Credential Issuer Service__
88

99
- GitHub: https://github.com/eclipse-tractusx/ssi-credential-issuer
1010
- Project home: https://projects.eclipse.org/projects/automotive.tractusx

‎docs/architecture/Architecture Constraints.md

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Architecture Constraints
2+
3+
## General
4+
5+
- The SSI Credential Issuer is a central API for the handling of credentials. It handles the wallet communication for the creation and revocation of credentials of the issuer and holder. Another purpose is the expiry handling and automatic revocation of already expired credentials. There is no plan to implement an UI at the current stage.
6+
7+
- Run anywhere: can be deployed as a docker image, e. g. on Kubernetes (platform-independent, cloud, on prem or local).
8+
9+
## Developer
10+
11+
- OpenSource software first - FOSS licenses approved by the eclipse foundation has to be used. It could represent the initial set that the CX community agrees on to regulate the content contribution under FOSS licenses.
12+
13+
- Coding guidelines for FE and BE are defined and are to be followed for all portal related developments.
14+
15+
- Apache License 2.0 - Apache License 2.0 is one of the approved licenses which should be used to respect and guarantee Intellectual property (IP).
16+
17+
- Code Analysis, Linting and Code Coverage - Consistent style increases readability and maintainability of the code base. Hence, we use analyzers to enforce consistency and style rules. We enforce the code style and rules in the CI to avoid merging code that does not comply with standards.
18+
19+
## Code analysis, linting and code coverage
20+
21+
As part of the standard reviews, following code analysis and security checks have been executed:
22+
23+
- SonarCloud Code Analysis
24+
- Thread Modelling Analysis
25+
- Static Application Security Testing (SAST)
26+
- Dynamic Application Security Testing (DAST)
27+
- Secret Scans
28+
- Software Composition Analysis (SCA)
29+
- Container Scans
30+
- Infrastructure as Code (IaC)
31+
32+
## NOTICE
33+
34+
This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
35+
36+
- SPDX-License-Identifier: Apache-2.0
37+
- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
38+
- Source URL: https://github.com/eclipse-tractusx/ssi-credential-issuer

‎docs/architecture/Context and scope.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Content and Scope
2+
3+
## Business Context
4+
5+
The SSI credential issuer is created to enable the communication with wallets and handle the creation, revocation and expiry of credentials.
6+
Additionally it gives the user a overview of available use case credentials.
7+
8+
## Technical Context
9+
10+
The SSI credential issuer comprise the technical foundation for interaction, monitoring, auditing and further functionalities. They are state of the art in terms of technology portfolio, consist of open-source components whenever possible and are open-sourced themselves 100%.
11+
12+
## NOTICE
13+
14+
This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
15+
16+
- SPDX-License-Identifier: Apache-2.0
17+
- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
18+
- Source URL: https://github.com/eclipse-tractusx/ssi-credential-issuer

‎docs/architecture/Development Concept.md

+143
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Development Concept
2+
3+
## Build, test, deploy
4+
5+
Details to the build, test and deploy process can get found under the following md file: [Release Process](/docs/technical-documentation/release-process/Release%20Process.md)
6+
7+
## Development Guidelines
8+
9+
The SSI credential issuer is using following key frameworks:
10+
11+
- .Net
12+
- Entity Framework
13+
14+
### Swagger
15+
16+
The API uses OpenAPI annotations to describe the endpoints with all necessary information. The annotations are then used to automatically generate the OpenAPI specification file, which can be viewed in the Swagger UI that is deployed with the application.
17+
18+
#### API Dev Guidelines
19+
20+
##### Implement authorization
21+
22+
API's need to ensure that they only grant access to the authorized requester. For example, a user might be approved to access the API, but if they’re not allowed to add information to the application’s database via the POST method, any request to do so should be rejected. Authorization information can also be contained within a request as a token.
23+
24+
Unlike some other API types, REST APIs must authenticate and authorize each request made to the server, even if multiple requests come from the same user. This is because REST communications are stateless — that is, each request can be understood by the API in isolation, without information from previous requests.
25+
26+
Authorization can be governed by user roles, where each role comes with different permissions. Generally, API developers should adhere to the principle of least privilege, which states that users should only have access to the resources and methods necessary for their role, and nothing more. Predefined roles make it easier to oversee and change user permissions, reducing the chance that a bad actor can access sensitive data.
27+
28+
In terms of implementation all endpoints should be secured with the highest restrictions as default. Restrictions should only be lessened through explicit exemptions. This ensures that in case of oversights an endpoint can be more secured than intended but never less secured.
29+
30+
##### Validate all requests
31+
32+
As mentioned, sometimes requests from perfectly valid sources may be hacking attempts. Therefore, APIs need rules to determine whether a request is friendly, friendly but invalid, or harmful, like an attempt to inject harmful code.
33+
34+
An API request is only processed once its contents pass a thorough validation check — otherwise, the request should never reach the application data layer.
35+
36+
Validation also includes sanity checks: Define sensible value ranges for the parameters a user provides. This especially is valid for the size of the request and the response. APIs should limit the possible number of records to process in order to prevent intentional or unintentional overloads of the system.
37+
38+
##### Encrypt all requests and responses
39+
40+
To prevent MITM attacks, any data transfer from the user to the API server or vice versa must be properly encrypted. This way, any intercepted requests or responses are useless to the intruder without the right decryption method.
41+
42+
Since REST APIs use HTTP, encryption can be achieved by using the Transport Layer Security (TLS) protocol or Secure Sockets Layer (SSL) protocol. These protocols supply the S in “HTTPS” (“S” meaning “secure'') and are the standard for encrypting web pages and REST API communications.
43+
44+
TLS/SSL only encrypts data when that data is being transferred. It doesn’t encrypt data sitting behind your API, which is why sensitive data should also be encrypted in the database layer as well.
45+
46+
##### Only include necessary information in responses
47+
48+
Like you might unintentionally let a secret slip when telling a story to a friend, it’s possible for an API response to expose information hackers can use. To prevent this, all responses sent to the end-user should include only the information to communicate the success or failure of the request, the resource requested (if any), and any other information directly related to these resources.
49+
50+
In other words, avoid “oversharing” data — the response is a chance for you to inadvertently expose private data, either through the returned resources or verbose status messages.
51+
52+
=> in the ownership of every API Developer
53+
54+
##### Throttle API requests and establish quotas
55+
56+
To prevent brute-force attacks like DDoS, an API can impose rate-limiting, a way to control the number of requests to the API server at any given time.
57+
58+
There are two main ways to rate-limit API requests, quotas and throttling. Quotas limit the number of requests allowed from a user over a span of time, while throttling slows a user’s connection while still allowing them to use your API.
59+
60+
Both methods should allow normal API requests but prevent floods of traffic intended to disrupt, as well as unexpected request spikes in general.
61+
62+
##### Log API activity
63+
64+
Logging API activities is extremely important when it comes to tracing user activity and in worst case hack activity.
65+
66+
###### Conduct security tests
67+
68+
=> see [Test Section](#tests) below
69+
70+
##### Error Handling
71+
72+
The simplest way we handle errors is to respond with an appropriate status code.
73+
74+
Common agreed response codes:
75+
76+
- 400 Bad Request – client sent an invalid request, such as lacking required request body or parameter.
77+
Example: The same constraint has been configured multiple times in the request
78+
- 401 Unauthorized – user authenticated but doesn't have permission to access the requested resource.
79+
Example: User token doesn't have the access on the resource.
80+
- 403 Forbidden – client failed to authenticate with the server.
81+
Example: token expired oder invalid login.
82+
- 404 Not Found – the requested resource does not exist.
83+
Example: A specific credential was requested which does not exist in the database.
84+
- 500 Internal Server Error – a generic error occurred in the internal system logic.
85+
Example: Unexpected server-side issue during credential validation.
86+
Additionally to the generic error code, a detailed message/error is needed to ensure that the issue can get validated and resolved quickly.
87+
88+
##### Repository Pattern
89+
90+
The repositories are used via the Factory HubRepositories, which ensures that the same database instance is used for all repositories.
91+
92+
Furthermore, it provides an implicit transaction functionality.
93+
94+
The repositories themselves must not be registered for dependency injection in the corresponding startup; the method IssuerRepositories.GetInstance<RepositoryType> provides the instance of a requested repository.
95+
96+
In the repository itself, you should not work with SaveChanges, it should only be called via the IssuerRepositories.SaveChanges to ensure that any transaction dependencies can be rolled back.
97+
98+
#### Tests
99+
100+
##### User Authentication Test
101+
102+
If authentication mechanisms are implemented incorrectly, attackers can compromise authentication tokens or exploit implementation flaws to assume other users’ identities and gain access to your API’s endpoints.
103+
104+
To test your authentication mechanisms, try sending API requests without proper authentication (either no tokens or credentials, or incorrect ones) and see if your API responds with the correct error and messaging.
105+
106+
##### Parameter Tampering Test
107+
108+
To run a parameter tampering test, try various combinations of invalid query parameters in your API requests and see if it responds with the correct error codes. If not, then your API likely has some backend validation errors that need to be resolved.
109+
110+
##### Injection Test
111+
112+
To test if your API is vulnerable to injections, try injecting SQL, NoSQL, LDAP, OS, or other commands in API inputs and see if your API executes them. These commands should be harmless, like reboot commands or cat commands.
113+
114+
##### Unhandled HTTP Methods Test
115+
116+
Most APIs have various HTTP methods that are used to retrieve, store, or delete data. Sometimes web servers will give access to unsupported HTTP methods by default, which makes your API vulnerable.
117+
118+
To test for this vulnerability, you should try all the common HTTP methods (POST, GET, PUT, PATCH, and DELETE) as well as a few uncommon ones. TRY sending an API request with the HEAD verb instead of GET, for example, or a request with an arbitrary method like FOO. You should get an error code, but if you get a 200 OK response, then your API has a vulnerability.
119+
120+
##### Load Test
121+
122+
Load testing should be one of the last steps of your API security auditing process. This type is pushing the API to its limits in order to discover any functional or security issues that have yet to be revealed.
123+
124+
To achieve this, send a large number of randomized requests, including SQL queries, system commands, arbitrary numbers, and other non-text characters, and see if your API responds with errors, processes any of these inputs incorrectly, or crashes. This type of testing will mimic Overflow and DDoS attacks.
125+
126+
An API manager or gateway tool will handle or help address the API security guidelines described above (including testing).
127+
128+
## Migration
129+
130+
To run the SSI credential issuer, migrations are needed to load the initial data inside the SSI credential issuer db to enable the SSI credential issuer to work.
131+
The migration will consist of an initial migration as well as delta migration files with future releases. As part of a new release, a migration file (if applicable) will get released and can get loaded via a delta load.
132+
133+
## Configurability
134+
135+
SSI Credential Issuer configuration is mainly possible via the appsettings files as well as the static data migration files.
136+
137+
## NOTICE
138+
139+
This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
140+
141+
- SPDX-License-Identifier: Apache-2.0
142+
- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
143+
- Source URL: https://github.com/eclipse-tractusx/ssi-credential-issuer

‎docs/architecture/Requirements.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Requirements overview
2+
3+
## What is the Portal & Marketplace Product?
4+
5+
The SSI Credential Issuer is a central API for the handling of credentials. It handles the wallet communication for the creation and revocation of credentials of the issuer and holder. Another purpose is the expiry handling and automatic revocation of already expired credentials. There is no plan to implement an UI at the current stage.
6+
7+
## Requirements
8+
9+
<!-- TODO (JJ): could you please add the requirements -->
10+
For Catena-X Member Companies
11+
|ID|Title|Requirement|
12+
|--------|--------|--------|
13+
|REQ|tbd|tbd|
14+
15+
## NOTICE
16+
17+
This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
18+
19+
- SPDX-License-Identifier: Apache-2.0
20+
- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
21+
- Source URL: https://github.com/eclipse-tractusx/ssi-credential-issuer

‎docs/architecture/Security_Assessment.md

+16-20
Original file line numberDiff line numberDiff line change
@@ -33,12 +33,12 @@ flowchart LR
3333
CU(Company user or Service Account)
3434
K("Keycloak (REST API)")
3535
IS(Issuer Service)
36-
CS(Credential Service)
37-
RS(Revocation Service)
3836
EW(Expiry Worker)
3937
IW(Issuer Wallet)
38+
PW(Process Worker)
4039
HW(3rd Party Holder Wallets)
41-
P(Portal Backend)
40+
PB(Portal Backend)
41+
PF(Portal Frontend)
4242
PHD[(Issuer DB \n Postgres \n EF Core for mapping \n objects to SQL)]
4343
4444
subgraph centralidp[centralidp Keycloak]
@@ -51,33 +51,29 @@ flowchart LR
5151
5252
subgraph SSI-Issuer-Component Product
5353
IS
54-
CS
55-
RS
54+
PW
5655
EW
5756
PHD
5857
end
5958
6059
subgraph External Systems
61-
P
60+
PB
61+
PF
6262
IW
6363
HW
6464
end
6565
6666
K-->|"Authentication & Authorization Data \n (Using JWT)"|IS
67-
K-->|"Authentication & Authorization Data \n (Using JWT)"|CS
68-
K-->|"Authentication & Authorization Data \n (Using JWT)"|RS
69-
CU-->|"Consumption of central, read-only REST API \n [HTTPS]"|IS
70-
CU-->|"Consumption of central, read-only REST API \n [HTTPS]"|CS
71-
CU-->|"Consumption of central, read-only REST API \n [HTTPS]"|RS
72-
IS-->|"Read and write credentials"|PHD
73-
IS-->|"Read and write credentials"|IW
74-
IS-->|"Read and write credentials"|HW
75-
EW-->|"Read and write credentials"|IW
76-
RS-->|"Read and write credentials"|IW
77-
P-->|"Create and revoke credentials"|IS
78-
IS-->|"Create notifications and mails"|P
79-
CS-->|"Read credentials and document"|PHD
80-
RS-->|"Read and update credential data"|PHD
67+
IS-->|"Read and write credential data"|PHD
68+
PF-->|"Read and Write Credentials"|IS
69+
PW-->|"Read and Write Credentials"|HW
70+
PW-->|"Write Credentials"|IW
71+
PW-->|"Creates Mails & Notifications"|PB
72+
PW-->|"Revoke Credential"|IW
73+
EW-->|"Read credentials \n write process data"|PHD
74+
PB-->|"Create and revoke credentials"|IS
75+
PF-->|"Read and Write Credentials"|IS
76+
IS-->|"Create notifications and mails"|PB
8177
CU-->|"IAM with OIDC \n [HTTPS]"|K
8278
```
8379

‎docs/architecture/Solution strategy.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Solution Strategy
2+
3+
- The technology portfolio and development stack are kept simple, based on commodity and oss components and products.
4+
- APIs are always REST-based with token authentication.
5+
- OIDC is used for authentication and authorization.
6+
- IaC is fully realized via helm charts.
7+
8+
## NOTICE
9+
10+
This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
11+
12+
- SPDX-License-Identifier: Apache-2.0
13+
- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
14+
- Source URL: https://github.com/eclipse-tractusx/ssi-credential-issuer

‎docs/architecture/Whitebox Overall System.md

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Whitebox Overall System
2+
3+
## Summary
4+
5+
In the following image you see the overall system overview of the SSI Credential Issuer
6+
7+
```mermaid
8+
flowchart LR
9+
10+
C(Customer)
11+
ING(Ingress)
12+
IS(Issuer Service)
13+
ES(Expiry Service)
14+
PW(Process Worker)
15+
P(Portal)
16+
HW(Holder Wallet)
17+
IW(Issuer Wallet)
18+
PHD[("Postgres Database \n \n (Base data created with \n application seeding)")]
19+
20+
subgraph SSI Credential Issuer Product
21+
ING
22+
PHD
23+
IS
24+
ES
25+
PW
26+
end
27+
28+
subgraph External Systems
29+
P
30+
HW
31+
IW
32+
end
33+
34+
C-->|"Authentication & Authorization Data \n (Using JWT)"|ING
35+
ING-->|"Forward Request"|IS
36+
ES-->|"Revokes Credentials"|IW
37+
ES-->|"Revokes Credentials"|HW
38+
ES-->|"Creates Mails & Notifications"|P
39+
ES-->|"Reads & updates credentials"|PHD
40+
PW-->|"Read, Write & Sign Credentials"|IW
41+
PW-->|"Write Credentials"|HW
42+
PW-->|"Creates Mails & Notifications"|P
43+
PW-->|"Reads credential requests, \n saves documents"|PHD
44+
IS-->|"Read credentialTypes and versions, \n saves credential requests, \n revokes credential"|PHD
45+
ES-->|"Updates credentials"|PHD
46+
47+
```
48+
49+
## NOTICE
50+
51+
This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
52+
53+
- SPDX-License-Identifier: Apache-2.0
54+
- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
55+
- Source URL: https://github.com/eclipse-tractusx/ssi-credential-issuer

0 commit comments

Comments
 (0)