From a27739c0723b8c87afd47368d0080a864faf06bf Mon Sep 17 00:00:00 2001 From: Phil Schneider Date: Wed, 31 Jul 2024 11:43:21 +0200 Subject: [PATCH 1/3] docs: add documentation Refs: #63 #60 --- README.md | 4 + docs/admin/database/db-view.md | 206 +++++++++++ .../dev-process/Dev-flow_deploy-dev-env.md | 28 ++ .../admin/dev-process/Enumeration Handling.md | 39 +++ docs/admin/dev-process/How to contribute.md | 109 ++++++ docs/admin/identity-access-management.md | 23 ++ .../known-issues-and-limitations.md | 11 + docs/admin/release-process/Release Process.md | 88 +++++ docs/admin/tractus-x-portal.md | 11 + docs/api/Dim.Web.postman_collection.json | 321 ++++++++++++++++++ docs/architecture/Architecture Constraints.md | 45 +++ docs/architecture/Context and scope.md | 19 ++ docs/architecture/Development Concept.md | 143 ++++++++ docs/architecture/Whitebox Overall System.md | 44 +++ docs/architecture/operational-concept.md | 35 ++ src/web/Dim.Web/Controllers/DimController.cs | 8 +- 16 files changed, 1130 insertions(+), 4 deletions(-) create mode 100644 docs/admin/database/db-view.md create mode 100644 docs/admin/dev-process/Dev-flow_deploy-dev-env.md create mode 100644 docs/admin/dev-process/Enumeration Handling.md create mode 100644 docs/admin/dev-process/How to contribute.md create mode 100644 docs/admin/identity-access-management.md create mode 100644 docs/admin/known-knowns/known-issues-and-limitations.md create mode 100644 docs/admin/release-process/Release Process.md create mode 100644 docs/admin/tractus-x-portal.md create mode 100644 docs/api/Dim.Web.postman_collection.json create mode 100644 docs/architecture/Architecture Constraints.md create mode 100644 docs/architecture/Context and scope.md create mode 100644 docs/architecture/Development Concept.md create mode 100644 docs/architecture/Whitebox Overall System.md create mode 100644 docs/architecture/operational-concept.md diff --git a/README.md b/README.md index 58989c9..a5c4c14 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,10 @@ This project is open to feature requests/suggestions, bug reports etc. via [GitH ## Security / Disclosure If you find any bug that may be a security problem, please follow our instructions at [in our security policy](https://github.com/SAP/ssi-dim-middle-layer/security/policy) on how to report it. Please do not create GitHub issues for security-related doubts or problems. +## Known Issues and Limitations + +See [Known Knowns](/docs/admin/known-knowns/known-issues-and-limitations.md). + ## Code of Conduct We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](https://github.com/SAP/.github/blob/main/CODE_OF_CONDUCT.md) at all times. diff --git a/docs/admin/database/db-view.md b/docs/admin/database/db-view.md new file mode 100644 index 0000000..881a520 --- /dev/null +++ b/docs/admin/database/db-view.md @@ -0,0 +1,206 @@ +# Database View + +- [Database View](#database-view) + - [Database Overview](#database-overview) + - [Database Structure](#database-structure) + - [PROCESS\_STEP\_STATUSES](#process_step_statuses) + - [Possible Values](#possible-values) + - [PROCESS\_STEP\_TYPES](#process_step_types) + - [Possible Values](#possible-values-1) + - [PROCESS\_STEPS](#process_steps) + - [PROCESS\_TYPES](#process_types) + - [Possible Values](#possible-values-2) + - [PROCESSES](#processes) + - [TECHNICAL\_USER](#technical_user) + - [TENANTS](#tenants) + - [Enum Value Tables](#enum-value-tables) + - [Process Handling](#process-handling) + - [NOTICE](#notice) + +## Database Overview + +```mermaid +erDiagram + PROCESS_STEP_STATUSES { + integer id PK + text label PK + } + PROCESS_STEP_TYPES { + integer id PK + text label + } + PROCESS_STEPS { + uuid id PK + integer process_step_type_id FK + integer process_step_status_id FK + uuid process_id FK + timestamp date_created + timestamp date_last_changed + text message + } + PROCESS_TYPES { + integer id PK + text label + } + PROCESSES { + uuid id PK + integer process_type_id FK + timestamp lock_expiry_date + uuid version + } + TECHNICAL_USER { + uuid id PK + uuid tenant_id FK + uuid external_id + text technical_user_name + text token_address + text client_id + bytea client_secret + bytea initialization_vector + integer encryption_mode + uuid process_id FK + } + TENANTS { + uuid id PK + text company_name + text bpn + 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 + text did_download_url + text did + text application_id + uuid company_id + text application_key + uuid operator_id + } +``` + +## Database Structure + +The database is organized into several key tables, each serving a specific purpose: + +### PROCESS_STEP_STATUSES + +id (INTEGER): A unique identifier for the process step status. This is the primary key of the table. +label (TEXT): The label of the process step status. + +#### Possible Values + +- `TODO`: The process step is still to be executed. +- `DONE`: The process step was already executed successfully. +- `SKIPPED`: The execution of the process step was skipped. +- `FAILED`: The process step execution failed due to an error. +- `DUPLICATE`: The process step did already exist. + +### PROCESS_STEP_TYPES + +id (INTEGER): A unique identifier for the process step type. This is the primary key of the table. +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 + +### PROCESS_STEPS + +id (UUID): A unique identifier for the process step. This is the primary key of the table. +process_step_type_id (INTEGER): A foreign key referencing id in the PROCESS_STEP_TYPES table. +process_step_status_id (INTEGER): A foreign key referencing id in the PROCESS_STEP_STATUSES table. +process_id (UUID): A foreign key referencing id in the PROCESSES table. +date_created (TIMESTAMP): The timestamp when the process step was created. +date_last_changed (TIMESTAMP): The timestamp when the process step was last changed. +message (TEXT): A message associated with the process step. + +### PROCESS_TYPES + +id (INTEGER): A unique identifier for the process type. This is the primary key of the table. +label (TEXT): The label of the process type. + +#### Possible Values + +- `SETUP_DIM`: Process to create wallets. +- `TECHNICAL_USER`: Process to create and delete technical users. + +### PROCESSES + +id (UUID): A unique identifier for the process. This is the primary key of the table. +process_type_id (INTEGER): A foreign key referencing id in the PROCESS_TYPES table. +lock_expiry_date (TIMESTAMP): The lock expiry date of the process. +version (UUID): The version of the process. + +### TECHNICAL_USER + +id (UUID): A unique identifier for the technical user. This is the primary key of the table +tenant_id (UUID): A unique identifier for the tenant. This is a foreign key referencing id in the TENANT table +external_id (UUID): the id of the technical user in the dim +technical_user_name (TEXT): The name of the technical user +token_address (TEXT): The address for the authentication of the technical user +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 +process_id (UUID): A unique identifier for the process. This is a foreign key referencing id in the PROCESS table + +### TENANTS + +id (UUID): A unique identifier for the technical user. This is the primary key of the table +company_name (TEXT): Name of the company must be unique in combination with the bpn +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 +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 +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 + +### Enum Value Tables + +`process_step_statuses`, `process_step_types`, `process_steps`, `process_types` are tables designed to store enum values. They contain an id and label, derived from the backend enums. + +### Process Handling + +The tables `processes`, `process_steps` are used for the processing of the wallet creation and technical user management. + +## 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/dev-process/Dev-flow_deploy-dev-env.md b/docs/admin/dev-process/Dev-flow_deploy-dev-env.md new file mode 100644 index 0000000..e6c5aa7 --- /dev/null +++ b/docs/admin/dev-process/Dev-flow_deploy-dev-env.md @@ -0,0 +1,28 @@ +# Dev flow with deployment to dev environment + +```mermaid +flowchart LR + subgraph local + D(Developer) + end + subgraph eclipse-tractusx + direction LR + D -- PR* to main*--> SDML(ssi-dim-middle-layer**) + click SCI "https://github.com/eclipse-tractusx/ssi-dim-middle-layer" + end + subgraph Argo CD - sync to k8s cluster + SCI -- auto-sync --> A(Argo CD dev) + end +``` + +Note\* Every pull request (PR) requires at least one approving review by a committer + +Note\*\* Unit tests and code analysis checks run at pull request + +## 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/dev-process/Enumeration Handling.md b/docs/admin/dev-process/Enumeration Handling.md new file mode 100644 index 0000000..2207eb2 --- /dev/null +++ b/docs/admin/dev-process/Enumeration Handling.md @@ -0,0 +1,39 @@ +# Enumeration + +Enum or enumeration are used for data type consisting of named values like elements, status workflow, types, etc., that represent integral constants. Enums are non-transactional (so called static data) which can only get changed in a new application version. Changes in the operation mode of an application are not allowed since this will result into possible system breaks. + +List of used enums in the ssi dim middle layer application + +- process_step_statuses +- process_step_types +- process_steps +- process_types + +## Add Enums + +New enums can get added easily be enhancing the enumeration table (via the seeding data). With the next deployment; the new enum is getting auto deployed to the respective env. +Since enums have an enhanced impact on the system functionality; it is mandatorily needed to test (FE wise) the impacted screens / flows before releasing new enums. It is likely that the enum has an enhanced impact on the user journey / flow and break the system if not well tested. + +## Change Enums + +Change of enums (labels) is possible but need to be done carefully and only if necessarily needed. +In the case a change is getting executed; the system configuration / appsettings / env. variables need to get checked to ensure that those don't refer to the enum which is getting changed/ updated. + +## Delete Enums + +Deletion of enums have following impacts + +- Seeding data update needed (likely data need to get deleted / changed) +- Data inside the database in the different running environments need to get updated +- User flow process impacted +- Business logic impacted + +**It is not recommended to delete enums.** + +## 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/dev-process/How to contribute.md b/docs/admin/dev-process/How to contribute.md new file mode 100644 index 0000000..2dbaf04 --- /dev/null +++ b/docs/admin/dev-process/How to contribute.md @@ -0,0 +1,109 @@ +# Contribution details + +To contribute to the SSI DIM Middle Layer as part of the open source community, please read the details defined below. +Besides a generic "how to", some commit and pull request (PR) guidelines are defined to ensure readability and make newly created PRs easier to review. Additionally, changelogs can get validated as well as written with more ease. Moreover, similar patterns are in use across the contributor community. + +**Content**: + +- [Commit How To](#how-to-contribute) +- [Commits, branches and pull requests guidelines](#commits-branches-and-pull-requests-guidelines) + +## How To Contribute + +### 1 Create a fork + +[Create a fork of the respective repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo). + +### 2 Fork setup + +Setup your fork by entering a name and make sure that you unselect the "main branch only" selection, in case the upstream repository maintains release branches besides the main branch. + +Click "Create fork". + +### 3 Commit + +With the newly created fork, you can now start to contribute. Create a new branch in your own fork and start to implement the planned changes or new features. +When the implementation is ready, create a PR against the upstream repository. + +The PR will get reviewed by the repository owners/official committers. +As part of the PR review, checks will run automatically, and unit tests (if configured) will get executed. The PR owner is responsible to check the results and fix possible findings. + +## Commits, branches and pull requests guidelines + +### Commits and branches + +The suggestion is to use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). + +Here are some examples: + +#### Feature branch + +```mermaid +%%{init: { 'logLevel': 'debug', 'theme': 'base' } }%% +gitGraph + commit id: "chore: initial commit" + branch feature/feature1 order: 2 + commit id:"feat(function): add feature1" + commit id:"feat(function): enable feature1" + checkout main + merge feature/feature1 +``` + +#### Bugfix branch + +```mermaid +%%{init: { 'logLevel': 'debug', 'theme': 'base' } }%% +gitGraph + commit id: "build(v0.1.0): merge in main" + branch bug/bug1 order: 2 + commit id: "fix(function): change bug" + checkout bug/bug1 + commit id:"fix(function): refactor bug" + checkout main + merge bug/bug1 +``` + +#### Release branch + +```mermaid +%%{init: { 'logLevel': 'debug', 'theme': 'base' } }%% +gitGraph + commit id: "build(v0.1.0): merge in main" + branch release/v1.0.0 order: 2 + commit id: "build(v1.0.0): bump version, changelog..." tag: "v1.0.0" + checkout main + merge release/v1.0.0 +``` + +#### Hotfix branch + +```mermaid +%%{init: { 'logLevel': 'debug', 'theme': 'base' } }%% +gitGraph + commit id: "release: v1.0.0" + branch release/v1.0.0 order: 2 + commit id: "build(v1.0.0): bump version, changelog..." tag: "v1.0.0" + checkout main + merge release/v1.0.0 + checkout release/v1.0.0 + branch hotfix/v1.0.1 order: 3 + checkout hotfix/v1.0.1 + commit id: "hotfix(v1.0.1): bump version, changelog..." tag: "v1.0.1" +``` + +### PR title + +The suggested naming convention is '{type}{(function)}: {short summary}'. + +### PR description + +Add details to the change, fix or feature in the PR description. +What was changed, why was it changed (e.g. which issue was fixed or which requirement was implemented), and how was it changed. + +## 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/identity-access-management.md b/docs/admin/identity-access-management.md new file mode 100644 index 0000000..d6ee80f --- /dev/null +++ b/docs/admin/identity-access-management.md @@ -0,0 +1,23 @@ +# Identity Access Management + +## Role concept + +The endpoints of the SSI Dim Middle Layer can only be used with an authenticated user. To be able to authorize the user, he needs to have the configured Audience which is set in the appsetting under `JWTBEAREROPTIONS__TOKENVALIDATIONPARAMETERS__VALIDAUDIENCE. The configured Audience **must** be added as a client in the idp. + +The following roles do exist and need to be exist in the Client that is configured as the valid audience: + +| Role | Endpoint | +|-----------------------|------------------------------------------------------| +| setup_wallet | POST: api/dim/setup-dim & POST: api/dim/setup-issuer | +| view_status_list | GET: api/dim/status-list/{bpn} | +| create_status_list | POST: api/dim/status-list/{bpn} | +| create_technical_user | POST: api/dim/technical-user/{bpn} | +| delete_technical_user | POST: api/dim/technical-user/{bpn}/delete | + +## 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/known-knowns/known-issues-and-limitations.md b/docs/admin/known-knowns/known-issues-and-limitations.md new file mode 100644 index 0000000..153d012 --- /dev/null +++ b/docs/admin/known-knowns/known-issues-and-limitations.md @@ -0,0 +1,11 @@ +# 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. + +## 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/release-process/Release Process.md b/docs/admin/release-process/Release Process.md new file mode 100644 index 0000000..2c664bb --- /dev/null +++ b/docs/admin/release-process/Release Process.md @@ -0,0 +1,88 @@ +# Release Process + +The release process for a new version can roughly be divided into the following steps: + +- [Release Process](#release-process) + - [Preparations on the release branch](#preparations-on-the-release-branch) + - [1. Aggregate migrations](#1-aggregate-migrations) + - [2. Version bump](#2-version-bump) + - [3. Update README (on chart level)](#3-update-readme-on-chart-level) + - [Update CHANGELOG.md](#update-changelogmd) + - [Merge release branch](#merge-release-branch) + - [NOTICE](#notice) + +The process builds on the [Development Flow](../dev-process/Dev-flow_git-diagram.md) which, usually, takes place within forks and leads to merged pull requests in the repositories of the eclipse-tractusx organization. + +For assigning and incrementing **version** numbers [Semantic Versioning](https://semver.org) is followed. + +## Preparations on the release branch + +Checking out from the main branch a release branch (release/{to be released version} e.g. release/v1.2.0). +On the release branch the following steps are executed: + +### 1. Aggregate migrations + +Migrations should be **aggregated in the case of releasing a new version**, in order to not release the entire history of migrations which accumulate during the development process. + +Once a version has been released, migrations **mustn't be aggregated** in order to ensure upgradeability this also applies to **hotfixes**. +Be aware that migrations coming release branches for release candidates or from hotfix branches, will **need to be incorporated into main**. + +### 2. Version bump + +The version needs to be updated in the `src` directory within the 'Directory.Build.props' file. + +Also, bump the chart and app version in the [Chart.yaml](../../../charts/dim/Chart.yaml) and the version of the images in the [values.yaml](../../../charts/dim/values.yaml). + +_Consortia relevant: Update the version of the targetRevision tag in the [argocd-app-templates](../../../consortia/argocd-app-templates/), used for consortia-environments._ + +Example for commit message: + +_build: bump version for vx.x.x_ + +### 3. Update README (on chart level) + +Use [helm-docs](https://github.com/norwoodj/helm-docs) (gotemplate driven) for updating the README file. + +```bash +helm-docs --chart-search-root [charts-dir] --sort-values-order file +``` + +Example for commit message: + +_build: update readme for vx.x.x_ + +## Update CHANGELOG.md + +The changelog file tracks all notable changes since the last released version. +Once a new version is ready to be released, the changelog can get updated via an automatically created pull request using the [release-please workflow](../../../.github/workflows/release-please.yml) which can be triggered manually or by pushing a _changelog/v*.*.*_ branch. + +Please see: + +- [How release please works](https://github.com/google-github-actions/release-please-action/tree/v4.0.2?tab=readme-ov-file#how-release-please-works) +- [How do I change the version number?](https://github.com/googleapis/release-please/tree/v16.7.0?tab=readme-ov-file#how-do-i-change-the-version-number) +- [How can I fix release notes?](https://github.com/googleapis/release-please/tree/v16.7.0?tab=readme-ov-file#how-can-i-fix-release-notes) + +## Merge release branch + +The release branch must be merged into main. +Those merges need to happen via PRs. + +Example for PR titles: + +_build(1.2.0): merge release into main_ + +> Be aware that the merge into main triggers the workflow with the [helm-chart releaser action](../../../.github/workflows/chart-release.yaml). +> +> The workflow creates a 'ssi-dim-middle-layer-x.x.x' tag and release. The release contains the new chart. +> +> This workflow also pushes the version tag that triggers the [release workflow](../../../.github/workflows/release.yml) which creates the versioned docker image/s. + +_Consortia relevant: The 'ssi-dim-middle-layer-x.x.x' tag is used to install (with the convenience of the argocd-app-templates) or upgrade the version via AgroCD on the consortia K8s clusters._ + +## 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/tractus-x-portal.md b/docs/admin/tractus-x-portal.md new file mode 100644 index 0000000..07eb722 --- /dev/null +++ b/docs/admin/tractus-x-portal.md @@ -0,0 +1,11 @@ +# Tractus-X (Catena-X) Portal + +The SSI Dim Middle Layer is currently designed to work with the [Catea-X Portal](https://github.com/eclipse-tractusx/portal) in version [v2.1.0](https://github.com/eclipse-tractusx/portal/tree/portal-2.1.0) + +## 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/api/Dim.Web.postman_collection.json b/docs/api/Dim.Web.postman_collection.json new file mode 100644 index 0000000..e27f11e --- /dev/null +++ b/docs/api/Dim.Web.postman_collection.json @@ -0,0 +1,321 @@ +{ + "info": { + "_postman_id": "6192d67b-f199-4e4d-ba7b-53700873c13a", + "name": "Dim.Web", + "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", + "_exporter_id": "2223943" + }, + "item": [ + { + "name": "api", + "item": [ + { + "name": "dim", + "item": [ + { + "name": "setup-dim", + "item": [ + { + "name": "Create a wallet", + "request": { + "method": "POST", + "header": [], + "url": { + "raw": "{{baseUrl}}/api/dim/setup-dim?companyName=&bpn=&didDocumentLocation=", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "dim", + "setup-dim" + ], + "query": [ + { + "key": "companyName", + "value": "", + "description": "(Required) the name of the company" + }, + { + "key": "bpn", + "value": "", + "description": "(Required) bpn of the wallets company" + }, + { + "key": "didDocumentLocation", + "value": "", + "description": "(Required) The did document location" + } + ] + }, + "description": "Example: Post: api/dim/setup-dim" + }, + "response": [] + } + ] + }, + { + "name": "setup-issuer", + "item": [ + { + "name": "Create a wallet for an issuer", + "request": { + "method": "POST", + "header": [], + "url": { + "raw": "{{baseUrl}}/api/dim/setup-issuer?companyName=&bpn=&didDocumentLocation=", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "dim", + "setup-issuer" + ], + "query": [ + { + "key": "companyName", + "value": "", + "description": "(Required) the name of the company" + }, + { + "key": "bpn", + "value": "", + "description": "(Required) bpn of the wallets company" + }, + { + "key": "didDocumentLocation", + "value": "", + "description": "(Required) The did document location" + } + ] + }, + "description": "Example: Post: api/dim/setup-issuer" + }, + "response": [] + } + ] + }, + { + "name": "status-list", + "item": [ + { + "name": "Gets the status list for the given company", + "request": { + "method": "GET", + "header": [ + { + "key": "Accept", + "value": "application/json" + } + ], + "url": { + "raw": "{{baseUrl}}/api/dim/status-list?bpn=", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "dim", + "status-list" + ], + "query": [ + { + "key": "bpn", + "value": "", + "description": "(Required) id of the dim company" + } + ] + }, + "description": "Example: GET: api/dim/status-list/{bpn}" + }, + "response": [] + }, + { + "name": "Creates a status list for the given company", + "request": { + "method": "POST", + "header": [ + { + "key": "Accept", + "value": "application/json" + } + ], + "url": { + "raw": "{{baseUrl}}/api/dim/status-list?bpn=", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "dim", + "status-list" + ], + "query": [ + { + "key": "bpn", + "value": "", + "description": "(Required) bpn of the company" + } + ] + }, + "description": "Example: Post: api/dim/status-list/{bpn}" + }, + "response": [] + } + ] + }, + { + "name": "technical-user", + "item": [ + { + "name": "{bpn}", + "item": [ + { + "name": "delete", + "item": [ + { + "name": "Deletes a technical user with the given name of the given bpn", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "body": { + "mode": "raw", + "raw": "{\n \"externalId\": \"\",\n \"name\": \"\"\n}", + "options": { + "raw": { + "headerFamily": "json", + "language": "json" + } + } + }, + "url": { + "raw": "{{baseUrl}}/api/dim/technical-user/:bpn/delete", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "dim", + "technical-user", + ":bpn", + "delete" + ], + "variable": [ + { + "key": "bpn", + "value": "", + "description": "(Required) bpn of the company" + } + ] + }, + "description": "Example: Post: api/dim/technical-user/{bpn}/delete" + }, + "response": [] + } + ] + }, + { + "name": "Creates a technical user for the dim of the given bpn", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Accept", + "value": "application/json" + } + ], + "body": { + "mode": "raw", + "raw": "{\n \"externalId\": \"\",\n \"name\": \"\"\n}", + "options": { + "raw": { + "headerFamily": "json", + "language": "json" + } + } + }, + "url": { + "raw": "{{baseUrl}}/api/dim/technical-user/:bpn", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "dim", + "technical-user", + ":bpn" + ], + "variable": [ + { + "key": "bpn", + "value": "", + "description": "(Required) bpn of the company" + } + ] + }, + "description": "Example: Post: api/dim/technical-user/{bpn}" + }, + "response": [] + } + ] + } + ] + } + ] + } + ] + } + ], + "auth": { + "type": "bearer", + "bearer": [ + { + "key": "token", + "value": "{{dimToken}}", + "type": "string" + } + ] + }, + "event": [ + { + "listen": "prerequest", + "script": { + "type": "text/javascript", + "packages": {}, + "exec": [ + "" + ] + } + }, + { + "listen": "test", + "script": { + "type": "text/javascript", + "packages": {}, + "exec": [ + "" + ] + } + } + ], + "variable": [ + { + "key": "baseUrl", + "value": "/" + } + ] +} \ No newline at end of file diff --git a/docs/architecture/Architecture Constraints.md b/docs/architecture/Architecture Constraints.md new file mode 100644 index 0000000..6a68177 --- /dev/null +++ b/docs/architecture/Architecture Constraints.md @@ -0,0 +1,45 @@ +# Architecture Constraints Documentation + +## Overview + +The following document outlines the architecture constraints for the SSI Dim Middle Layer App. This App serves as a central point for wallet as well as technical user creation. The constraints outlined in this document are intended to guide the development and deployment of the system to ensure it meets the specified requirements and adheres to the defined standards. + +## General Constraints + +### System Purpose + +- **Communication**: The App facilitates communication with wallets and technical users. +- **No User Interface (UI)**: The current development plan does not include the implementation of a user interface. + +### Deployment + +- **Run Anywhere**: The system is designed to be containerized and deployable as a Docker image. This ensures it can run on various platforms, including cloud environments, on-premises infrastructure, or locally. +- **Platform-Independent**: The application is platform-independent, capable of running on Kubernetes or similar orchestration platforms. + +## Developer Constraints + +### Open Source Software + +- **Apache License 2.0**: The Apache License 2.0 is selected as the approved license to respect and guarantee intellectual property rights. + +### Development Standards + +- **Coding Guidelines**: Defined coding guidelines for frontend (FE) and backend (BE) development must be followed for all portal-related developments. +- **Consistency Enforcement**: Code analysis tools, linters, and code coverage metrics are used to enforce coding standards and maintain a consistent style. These standards are enforced through the Continuous Integration (CI) process to prevent the merging of non-compliant code. + +## Code Analysis and Security + +To ensure code quality and security, the following analyses and checks are performed during standard reviews: + +### Code Quality Checks + +- **Code Linting**: Tools to enforce coding style and detect syntax errors. +- **Code Coverage**: Metrics to ensure a sufficient percentage of the codebase is covered by automated tests. + +## 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/architecture/Context and scope.md b/docs/architecture/Context and scope.md new file mode 100644 index 0000000..e582d7c --- /dev/null +++ b/docs/architecture/Context and scope.md @@ -0,0 +1,19 @@ +# Content and Scope + +## Business Context + +The Self-Sovereign Identity (SSI) dim middle layer purpose is to facilitate seamless communication with digital wallet of SAP. Being responsible for the critical functions of creating wallets and managing technical user. + +## Technical Context + +From a technical standpoint, the SSI dim middle layer is built on a foundation that promotes interaction, monitoring and a host of other functionalities that are crucial for maintaining a secure and reliable identity management system. + +A key aspect of the technical context is the commitment to open-source principles. The SSI dim middle layer is constructed with open-source components to the greatest extent possible, fostering a collaborative and transparent development environment. Moreover, the entire codebase of the SSI dim middle layer is open-sourced, reflecting a 100% commitment to the open-source community. + +## 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/architecture/Development Concept.md b/docs/architecture/Development Concept.md new file mode 100644 index 0000000..8d3e710 --- /dev/null +++ b/docs/architecture/Development Concept.md @@ -0,0 +1,143 @@ +# Development Concept + +## Build, test, deploy + +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) + +## Development Guidelines + +The SSI dim middle layer is using following key frameworks: + +- .Net +- Entity Framework + +### Swagger + +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. + +#### API Dev Guidelines + +##### Implement authorization + +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. + +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. + +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. + +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. + +##### Validate all requests + +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. + +An API request is only processed once its contents pass a thorough validation check — otherwise, the request should never reach the application data layer. + +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. + +##### Encrypt all requests and responses + +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. + +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. + +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. + +##### Only include necessary information in responses + +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. + +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. + +=> in the ownership of every API Developer + +##### Throttle API requests and establish quotas + +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. + +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. + +Both methods should allow normal API requests but prevent floods of traffic intended to disrupt, as well as unexpected request spikes in general. + +##### Log API activity + +Logging API activities is extremely important when it comes to tracing user activity and in worst case hack activity. + +###### Conduct security tests + +=> see [Test Section](#tests) below + +##### Error Handling + +The simplest way we handle errors is to respond with an appropriate status code. + +Common agreed response codes: + +- 400 Bad Request – client sent an invalid request, such as lacking required request body or parameter. + Example: The same constraint has been configured multiple times in the request +- 401 Unauthorized – user authenticated but doesn't have permission to access the requested resource. + Example: User token doesn't have the access on the resource. +- 403 Forbidden – client failed to authenticate with the server. + Example: token expired oder invalid login. +- 404 Not Found – the requested resource does not exist. + Example: A tenant can not be found. +- 500 Internal Server Error – a generic error occurred in the internal system logic. + Example: Unexpected server-side issue during wallet creation. + Additionally to the generic error code, a detailed message/error is needed to ensure that the issue can get validated and resolved quickly. + +##### Repository Pattern + +The repositories are used via the Factory DimRepositories, which ensures that the same database instance is used for all repositories. + +Furthermore, it provides an implicit transaction functionality. + +The repositories themselves must not be registered for dependency injection in the corresponding startup; the method DimRepositories.GetInstance provides the instance of a requested repository. + +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. + +#### Tests + +##### User Authentication Test + +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. + +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. + +##### Parameter Tampering Test + +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. + +##### Injection Test + +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. + +##### Unhandled HTTP Methods Test + +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. + +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. + +##### Load Test + +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. + +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. + +An API manager or gateway tool will handle or help address the API security guidelines described above (including testing). + +## Migration + +To run the SSI dim middle layer, migrations are needed to load the initial data inside the SSI dim middle layer db to enable the SSI dim middle layer to work. +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. + +## Configurability + +SSI Dim Middle Layer configuration is mainly possible via the appsettings files as well as the static data migration files. + +## 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/architecture/Whitebox Overall System.md b/docs/architecture/Whitebox Overall System.md new file mode 100644 index 0000000..fe6a002 --- /dev/null +++ b/docs/architecture/Whitebox Overall System.md @@ -0,0 +1,44 @@ +# Whitebox Overall System + +## Summary + +In the following image you see the overall system overview of the SSI Dim Middle Layer + +```mermaid +flowchart LR + + C(Customer) + ING(Ingress) + DS(DIM Service) + PW(Process Worker) + P(Portal) + SD(SAP DIM) + PHD[("Postgres Database \n \n (Base data created with \n application seeding)")] + + subgraph SSI Dim Middle Layer Product + ING + PHD + DS + PW + end + + subgraph External Systems + P + SD + end + + C-->|"Authentication & Authorization Data \n (Using JWT)"|ING + ING-->|"Forward Request"|DS + PW-->|"Read, Write Wallet & Technical User Data"|PHD + PW-->|"Callback wallet & technical user information"|P + DS-->|"Create wallets, \n manage technical users"|PHD + +``` + +## 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/architecture/operational-concept.md b/docs/architecture/operational-concept.md new file mode 100644 index 0000000..a48e9b9 --- /dev/null +++ b/docs/architecture/operational-concept.md @@ -0,0 +1,35 @@ +# Operational concepts + +## SSI Dim Middle Layer Services + +### Configuration + +The SSI Dim Middle Layer services can be configured using two methods: + +### appsettings.json + +If you build the SSI Dim Middle Layer, you can modify the appsettings.json for each backend service, to individually configure to a certain extend. This file contains all possible config entries for the application. + +### Helm Chart + +The most relevant config properties are exposed as environment variables and must be set in the Helm chart so the application can run at all. Check the SSI Dim Middle Layer Helm chart in Git for all available variables. + +### DB Migration File + +Static Data migration files provide a certain configuration possibility by adding or deleting static data records before the deployment. Be aware that touching static data files will always impact the application business process. It is suggested to always test the application with the planned changes carefully in INT before releasing to a productive env. + +## Monitoring + +Currently all backend services write log entries as structural data in json format. These logs can easily be monitored. There are several options to provide a stable monitoring solution, one of them is to setup loki and grafana. In this solution loki is used as a datasource and custom dashboards can be setup in grafana to monitor the services. Some general Properties to query with grafana are: + +- StatusCode - contains the status code of the response +- Elapsed - contains the time a endpoint took to response in milliseconds +- RenderedMessage - contains the log message with possible errors + +## 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 55e739b..486ecdb 100644 --- a/src/web/Dim.Web/Controllers/DimController.cs +++ b/src/web/Dim.Web/Controllers/DimController.cs @@ -35,8 +35,8 @@ public static RouteGroupBuilder MapDimApi(this RouteGroupBuilder group) var dim = group.MapGroup("/dim"); dim.MapPost("setup-dim", ([FromQuery] string companyName, [FromQuery] string bpn, [FromQuery] string didDocumentLocation, IDimBusinessLogic dimBusinessLogic) => dimBusinessLogic.StartSetupDim(companyName, bpn, didDocumentLocation, false)) - .WithSwaggerDescription("Gets the keys for the attributes", - "Example: Post: api/dim/setup-dim", + .WithSwaggerDescription("Creates a holder wallet", + "Example: POST: api/dim/setup-dim", "the name of the company", "bpn of the wallets company", "The did document location") @@ -44,8 +44,8 @@ public static RouteGroupBuilder MapDimApi(this RouteGroupBuilder group) .Produces(StatusCodes.Status201Created); dim.MapPost("setup-issuer", ([FromQuery] string companyName, [FromQuery] string bpn, [FromQuery] string didDocumentLocation, IDimBusinessLogic dimBusinessLogic) => dimBusinessLogic.StartSetupDim(companyName, bpn, didDocumentLocation, true)) - .WithSwaggerDescription("Gets the keys for the attributes", - "Example: Post: api/dim/setup-issuer", + .WithSwaggerDescription("Creates a wallet for an issuer", + "Example: POST: api/dim/setup-issuer", "the name of the company", "bpn of the wallets company", "The did document location") From cbfdcfb4b0e8c46fff4c9ed23396795886181095 Mon Sep 17 00:00:00 2001 From: Evelyn Gurschler Date: Thu, 1 Aug 2024 16:12:17 +0200 Subject: [PATCH 2/3] chore: update docs --- README.md | 2 ++ .../{ => iam}/identity-access-management.md | 6 +++--- docs/admin/release-process/Release Process.md | 6 ------ docs/admin/tractus-x-portal.md | 11 ---------- docs/architecture/Architecture Constraints.md | 20 ------------------- docs/architecture/Context and scope.md | 2 +- ...onal-concept.md => Operational Concept.md} | 0 7 files changed, 6 insertions(+), 41 deletions(-) rename docs/admin/{ => iam}/identity-access-management.md (65%) delete mode 100644 docs/admin/tractus-x-portal.md rename docs/architecture/{operational-concept.md => Operational Concept.md} (100%) diff --git a/README.md b/README.md index a5c4c14..8c0adca 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ This repository contains the code for the Integration layer between Digital Identity Management (DIM) solution and Tractus-X Portal written in C#. It's used to create a wallet and configure all needed information. +The SSI Dim Middle Layer is currently designed to work with the [Eclipse Tractus-X Portal](https://github.com/eclipse-tractusx/portal) in version [v2.1.0](https://github.com/eclipse-tractusx/portal/tree/portal-2.1.0). The Eclipse Tractus-X Portal is the reference implementation of the portal application for [Catena-X](https://catena-x.net). + For **installation** details and further information, please refer to the chart specific [README](./charts/dim/README.md). ## Requirements and Setup diff --git a/docs/admin/identity-access-management.md b/docs/admin/iam/identity-access-management.md similarity index 65% rename from docs/admin/identity-access-management.md rename to docs/admin/iam/identity-access-management.md index d6ee80f..4d48705 100644 --- a/docs/admin/identity-access-management.md +++ b/docs/admin/iam/identity-access-management.md @@ -1,10 +1,10 @@ -# Identity Access Management +# Identity Access Management (IAM) ## Role concept -The endpoints of the SSI Dim Middle Layer can only be used with an authenticated user. To be able to authorize the user, he needs to have the configured Audience which is set in the appsetting under `JWTBEAREROPTIONS__TOKENVALIDATIONPARAMETERS__VALIDAUDIENCE. The configured Audience **must** be added as a client in the idp. +The endpoints of the SSI Dim Middle Layer can only be used with an authenticated and authorized user. To be able to authorize the (technical) user, he needs to have the configured audience which is set in the appsettings under `JWTBEAREROPTIONS__TOKENVALIDATIONPARAMETERS__VALIDAUDIENCE`. The configured audience **must** be added as a client in the IAM system. -The following roles do exist and need to be exist in the Client that is configured as the valid audience: +The following roles need to exist in the client that is configured as the valid audience and need to be assigned to the (technical) user: | Role | Endpoint | |-----------------------|------------------------------------------------------| diff --git a/docs/admin/release-process/Release Process.md b/docs/admin/release-process/Release Process.md index 2c664bb..24bcc0c 100644 --- a/docs/admin/release-process/Release Process.md +++ b/docs/admin/release-process/Release Process.md @@ -11,8 +11,6 @@ The release process for a new version can roughly be divided into the following - [Merge release branch](#merge-release-branch) - [NOTICE](#notice) -The process builds on the [Development Flow](../dev-process/Dev-flow_git-diagram.md) which, usually, takes place within forks and leads to merged pull requests in the repositories of the eclipse-tractusx organization. - For assigning and incrementing **version** numbers [Semantic Versioning](https://semver.org) is followed. ## Preparations on the release branch @@ -33,8 +31,6 @@ The version needs to be updated in the `src` directory within the 'Directory.Bui Also, bump the chart and app version in the [Chart.yaml](../../../charts/dim/Chart.yaml) and the version of the images in the [values.yaml](../../../charts/dim/values.yaml). -_Consortia relevant: Update the version of the targetRevision tag in the [argocd-app-templates](../../../consortia/argocd-app-templates/), used for consortia-environments._ - Example for commit message: _build: bump version for vx.x.x_ @@ -77,8 +73,6 @@ _build(1.2.0): merge release into main_ > > This workflow also pushes the version tag that triggers the [release workflow](../../../.github/workflows/release.yml) which creates the versioned docker image/s. -_Consortia relevant: The 'ssi-dim-middle-layer-x.x.x' tag is used to install (with the convenience of the argocd-app-templates) or upgrade the version via AgroCD on the consortia K8s clusters._ - ## NOTICE This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/docs/admin/tractus-x-portal.md b/docs/admin/tractus-x-portal.md deleted file mode 100644 index 07eb722..0000000 --- a/docs/admin/tractus-x-portal.md +++ /dev/null @@ -1,11 +0,0 @@ -# Tractus-X (Catena-X) Portal - -The SSI Dim Middle Layer is currently designed to work with the [Catea-X Portal](https://github.com/eclipse-tractusx/portal) in version [v2.1.0](https://github.com/eclipse-tractusx/portal/tree/portal-2.1.0) - -## 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/architecture/Architecture Constraints.md b/docs/architecture/Architecture Constraints.md index 6a68177..138bd6d 100644 --- a/docs/architecture/Architecture Constraints.md +++ b/docs/architecture/Architecture Constraints.md @@ -16,26 +16,6 @@ The following document outlines the architecture constraints for the SSI Dim Mid - **Run Anywhere**: The system is designed to be containerized and deployable as a Docker image. This ensures it can run on various platforms, including cloud environments, on-premises infrastructure, or locally. - **Platform-Independent**: The application is platform-independent, capable of running on Kubernetes or similar orchestration platforms. -## Developer Constraints - -### Open Source Software - -- **Apache License 2.0**: The Apache License 2.0 is selected as the approved license to respect and guarantee intellectual property rights. - -### Development Standards - -- **Coding Guidelines**: Defined coding guidelines for frontend (FE) and backend (BE) development must be followed for all portal-related developments. -- **Consistency Enforcement**: Code analysis tools, linters, and code coverage metrics are used to enforce coding standards and maintain a consistent style. These standards are enforced through the Continuous Integration (CI) process to prevent the merging of non-compliant code. - -## Code Analysis and Security - -To ensure code quality and security, the following analyses and checks are performed during standard reviews: - -### Code Quality Checks - -- **Code Linting**: Tools to enforce coding style and detect syntax errors. -- **Code Coverage**: Metrics to ensure a sufficient percentage of the codebase is covered by automated tests. - ## NOTICE This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/docs/architecture/Context and scope.md b/docs/architecture/Context and scope.md index e582d7c..a2b5940 100644 --- a/docs/architecture/Context and scope.md +++ b/docs/architecture/Context and scope.md @@ -2,7 +2,7 @@ ## Business Context -The Self-Sovereign Identity (SSI) dim middle layer purpose is to facilitate seamless communication with digital wallet of SAP. Being responsible for the critical functions of creating wallets and managing technical user. +The Self-Sovereign Identity (SSI) DIM Middle Layer purpose is to facilitate seamless communication with digital wallet of SAP. Being responsible for the critical functions of creating wallets and managing technical user. ## Technical Context diff --git a/docs/architecture/operational-concept.md b/docs/architecture/Operational Concept.md similarity index 100% rename from docs/architecture/operational-concept.md rename to docs/architecture/Operational Concept.md From 1a2284bc14cf2ce6a1e5414a7428a5df719b183d Mon Sep 17 00:00:00 2001 From: Evelyn Gurschler Date: Thu, 1 Aug 2024 16:16:03 +0200 Subject: [PATCH 3/3] docs: update contributing.md --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index aed3868..52d7970 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,6 +22,8 @@ Should you wish to work on an issue, please claim it first by commenting on the If you have questions about one of the issues, please comment on them, and one of the maintainers will clarify. +Please also refer to [How to Contribute](/docs/admin/dev-process/How%20to%20contribute.md). + ## Contributing Code or Documentation You are welcome to contribute code in order to fix a bug or to implement a new feature that is logged as an issue.