From 5ceba1fb2d64462194b4d2448179e038088e20f0 Mon Sep 17 00:00:00 2001 From: Phil Schneider Date: Wed, 25 Sep 2024 11:19:37 +0200 Subject: [PATCH] docs: add documentation for the new process Refs: #79 --- docs/admin/database/db-view.md | 83 +++++----- .../known-issues-and-limitations.md | 2 +- docs/admin/processes/01. create_wallet.md | 149 ++++++++++++++++++ .../processes/02. create_technical_user.md | 71 +++++++++ .../processes/03. delete_technical_user.md | 51 ++++++ docs/admin/processes/index.md | 27 ++++ src/web/Dim.Web/Controllers/DimController.cs | 3 +- 7 files changed, 345 insertions(+), 41 deletions(-) create mode 100644 docs/admin/processes/01. create_wallet.md create mode 100644 docs/admin/processes/02. create_technical_user.md create mode 100644 docs/admin/processes/03. delete_technical_user.md create mode 100644 docs/admin/processes/index.md diff --git a/docs/admin/database/db-view.md b/docs/admin/database/db-view.md index 881a520..2147341 100644 --- a/docs/admin/database/db-view.md +++ b/docs/admin/database/db-view.md @@ -59,6 +59,8 @@ erDiagram bytea initialization_vector integer encryption_mode uuid process_id FK + uuid operation_id + uuid service_key_id } TENANTS { uuid id PK @@ -67,17 +69,18 @@ erDiagram text did_document_location bool is_issuer uuid process_id FK - uuid sub_account_id - text service_instance_id - text service_binding_name - uuid space_id - uuid dim_instance_id + uuid wallet_id + text token_address + text client_id + uuid operation_id text did_download_url text did - text application_id uuid company_id - text application_key + text base_url uuid operator_id + bytea client_secret + int encryption_mode + bytea initialization_vector } ``` @@ -105,29 +108,30 @@ label (TEXT): The label of the process step type. #### Possible Values -- `CREATE_SUBACCOUNT`: Creates the sub account in sap -- `CREATE_SERVICEMANAGER_BINDINGS`: Creates the service manager binding for the created subaccount -- `ASSIGN_ENTITLEMENTS`: Assigns the entitlements -- `CREATE_SERVICE_INSTANCE`: Creates the service instance -- `CREATE_SERVICE_BINDING`: Creates the service binding for the created service instance -- `SUBSCRIBE_APPLICATION`: Subscribes to the `decentralized-identity-management-app` application -- `CREATE_CLOUD_FOUNDRY_ENVIRONMENT`: Creates the cloud foundry environment -- `CREATE_CLOUD_FOUNDRY_SPACE`: Creates the cloud foundry space for the created environment -- `ADD_SPACE_MANAGER_ROLE`: Adds the space manager role for the created subaccount -- `ADD_SPACE_DEVELOPER_ROLE`: Adds the space developer role for the created subaccount -- `CREATE_DIM_SERVICE_INSTANCE`: Creates the dim instance -- `CREATE_SERVICE_INSTANCE_BINDING`: Creates the binding for to the created dim instance -- `GET_DIM_DETAILS`: Retrieves the dim details from SAP Dim -- `CREATE_APPLICATION`: Creates the application in the wallet -- `CREATE_COMPANY_IDENTITY`: Creates a company identity for the wallet -- `ASSIGN_COMPANY_APPLICATION`: Assigns the company identity to the application -- `CREATE_STATUS_LIST`: Creates a statuslist for a company -- `SEND_CALLBACK`: Sends the callback to the portal to transmit the data of the created wallet and did -- `CREATE_TECHNICAL_USER`: Creates a new technical user for a wallet -- `GET_TECHNICAL_USER_DATA`: Retrieves the technical user data from the SAP Dim -- `SEND_TECHNICAL_USER_CREATION_CALLBACK`: Sends the technical user data back to the portal -- `DELETE_TECHNICAL_USER`: Deletes the technical user from the database and from the SAP Dim -- `SEND_TECHNICAL_USER_DELETION_CALLBACK`: Sends a status to the portal if the deletion was successful +- `CREATE_WALLET`: Sends the wallet creation process to the SAP Dim +- `CHECK_OPERATION`: Checks the wallet creation operation to be completed +- `GET_COMPANY`: Gets the company and wallet information +- `GET_DID_DOCUMENT`: Gets the did document and the did for the wallet +- `CREATE_STATUS_LIST`: Only if the tenant is an issuer - Creates the status list +- `SEND_CALLBACK`: Sends the wallet data back to the portal backend +- `RETRIGGER_CREATE_WALLET`: Retriggers the `CREATE_WALLET` step +- `RETRIGGER_CHECK_OPERATION`: Retriggers the `CHECK_OPERATION` step +- `RETRIGGER_GET_COMPANY`: Retriggers the `GET_COMPANY` step +- `RETRIGGER_GET_DID_DOCUMENT`: Retriggers the `GET_DID_DOCUMENT` step +- `RETRIGGER_CREATE_STATUS_LIST`: Retriggers the `CREATE_STATUS_LIST` step +- `RETRIGGER_SEND_CALLBACK`: Retriggers the `SEND_CALLBACK` step +- `CREATE_TECHNICAL_USER`: Sends a technical user creation request to the SAP Dim +- `GET_TECHNICAL_USER_DATA`: Gets the technical user data (clientId, clientSecret and tokenUrl) +- `GET_TECHNICAL_USER_SERVICE_KEY`: Gets the service key id which is needed to delete the technical user later on +- `SEND_TECHNICAL_USER_CREATION_CALLBACK`: Sends all information of the technical user to the portal backend +- `RETRIGGER_CREATE_TECHNICAL_USER`: Retriggers the `CREATE_TECHNICAL_USER` step +- `RETRIGGER_GET_TECHNICAL_USER_DATA`: Retriggers the `GET_TECHNICAL_USER_DATA` step +- `RETRIGGER_GET_TECHNICAL_USER_SERVICE_KEY`: Retriggers the `GET_TECHNICAL_USER_SERVICE_KEY` step +- `RETRIGGER_SEND_TECHNICAL_USER_CREATION_CALLBACK`: Retriggers the `SEND_TECHNICAL_USER_CREATION_CALLBACK` step +- `DELETE_TECHNICAL_USER`: Deletes the technical user from the SAP Dim +- `SEND_TECHNICAL_USER_DELETION_CALLBACK`: Sends a status of whether the deletion was successful to the portal and deletes the technical user from the database +- `RETRIGGER_DELETE_TECHNICAL_USER`: Retriggers the `DELETE_TECHNICAL_USER` step +- `RETRIGGER_SEND_TECHNICAL_USER_DELETION_CALLBACK`: Retriggers the `SEND_TECHNICAL_USER_DELETION_CALLBACK` step ### PROCESS_STEPS @@ -168,6 +172,8 @@ client_secret (BYTEA): The encrypted client secret initialization_vector (BYTEA): The used initialization vector which is needed for decrypting the secret encryption_mode (INTEGER): The used encryption mode for the secret process_id (UUID): A unique identifier for the process. This is a foreign key referencing id in the PROCESS table +operation_id (UUID): A unique identifier of the operation which is created on SAP Dim side +service_key_id (UUID): A unique identifier of the technical user on SAP Dim side ### TENANTS @@ -177,17 +183,18 @@ bpn (TEXT): Bpn of the company must be unique in combination with the name did_document_location (TEXT): The location of the did document (url) is_issuer (BOOL): Defines if the requesting tenant is an issuer process_id (UUID): A unique identifier for the process. This is a foreign key referencing id in the PROCESS table -sub_account_id (UUID): A unique identifier of the sub account in the SAP DIM -service_instance_id (TEXT): A unique identifier of the service instance id in the SAP DIM -service_binding_name (TEXT): The service binding name in the SAP DIM -space_id (UUID): A unique identifier of the space id in the SAP DIM -dim_instance_id (UUID): A unique identifier of the dim instance in the SAP DIM +operator_id (UUID): A unique identifier of the operator which is used for the wallet creation did_download_url (TEXT): The url of the did document. did (TEXT): The did of the wallet -application_id (TEXT): A unique identifier of the application in the SAP DIM +base_url (TEXT): The address of the wallet +token_address (TEXT): The address for the authentication of the wallet +client_id (TEXT): The client id which is needed for authentication +client_secret (BYTEA): The encrypted client secret +initialization_vector (BYTEA): The used initialization vector which is needed for decrypting the secret +encryption_mode (INTEGER): The used encryption mode for the secret company_id (UUID): A unique identifier of the company in the SAP DIM -application_key (TEXT): The key of the application in the SAP DIM -operator_id (UUID): A unique identifier of the operator which is used for the wallet creation +operation_id (UUID): A unique identifier of the operation which is created in the SAP DIM +wallet_id (UUID): A unique identifier of the wallet in the SAP DIM ### Enum Value Tables diff --git a/docs/admin/known-knowns/known-issues-and-limitations.md b/docs/admin/known-knowns/known-issues-and-limitations.md index 153d012..3fc991d 100644 --- a/docs/admin/known-knowns/known-issues-and-limitations.md +++ b/docs/admin/known-knowns/known-issues-and-limitations.md @@ -1,6 +1,6 @@ # Known Issues and Limitations -- The creation of the CF Space currently is only possible by using a personal SAP account. This will likely be adjusted to a technical user in the future. For now, the configuration needs to be made with an personal user. +There are currently no known issues or limitations. ## NOTICE diff --git a/docs/admin/processes/01. create_wallet.md b/docs/admin/processes/01. create_wallet.md new file mode 100644 index 0000000..749ec64 --- /dev/null +++ b/docs/admin/processes/01. create_wallet.md @@ -0,0 +1,149 @@ +# Create Wallet Process + +## Summary + +The create wallet process handles the creation of a wallet. The process steps are the following: + +```mermaid +flowchart TD + A((Start wallet creation process)) + B(CREATE_WALLET) + C(CHECK_OPERATION) + D(GET_COMPANY) + E(GET_DID_DOCUMENT) + F(CREATE_STATUS_LIST) + G(SEND_CALLBACK) + H((Process completed)) + I(RETRIGGER_CREATE_WALLET) + J(RETRIGGER_CHECK_OPERATION) + K(RETRIGGER_GET_COMPANY) + L(RETRIGGER_GET_DID_DOCUMENT) + M(RETRIGGER_CREATE_STATUS_LIST) + N(RETRIGGER_SEND_CALLBACK) + A--> B + B -->|Success| C + C -->|Success| D + D -->|Success| E + E -->|Success, if not issuer| G + E -->|Success, if issuer| F + F -->|Success| G + G --> H + B-->|Error| I + C-->|Error| J + D-->|Error| K + E-->|Error| L + F-->|Error| M + G-->|Error| N + I--> B + J--> C + K--> D + L--> E + M--> F + N--> G +``` + +## External dependencies + +The process worker communicates with the SAP Dim to create the wallet. It further more communicates with the portal backend to return the wallet data. + +## Process Steps + +### CREATE_WALLET + +The process step `CREATE_WALLET` is automatically triggered from the process worker. It sends a request to create the wallet to the SAP Dim. + +### CHECK_OPERATION + +The process step `CHECK_OPERATION` is automatically triggered from the process worker. It requests the status of the operation which is created in the `CREATE_WALLET` step. If the status is `completed` it takes the data of the wallet and saves it in the database. + +### GET_COMPANY + +The process step `GET_COMPANY` is automatically triggered from the process worker. It retrieves Did download url and company id and saves it to the database. + +Example did document: + +```json +{ + "@context": + [ + "https://www.w3.org/ns/did/v1", + "https://w3id.org/security/suites/jws-2020/v1", + ], + "id": "did:web:example.org:api:did:BPNL0000001TEST", + "service": + [ + { + "type": "CredentialService", + "serviceEndpoint": "https://dis-agent-prod.eu10.dim.cloud.sap/api/v1.0.0/iatp", + "id": "did:web:example.org:api:did:BPNL0000001TEST#CredentialService", + }, + ], + "verificationMethod": + [ + { + "id": "did:web:example.org:api:did:BPNL0000001TEST#keys-1c55236c-f974-4c7e-bdd3-b667d0c2e1a4", + "type": "JsonWebKey2020", + "controller": "did:web:example.org:api:did:BPNL0000001TEST", + "publicKeyJwk": + { + "kty": "EC", + "crv": "secp256k1", + "x": "kxZJ_7xWDmRm6VX11Oi7JYYzicfme53whduBhpJSM_c", + "y": "p47wM71fs0rBLM6la9eat6f1sIMtzbqOON0PG393rso", + }, + }, + { + "id": "did:web:example.org:api:did:BPNL0000001TEST#keys-2a5052ac-dac7-47b4-842a-786efe60e8cb", + "type": "JsonWebKey2020", + "controller": "did:web:example.org:api:staticdata:did:BPNL0000001TEST", + "publicKeyJwk": + { + "kty": "EC", + "crv": "secp256k1", + "x": "AUHunkMYUecQfgrJUbksH83mRpcqHdhAdMEBP-Z0lTQ", + "y": "68HOmlhB1gdfggV9AvMlbe4yfI-Ce6brV-ge6z-7shg", + }, + }, + ], + "authentication": + [ + "did:web:example.org:api:did:BPNL0000001TEST#keys-1c55236c-f974-4c7e-bdd3-b667d0c2e1a4", + ], + "assertionMethod": + [ + "did:web:example.org:api:did:BPNL0000001TEST#keys-2a5052ac-dac7-47b4-842a-786efe60e8cb", + ], + "keyAgreement": [], +} +``` + +### GET_DID_DOCUMENT + +The process step `GET_DID_DOCUMENT` is automatically triggered from the process worker. It retrieves the did and saves it to the database. + +### CREATE_STATUS_LIST + +The process step `CREATE_STATUS_LIST` is automatically triggered from the process worker if the wallet is created for the issuer. It creates a status list. + +### SEND_CALLBACK + +The process step `SEND_CALLBACK` is automatically triggered from the process worker. It sends the wallet data, did and the did document to the portal backend. + +## Retrigger + +| Step Name | Retrigger Step | Retrigger Endpoint | +| ------------------ | ---------------------------- | ------------------------------------------------------------------------------------------- | +| CREATE_WALLET | RETRIGGER_CREATE_WALLET | api/dim/process/wallet/{processId}/retrigger?processStepTypeId=RETRIGGER_CREATE_WALLET | +| CHECK_OPERATION | RETRIGGER_CHECK_OPERATION | api/dim/process/wallet/{processId}/retrigger?processStepTypeId=RETRIGGER_CHECK_OPERATION | +| GET_COMPANY | RETRIGGER_GET_COMPANY | api/dim/process/wallet/{processId}/retrigger?processStepTypeId=RETRIGGER_GET_COMPANY | +| GET_DID_DOCUMENT | RETRIGGER_GET_DID_DOCUMENT | api/dim/process/wallet/{processId}/retrigger?processStepTypeId=RETRIGGER_GET_DID_DOCUMENT | +| CREATE_STATUS_LIST | RETRIGGER_CREATE_STATUS_LIST | api/dim/process/wallet/{processId}/retrigger?processStepTypeId=RETRIGGER_CREATE_STATUS_LIST | +| SEND_CALLBACK | RETRIGGER_SEND_CALLBACK | api/dim/process/wallet/{processId}/retrigger?processStepTypeId=RETRIGGER_SEND_CALLBACK | + +## 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 SAP SE or an SAP affiliate company, BMW Group AG and ssi-dim-middle-layer contributors +- Source URL: https://github.com/SAP/ssi-dim-middle-layer diff --git a/docs/admin/processes/02. create_technical_user.md b/docs/admin/processes/02. create_technical_user.md new file mode 100644 index 0000000..ab5181e --- /dev/null +++ b/docs/admin/processes/02. create_technical_user.md @@ -0,0 +1,71 @@ +# Create Technical User Process + +## Summary + +The create technical user process handles the creation of a technical user. The process steps are the following: + +```mermaid +flowchart TD + A((Start technical user creation process)) + B(CREATE_TECHNICAL_USER) + C(GET_TECHNICAL_USER_DATA) + D(GET_TECHNICAL_USER_SERVICE_KEY) + E(SEND_TECHNICAL_USER_CREATION_CALLBACK) + F(RETRIGGER_CREATE_TECHNICAL_USER) + G(RETRIGGER_GET_TECHNICAL_USER_DATA) + H(RETRIGGER_GET_TECHNICAL_USER_SERVICE_KEY) + I(RETRIGGER_SEND_TECHNICAL_USER_CREATION_CALLBACK) + J((Process completed)) + A --> B + B -->|Success| C + C -->|Success| D + D -->|Success| E + E -->|Success| J + B-->|Error| F + C-->|Error| G + D-->|Error| H + E-->|Error| I + F--> B + G--> C + H--> D + I--> E +``` + +## External dependencies + +The process worker communicates with the SAP Dim to create the technical user. It further more communicates with the portal backend to return the technical user data. + +## Process Steps + +### CREATE_TECHNICAL_USER + +The process step `CREATE_TECHNICAL_USER` is automatically triggered from the process worker. It sends a request to create the technical user to the SAP Dim. + +### GET_TECHNICAL_USER_DATA + +The process step `GET_TECHNICAL_USER_DATA` is automatically triggered from the process worker. It requests the status of the operation which is created in the `CREATE_TECHNICAL_USER` step. If the status is `completed` it takes the data of the technical user and saves it in the database. + +### GET_TECHNICAL_USER_SERVICE_KEY + +The process step `GET_TECHNICAL_USER_SERVICE_KEY` is automatically triggered from the process worker. It retrieves the service key id which is the unique identifier of the technical user in the SAP Dim. + +### SEND_TECHNICAL_USER_CREATION_CALLBACK + +The process step `SEND_TECHNICAL_USER_CREATION_CALLBACK` is automatically triggered from the process worker. It sends the technical user details to the portal backend. + +## Retrigger + +| Step Name | Retrigger Step | Retrigger Endpoint | +| ------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| CREATE_TECHNICAL_USER | RETRIGGER_CREATE_TECHNICAL_USER | api/dim/process/technicalUser/{processId}/retrigger?processStepTypeId=RETRIGGER_CREATE_TECHNICAL_USER | +| GET_TECHNICAL_USER_DATA | RETRIGGER_GET_TECHNICAL_USER_DATA | api/dim/process/technicalUser/{processId}/retrigger?processStepTypeId=RETRIGGER_GET_TECHNICAL_USER_DATA | +| GET_TECHNICAL_USER_SERVICE_KEY | RETRIGGER_GET_TECHNICAL_USER_SERVICE_KEY | api/dim/process/technicalUser/{processId}/retrigger?processStepTypeId=RETRIGGER_GET_TECHNICAL_USER_SERVICE_KEY | +| SEND_TECHNICAL_USER_CREATION_CALLBACK | RETRIGGER_SEND_TECHNICAL_USER_CREATION_CALLBACK | api/dim/process/technicalUser/{processId}/retrigger?processStepTypeId=RETRIGGER_SEND_TECHNICAL_USER_CREATION_CALLBACK | + +## 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 SAP SE or an SAP affiliate company, BMW Group AG and ssi-dim-middle-layer contributors +- Source URL: https://github.com/SAP/ssi-dim-middle-layer diff --git a/docs/admin/processes/03. delete_technical_user.md b/docs/admin/processes/03. delete_technical_user.md new file mode 100644 index 0000000..394c47a --- /dev/null +++ b/docs/admin/processes/03. delete_technical_user.md @@ -0,0 +1,51 @@ +# Delete Technical User Process + +## Summary + +The delete technical user process handles the deletion of an technical user. The process steps are the following: + +```mermaid +flowchart TD + A((Start technical user deletion process)) + B(DELETE_TECHNICAL_USER) + C(SEND_TECHNICAL_USER_DELETION_CALLBACK) + D(RETRIGGER_DELETE_TECHNICAL_USER) + E(RETRIGGER_SEND_TECHNICAL_USER_DELETION_CALLBACK) + F((Process completed)) + A --> B + B -->|Success| C + C -->|Success| F + B-->|Error| D(RETRIGGER_DELETE_TECHNICAL_USER) + C-->|Error| E(RETRIGGER_SEND_TECHNICAL_USER_DELETION_CALLBACK) + D--> B + E--> C +``` + +## External dependencies + +The process worker communicates with the SAP Dim to delete the technical user. It further more communicates with the portal backend to return the status of the deletion. + +## Process Steps + +### DELETE_TECHNICAL_USER + +The process step `DELETE_TECHNICAL_USER` is automatically triggered from the process worker. It sends a request to delete the technical user from the SAP Dim. + +### SEND_TECHNICAL_USER_DELETION_CALLBACK + +The process step `SEND_TECHNICAL_USER_DELETION_CALLBACK` is automatically triggered from the process worker. It deletes the technical user from the dim database and sends a status update to the portal backend. + +## Retrigger + +| Step Name | Retrigger Step | Retrigger Endpoint | +| ------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| DELETE_TECHNICAL_USER | RETRIGGER_DELETE_TECHNICAL_USER | api/dim/process/technicalUser/{processId}/retrigger?processStepTypeId=RETRIGGER_DELETE_TECHNICAL_USER | +| SEND_TECHNICAL_USER_DELETION_CALLBACK | RETRIGGER_SEND_TECHNICAL_USER_DELETION_CALLBACK | api/dim/process/technicalUser/{processId}/retrigger?processStepTypeId=RETRIGGER_SEND_TECHNICAL_USER_DELETION_CALLBACK | + +## 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 SAP SE or an SAP affiliate company, BMW Group AG and ssi-dim-middle-layer contributors +- Source URL: https://github.com/SAP/ssi-dim-middle-layer diff --git a/docs/admin/processes/index.md b/docs/admin/processes/index.md new file mode 100644 index 0000000..9dd85ab --- /dev/null +++ b/docs/admin/processes/index.md @@ -0,0 +1,27 @@ +# Summary + +The main process worker project is the `Processes.Worker` which runs all the processes. It therefor looks up `process_steps` in status `TODO` and their respective `processes` and executes those. + +## Processes + +The process worker supports the following processes: + +- [CreateWallet](../processes/01.%20create_wallet.md) - handles the creation of wallets +- [CreateTechnicalUser](../processes/02.%20create_technical_user.md) - handles the creation of technical user +- [DeleteTechnicalUser](../processes/03.%20delete_technical_user.md) - handles the deletion of technical user + +## Retriggering + +The process has a logic to retrigger failing steps. For this a retrigger step is created which can be triggered via an api call to retrigger the step. This logic is implemented separately for each process. In general the retriggering of a step is possible if for example external services are not available. The retrigger logic for each process can be found in the process file. + +## Configuration + +The configuration of the process worker such as the interval of execution or encryption configuration is made via the helm chart. + +## 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 SAP SE or an SAP affiliate company, BMW Group AG and ssi-dim-middle-layer contributors +- Source URL: https://github.com/SAP/ssi-dim-middle-layer diff --git a/src/web/Dim.Web/Controllers/DimController.cs b/src/web/Dim.Web/Controllers/DimController.cs index 7ffdb68..642a32a 100644 --- a/src/web/Dim.Web/Controllers/DimController.cs +++ b/src/web/Dim.Web/Controllers/DimController.cs @@ -78,8 +78,7 @@ public static RouteGroupBuilder MapDimApi(this RouteGroupBuilder group) .WithSwaggerDescription("Deletes a technical user with the given name of the given bpn", "Example: Post: api/dim/technical-user/{bpn}/delete", "bpn of the company") - // .RequireAuthorization(r => r.RequireRole("delete_technical_user")) - .AllowAnonymous() + .RequireAuthorization(r => r.RequireRole("delete_technical_user")) .Produces(StatusCodes.Status200OK, contentType: Constants.JsonContentType); dim.MapGet("process/setup", (