docs(developer): create identity documentation (#247)

eclipse-tractusx · Feb 14, 2024 · 62423b2 · 62423b2
1 parent cb6b131
commit 62423b2
Show file tree

Hide file tree

Showing 10 changed files with 110 additions and 9 deletions.
diff --git a/docs/developer/02. Identity/01. Identity Process/00. Wallet Process.md b/docs/developer/02. Identity/01. Identity Process/00. Wallet Process.md
@@ -0,0 +1,39 @@
+## Self-Sovereign-Identity
+
+Inside the Catena-x world, managing your identity and data securely and efficiently is one of the key targets. Considering this, we implemented the usage of _Digital Wallet_ and _Credentials_ on Company level.
+
+### What is a Digital Wallet?
+
+A **Digital Wallet** in the context of a dataspace is an identity wallet of an company (note: it can be many other things as well, but in the context of the CX implementation we are talking about company identities). In detail: it holds your credentials, identity information, and potentially other company data. It's like a virtual safe where your digital identity components are stored securely. Your digital wallet can authenticate you across various platforms and services within the dataspace without the need to repeatedly enter your personal information.
+Within the concept of the digital wallet are the concepts of own and managed wallets.
+
+In the current implementation state of the datapsace only one wallet is supported, but extending to multiple wallets (managed as well as own) is planned shortly.
+
+### What are Credentials?
+
+**Credentials** are digital documents that prove various aspects of your identity or qualifications. These can include things like your identity itself (similar to digital ID card - just on a company level), memberships, or permissions to access certain data or services. These credentials are issued by trusted entities within the dataspace and are stored securely in your digital wallet.
+
+### Which roles play a game in the wallet/credential management?
+
+1. **Issuer**: Trusted entities in the dataspace issue digital credentials after verifying your identity or certifications. These credentials are then securely stored in your digital wallet.
+   Trusted issuer of the Catena-x dataspace are certified and available via the 'SSI Authority & Schema Registry'.
+
+2. **Wallet provider**: Wallet service provider which offer managed wallets for dataspace participants. Status: Coming Soon.
+
+### Important Links - Get to the implementation
+
+- Wallet Creation
+- Get a Credential (UseCase)
+- Get a Credential (CompanyRoles)
+- Issuer Component - _coming soon_
+
+<br>
+<br>
+
+## NOTICE
+
+This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+- SPDX-License-Identifier: Apache-2.0
+- SPDX-FileCopyrightText: 2021-2024 Contributors to the Eclipse Foundation
+- Source URL: https://github.com/eclipse-tractusx/portal-assets
diff --git a/...on/04. Credentials/00. Wallet Creation.md → ...2. Wallet Creation/00. Wallet Creation.md b/...on/04. Credentials/00. Wallet Creation.md → ...2. Wallet Creation/00. Wallet Creation.md
@@ -2,8 +2,8 @@
 
 ### Wallet Creation
 
-The wallet tenant per company is created as part of the dataspace registration.
-This includes a didWeb.
+As part of the dataspace registration a wallet tenant per company is created.
+This includes a DID Web.
 The managed identity wallet is created and new credentials are issued by th portal.
 A direct interface by the user is not provided.
 

diff --git a/...Credentials/01. Get UseCase Credential.md → ... Management/01. Get UseCase Credential.md b/...Credentials/01. Get UseCase Credential.md → ... Management/01. Get UseCase Credential.md
@@ -26,7 +26,7 @@ Functional Description: [here](/docs/user/06.%20Certificates/01.%20UseCase%20Par
 <br>
 
 The available credential types are fetched from the portal db company_ssi_details and verified_credential_external_type_use_case_detail_versions.
-The api response (see below) automatically includes the "ssiDetailData" which include the actual acting user company credential status. (e.g. if the company has one or several credentials of the use case framework requested or active already, it will be shown/displayed in the "ssiDetailData" section)
+The api response (see below) automatically includes the "ssiDetailData" which includes the actual acting user company credential status. (e.g. if the company has one or several credentials of the use case framework requested or already active, it will be shown/displayed in the "ssiDetailData" section).
 
 ```diff
 ! GET /api/administration/companydata/useCaseParticipation
@@ -70,7 +70,7 @@ Request Body
 
 ### Submit Credential request
 
-As part of the credential request submission (which is only possible if there is no PENDING request for the credential and version existing yet) the signed framework agreement need to get submitted.
+As part of the credential request submission (which is only possible if there is no PENDING request for the credential and version existing yet) the signed framework agreement needs to get submitted.
 
 ```diff
 ! POST /api/administration/companydata/useCaseParticipation

diff --git a/...04. Credentials/02. Other Certificates.md → ...tial Management/02. Other Certificates.md b/...04. Credentials/02. Other Certificates.md → ...tial Management/02. Other Certificates.md
@@ -1,6 +1,6 @@
 ## Company Certificates
 
-Beside the Use Case Frameworks, companies can apply/request for other kind of company certificates as well.
+Beside the Use Case Frameworks, companies can apply/request for other kinds of company certificates as well.
 
 Currently Supported:
 
@@ -62,8 +62,8 @@ Response Body
 
 ### Available Certificate Document Requests
 
-With the page load, the GET /certificateTypes endpoint is triggered which gets used to manage the "Upload Certificate" Button as well as the overlay content.
-The endpoint only response with those certificate types which the user company can actually request.
+With the page load, the GET /certificateTypes endpoint is triggered which gets used to manage the "Upload Certificate" button as well as the overlay content.
+The endpoint responds only with those certificate types which the user company can actually request.
 
 Backend Logic:
 
@@ -92,7 +92,7 @@ Backend Logic:
 
 ### Submit Certificate request
 
-As part of the credential request submission (which is only possible if there is no PENDING request for the credential and version existing yet) the signed framework agreement need to get submitted.
+As part of the credential request submission (which is only possible if there is no PENDING request for the credential and version yet existing) the signed framework agreement needs to get submitted.
 
 ```diff
 ! POST /api/administration/companydata/certificates

diff --git a/...Credentials/03. Credential Admin Board.md → ... Management/03. Credential Admin Board.md b/...Credentials/03. Credential Admin Board.md → ... Management/03. Credential Admin Board.md
@@ -166,7 +166,7 @@ Request Body
 
 #### Reject Credential Request
 
-With the credential reject button, the credential request decline endpoint is triggered (see details below) additionally, following task will get executed
+With the credential reject button, the credential request decline endpoint is triggered (see details below) additionally, following task will get executed:
 
 - credential request is getting set to "Inactive" (table: company_ssi_details)
 - the requester company is getting informed about the rejection/decline of the credential and is allowed to start a new request (via email)

diff --git a/docs/developer/02. Identity/04. Wallet UI/01. Wallet UI.md b/docs/developer/02. Identity/04. Wallet UI/01. Wallet UI.md
@@ -0,0 +1,50 @@
+## Wallet UI
+
+With release 24.03. the wallet UI was introduced inside the portal application.
+The wallet ui connects the company wallet (technical component as managed service which is provided by the operator) with an user interface giving the company users an access to the content.
+
+Inside the wallet UI the owned credentials, their expiry as well as the authority are displayed.
+
+<br>
+
+### Authentication
+
+The authentication is a direct connection to the backend service of the wallet (as per release 24.03.).
+The user jwt token is getting validated and used to authorize.
+With the implementation of 24.05. a change is planned.
+
+<br>
+
+### Architecture View
+
+<img width="152" alt="image" src="https://raw.githubusercontent.com/eclipse-tractusx/portal-assets/main/docs/static/walletUIArchitecture.png">
+
+<br>
+
+### Implementation Details
+
+#### Design Example
+
+<br>
+
+<img width="152" alt="image" src="https://raw.githubusercontent.com/eclipse-tractusx/portal-assets/main/docs/static/walletUI.png">
+
+<br>
+
+#### API Connection
+
+Calling the configured wallet solution (as per the env. file config) endpoint
+
+```
+GET /api/credentials
+```
+
+<br>
+
+## NOTICE
+
+This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+- SPDX-License-Identifier: Apache-2.0
+- SPDX-FileCopyrightText: 2021-2024 Contributors to the Eclipse Foundation
+- Source URL: https://github.com/eclipse-tractusx/portal-assets
diff --git a/docs/static/walletUI.png b/docs/static/walletUI.png
diff --git a/docs/static/walletUI.png.license b/docs/static/walletUI.png.license
@@ -0,0 +1,6 @@
+This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
+
+- SPDX-License-Identifier: CC-BY-4.0
+- SPDX-FileCopyrightText: Copyright (c) 2024 Contributors to the Eclipse Foundation
+- Source URL: https://github.com/eclipse-tractusx/portal-assets
+
diff --git a/docs/static/walletUIArchitecture.png b/docs/static/walletUIArchitecture.png
diff --git a/docs/static/walletUIArchitecture.png.license b/docs/static/walletUIArchitecture.png.license
@@ -0,0 +1,6 @@
+This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
+
+- SPDX-License-Identifier: CC-BY-4.0
+- SPDX-FileCopyrightText: Copyright (c) 2024 Contributors to the Eclipse Foundation
+- Source URL: https://github.com/eclipse-tractusx/portal-assets
+