docs: added and enhanced credential management documentation (#360)

docs/developer/06. Certificates/04. Credential Revocation.md → docs/developer/06. Credential Management/04. Credential Revocation.md

@@ -1,56 +1,84 @@
 ## Credential Revocation Feature Documentation
 
-### Description
+The credential revocation flow is enabled for two scenarios:
+
+1. Recovation by issuer
+2. Revocation by holder
+
+### Revocation by Issuer
+
+#### Description
 
 The issuer admin board now includes a feature that allows the revocation of "Active" credentials. Issuers assigned with the "revoke_credentials_issuer" permission can utilize this feature to manage the valid status of issued credentials.
 
-### Revocation Capability
+#### Revocation Capability
 
 Issuers with the necessary permissions can now revoke credentials that are marked as "Active." This feature is crucial for maintaining the integrity and trustworthiness of the credentialing system.
 
-### UI Integration
+#### UI Integration
 
 A revoke option, represented by the MaterialUI `SettingsBackupRestore` icon, has been added to the issuer admin board. This icon is displayed next to each "Active" credential, enabling easy access to the revocation function.
 
 <img width="70" alt="image" src="https://raw.githubusercontent.com/eclipse-tractusx/portal-assets/main/docs/static/credential-revocation-icon.png">
 
 This option is only visible and accessible to users who have been granted the "revoke_credentials_issuer" permission.
 
-### Confirmation Overlay
+#### Confirmation Overlay
 
 When the revoke icon is clicked, a confirmation overlay appears to ensure the issuer intends to proceed with the revocation. The overlay provides "Cancel" and "Confirm" options to either abort or continue with the process.
 
 <img width="300" alt="image" src="https://raw.githubusercontent.com/eclipse-tractusx/portal-assets/main/docs/static/credential-revocation-overlay.png">
 
-### API Integration
+#### API Integration
 
 Upon confirming the revocation, the system will trigger an API call to the revocation endpoint with the specific credential ID that is to be revoked.
 
-**API Endpoint**: `POST /api/revocation/issuer/credentials/{credentialId}`
+- **URL**: `/api/revocation/issuer/credentials/{credentialId}`
+- **Method**: `POST`
+- **Permission**: `revoke_credentials_issuer`
 
 The `{credentialId}` in the endpoint's path should be replaced with the actual ID of the credential being revoked.
 
-### Loading State and User Feedback
+#### Loading State and User Feedback
 
 A loading indicator is displayed while the revocation request is processed. Feedback is provided to the issuer once the API responds, indicating the success or failure of the revocation.
 
-### Success/Error Handling
+#### Success/Error Handling
 
 The user will receive a notification upon successful revocation. In the event of a failure, an error message will be displayed.
 
-**Unsuccessful Revocation Message**:
+#### Permissions Check
 
-- DE: "Der Widerruf der Berechtigung war erfolglos. Bitte wenden Sie sich an den Administrator oder versuchen Sie es später erneut."
-- EN: "The revocation of the credential was unsuccessful. An error occurred. Please try again. If the problem persists, contact the site administrator."
+The system verifies that only users with the "revoke_credentials_issuer" permission can access and use the revocation feature, adhering to the established permission system.
 
-**Successful Revocation Message**:
+<br>
 
-- DE: "Der Widerruf Ihrer Zugangsdaten wurde erfolgreich verarbeitet. Mit der erfolgreichen Sperrung verliert der Ausweis seine Gültigkeit. Beachten Sie, dass die Aktion nach dem Widerrufen eines Berechtigungsnachweises nicht mehr rückgängig gemacht werden kann und der Berechtigungsnachweis nicht mehr als gültig anerkannt wird."
-- EN: "The customer credential revocation has been successfully processed. With the successful revocation, the credential is no longer valid. Note that once a credential is revoked, the action cannot be undone, and the credential will no longer be recognized as valid."
+### Revocation by Holder
 
-### Permissions Check
+#### API Endpoint
 
-The system verifies that only users with the "revoke_credentials_issuer" permission can access and use the revocation feature, adhering to the established permission system.
+- **URL**: `/api/revocation/credentials/{credentialId}`
+- **Method**: `POST`
+- **Permission**: `revoke_credential`
+
+#### Validation
+
+- Ensure that the caller of the endpoint is the holder.
+- Check if the credential is "active" and revocable.
+  - If "yes", proceed with revocation.
+  - If "no", respond with "already done".
+
+#### API Responses
+
+- **200 OK**: Revocation successful.
+- **401 Unauthorized**: Authentication failed.
+- **403 Forbidden**: Authorization failed.
+- **404 Not Found**: Credential ID not found.
+- **500 Internal Server Error**: Server-side error.
+
+#### Success/Error Handling
+
+The user will receive a notification upon successful revocation. In the event of a failure, an error message will be displayed.
 
 <br>
 

docs/developer/Technical Documentation/Interface Contracts/Credential Issuer.md

@@ -0,0 +1,89 @@
+## Credential Issuer Component
+
+### Interface Summary
+
+This interface contract specifies the interaction between the portal and the issuer component responsible for creating, managing, and revoking Self-Sovereign Identity (SSI) credentials within the Catena-X dataspace.
+
+### Architecture Overview
+
+The portal serves as the front-end interface through which users interact with the credential issuer component. The issuer component is a back-end service handling the lifecycle of credentials, such as creating, issuing, approving, rejecting, and revoking credentials. The component is accessible via RESTful APIs and integrates with Keycloak for authentication and authorization purposes.
+
+### Authentication Flow / Details
+
+Authentication is performed using OAuth 2.0, where clients must obtain a valid access token from Keycloak.
+
+- **Token Endpoint**: Clients access Keycloak's token endpoint to obtain an access token.
+- **Token Usage**: The access token is then included in the `Authorization` header as a Bearer token for subsequent API calls to the issuer component.
+
+### Description of the Functional Interface (WHAT)
+
+The issuer component provides the following functionalities:
+
+- **Use Case Participation**: Retrieve all use case frameworks and the participation status of the acting company.
+- **Certificates**: Get all company certificate requests and their statuses.
+- **Certificate Types**: Obtain the certificate types for which the company can apply.
+- **Credential Overview**: Fetch all outstanding, existing, and inactive credentials.
+- **Owned Credentials**: List all outstanding, existing, and inactive credentials for the user's company.
+- **Credential Creation**: Create various credentials such as BPN, membership, and framework.
+- **Credential Approval/Rejection**: Approve or reject credentials, triggering the creation or revocation process.
+- **Credential Revocation**: Allows the issuer or holder to revoke issued credentials.
+
+### Description of the Physical Interface (HOW)
+
+The RESTful API endpoints for interacting with the issuer component are as follows:
+
+#### Credential Information Retrieval
+
+- `GET /api/issuer/useCaseParticipation`
+- `GET /api/issuer/certificates`
+- `GET /api/issuer/certificateTypes`
+- `GET /api/issuer`
+- `GET /api/issuer/owned-credentials`
+- `GET /api/credential/{credentialId}`
+- `GET /api/credential/documents/{documentId}`
+
+#### Credential Management
+
+- `POST /api/issuer/bpn`
+- `POST /api/issuer/membership`
+- `POST /api/issuer/framework`
+- `PUT /api/issuer/{credentialId}/approval`
+- `PUT /api/issuer/{credentialId}/reject`
+
+#### Credential Revocation
+
+- `POST /api/revocation/issuer/credentials/{credentialId}`
+- `POST /api/revocation/credentials/{credentialId}`
+
+These endpoints must be exposed by the issuer component and accessible through HTTPS, ensuring secure communication.
+
+### Authorization Details (Keycloak Technical User)
+
+The issuer component integrates with Keycloak for fine-grained access control. Each endpoint is protected by specific roles and permissions assigned to technical users within Keycloak. Clients must possess the necessary roles to interact with the issuer component.
+
+- **`revoke_credentials_issuer`**: Required for revocation endpoints (POST) by issuers.
+- **`revoke_credential`**: Required for revocation endpoints (POST) by holders.
+- **Permissions For Other Endpoints**: Specific roles must be created and assigned to users for managing credentials (GET, POST, PUT).
+
+For each action taken through the interface, a corresponding Keycloak role must be mapped and validated to ensure proper authorization and to prevent unauthorized access or actions.
+
+### Endpoint Responses
+
+Each endpoint should provide appropriate HTTP status codes as feedback to the user for the action taken. These include:
+
+- `200 OK`: Successful operation.
+- `400 Bad Request`: Invalid request format or parameters.
+- `401 Unauthorized`: Authentication required or failed.
+- `403 Forbidden`: Insufficient permissions.
+- `404 Not Found`: Resource not found.
+- `500 Internal Server Error`: Unexpected condition encountered.
+
+<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: 2024 Contributors to the Eclipse Foundation
+- Source URL: https://github.com/eclipse-tractusx/portal-assets

docs/user/06. Certificates/04. Credential Revocation.md → docs/user/06. Credential Management/04. Credential Revocation.md

@@ -4,7 +4,14 @@
 
 The credential revocation function allows authorized individuals to revoke issued credentials that are currently active. This action is irreversible and will invalidate the credential, ensuring it is no longer recognized as valid within any transactions.
 
-### How to Revoke a Credential
+For Credential Revocation two scenarios need to get differenciated:
+
+1. Revocation by issuer
+2. Revocation by holder
+
+### Revocation by issuer
+
+#### How to Revoke a Credential
 
 If you have been granted the "revoke_credentials_issuer" permission, you can revoke active credentials via the issuer admin board. Follow the steps below to carry out a revocation:
 
@@ -20,12 +27,43 @@ If you have been granted the "revoke_credentials_issuer" permission, you can rev
 
 4. **Revocation Process**: A loading indicator will appear while the system processes the revocation. Once complete, you will receive a notification indicating the outcome of your action.
 
-### Notifications
+#### Notifications
+
+- **Success**: You will receive a confirmation message stating that the credential has been successfully revoked and is no longer valid.
+- **Error**: If the revocation fails, an error message will be displayed advising you to try again later or contact the site administrator.
+
+#### Important Considerations
+
+- **Irreversible Action**: Revocation is a permanent action. Once a credential is revoked, it cannot be reinstated as valid.
+- **Permission Required**: Only users with the "revoke_credentials_issuer" permission can perform revocations.
+- **Immediate Effect**: The revocation takes effect immediately, and the credential's status will be updated to reflect this change.
+
+### Revocation by holder
+
+As a holder, you have the ability to revoke your own credentials, such as frameworkAgreement or BPN, in case of security concerns or account compromise.
+
+#### How to Revoke a Credential
+
+1. **Log in to your Wallet UI Board.**
+   Access your wallet by logging in with your credentials.
+
+2. **Identify the Credential.**
+   Within the wallet UI, active credentials will have a revocation icon.
+
+3. **Request Revocation.**
+   Click on the revocation icon for the credential you wish to revoke.
+
+4. **Confirm Revocation.**
+   Validate your identity if prompted, and confirm the revocation request.
+
+Once the revocation is successful, the credential will be updated to "INACTIVE" and greyed out.
+
+#### Notifications
 
 - **Success**: You will receive a confirmation message stating that the credential has been successfully revoked and is no longer valid.
 - **Error**: If the revocation fails, an error message will be displayed advising you to try again later or contact the site administrator.
 
-### Important Considerations
+#### Important Considerations
 
 - **Irreversible Action**: Revocation is a permanent action. Once a credential is revoked, it cannot be reinstated as valid.
 - **Permission Required**: Only users with the "revoke_credentials_issuer" permission can perform revocations.