From e3a4a0d90688d5b564a67fa89c57c3813f14b5c0 Mon Sep 17 00:00:00 2001 From: Evelyn Gurschler Date: Mon, 20 Nov 2023 15:21:05 +0100 Subject: [PATCH 1/5] docs(data flow): add diagram (#195) --- .../Architecture/Security-Assessment.md | 97 +++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 developer/Technical Documentation/Architecture/Security-Assessment.md diff --git a/developer/Technical Documentation/Architecture/Security-Assessment.md b/developer/Technical Documentation/Architecture/Security-Assessment.md new file mode 100644 index 000000000..461919cec --- /dev/null +++ b/developer/Technical Documentation/Architecture/Security-Assessment.md @@ -0,0 +1,97 @@ +# Security Assessment + +## Data Flow Diagram + +```mermaid +flowchart LR + + RF("Registration") + PF("Portal") + + RS(Registration service) + AS(Administration service) + MAS(Marketplace apps service) + MSS(Marketplace services service) + NS(Notification service) + + NC("Potential new company (admin)") + CU-Shared(Company user) + CU-Own(Company user) + + K("Keycloak (REST API)") + + BPDM(Business Partner Data Management) + SDT(Semantic Hub / Digital Twin) + SDR("SD-Registry \n (Self Description)") + MIW(Managed Identity Wallets) + + CH(Gaia-X Clearing House) + + subgraph Portal + subgraph Frontend + RF + PF + end + subgraph Backend + RS + AS + MAS + MSS + NS + end + PDB[(Portal DB \n Postgres \n EF Core for mapping \n objects to SQL)] + end + subgraph Keycloak + subgraph centralidp + K + end + subgraph sharedidp + subgraph Company realms + NC + CU-Shared + end + end + end + subgraph ownIdP + CU-Own + end + subgraph cross[Catena-X Cross functions] + BPDM + SDT + SDR + MIW + end + subgraph ext["External Services (3rd party)"] + CH + end + + RS <-->|Company data \n user role data \n T&C / consent agreements| RF + RS <--> K + RS -->|Company data \n user role data \n T&C consent agreements| PDB + RS -->|"Company data (e.g. name, etc.)"| BPDM + + AS --> K + AS <--> PF + AS -->|"User data \n (real and technical company data)"| PDB + AS -->|Data related to \n self description| SDR + AS -->|"Create MIW-tenant \n update MIW-tenant (BPN-VC, Member-VC) \n update MIW-framework-VC \n update dismantler-VC \n data: BPN, Auth, Contract, Version"| MIW + AS -->|Company data \n signed self description| CH + + MAS -->|Company app subscription data \n app service data + user preferences| PDB + MAS <--> K & PF + + MSS <--> PF & K + MSS -->|Company app subscription data \n app service data + user preferences| PDB + + NS --> PDB & PF & K + + PF -->|Product meta data| SDT + PF -->|"Company data (e.g. BPN)"| BPDM + + NC & CU-Shared & CU-Own --> |OIDC| K + + K <--> |"Authentication/authorization data (using JWT)"| RF & PF + + %% workaround to improve arrangement of subgraphs + K ~~~ ownIdP & cross & ext +``` From 08d1ca1b41dad5fe612d60b520f06395644dbdb4 Mon Sep 17 00:00:00 2001 From: Evelyn Gurschler Date: Thu, 23 Nov 2023 16:06:47 +0100 Subject: [PATCH 2/5] docs(data-flow): improve diagram --- .../Architecture/Data-Flow.md | 113 ++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 developer/Technical Documentation/Architecture/Data-Flow.md diff --git a/developer/Technical Documentation/Architecture/Data-Flow.md b/developer/Technical Documentation/Architecture/Data-Flow.md new file mode 100644 index 000000000..664020f87 --- /dev/null +++ b/developer/Technical Documentation/Architecture/Data-Flow.md @@ -0,0 +1,113 @@ +# Data Flow Diagram + +```mermaid +flowchart LR + + RF("Registration") + PF("Portal") + + RS(Registration service) + AS(Administration service) + MAS(Marketplace apps service) + MSS(Marketplace services service) + NS(Notification service) + + CU-Own(Company user) + + NC1("Potential new company (admin)") + CU-Shared1(Company user) + + NC2("Potential new company (admin)") + CU-Shared2(Company user) + + NC3("Potential new company (admin)") + CU-Shared3(Company user) + + K("Keycloak (REST API)") + + BPDM(Business Partner Data Management) + SDT(Semantic Hub) + SDF("SD Factory \n (Self Description)") + MIW(Managed Identity Wallets) + + CH(Gaia-X Clearing House) + OSP("Onboarding Service Provider \n (Owns infrastructure \n e.g. IAM, portal and registration app, \n other core services) ") + + subgraph Portal + subgraph Frontend + RF + PF + end + subgraph Backend + RS + AS + MAS + MSS + NS + end + PDB[(Portal DB \n Postgres \n EF Core for mapping \n objects to SQL)] + end + subgraph operator[Operator IdP] + subgraph centralidp[centralidp Keycloak] + K + end + subgraph sharedidp[sharedidp Keycloak] + subgraph companyrealm1[Company realm] + NC1 + CU-Shared1 + end + subgraph companyrealm2[Company realm] + NC2 + CU-Shared2 + end + subgraph companyrealm3[Company realm] + NC3 + CU-Shared3 + end + end + end + subgraph ownIdP + CU-Own + end + subgraph cross[Catena-X Cross functions] + BPDM + SDT + SDF + MIW + OSP + end + subgraph ext["External Services (3rd party)"] + CH + end + + RS <-->|Company data \n user role data \n T&C / consent agreements| RF + RS <--> K + RS -->|Company data \n user role data \n T&C consent agreements| PDB + + AS --> K + AS <--> PF + AS -->|"User data \n (real and technical company data)"| PDB + AS ---|Data related to \n self description| SDF + AS -->|"Create MIW-tenant \n update MIW-tenant (BPN-VC, Member-VC) \n update MIW-framework-VC \n update dismantler-VC \n data: BPN, Auth, Contract, Version"| MIW + AS <-->|Company data \n signed self description| CH + AS <-->|OSP registers its customer \n Company Data \n Admin User Record| OSP + + NS --> PDB & PF & K + + BPDM -->|"Company data (e.g. name, etc.)"| RF + BPDM -->|"Company data (e.g. BPN)"| AS + + MAS -->|Company app subscription data \n app service data + user preferences| PDB + MAS <--> K & PF + + MSS <--> PF & K + MSS -->|Company app subscription data \n app service data + user preferences| PDB + + SDF <--> CH + + SDT -->|Product meta data| PF + + NC1 & CU-Shared1 & NC2 & CU-Shared2 & NC3 & CU-Shared3 & CU-Own --> |OIDC| K + + K <--> |"Authentication/authorization data (using JWT)"| RF & PF +``` From cf3f5474dec891888a6f2710409c3ce26190178f Mon Sep 17 00:00:00 2001 From: Evelyn Gurschler Date: Thu, 23 Nov 2023 16:08:10 +0100 Subject: [PATCH 3/5] chore: fix linter issues --- .../Architecture/Data-Flow.md | 2 +- .../Architecture/Security-Assessment.md | 2 +- .../04. Create new user account (bulk).md | 14 +++--- .../12. Offer Authentication Flow.md | 43 ++++++++++--------- 4 files changed, 31 insertions(+), 30 deletions(-) diff --git a/developer/Technical Documentation/Architecture/Data-Flow.md b/developer/Technical Documentation/Architecture/Data-Flow.md index 664020f87..469ed5b1d 100644 --- a/developer/Technical Documentation/Architecture/Data-Flow.md +++ b/developer/Technical Documentation/Architecture/Data-Flow.md @@ -79,7 +79,7 @@ flowchart LR subgraph ext["External Services (3rd party)"] CH end - + RS <-->|Company data \n user role data \n T&C / consent agreements| RF RS <--> K RS -->|Company data \n user role data \n T&C consent agreements| PDB diff --git a/developer/Technical Documentation/Architecture/Security-Assessment.md b/developer/Technical Documentation/Architecture/Security-Assessment.md index 461919cec..ceda94806 100644 --- a/developer/Technical Documentation/Architecture/Security-Assessment.md +++ b/developer/Technical Documentation/Architecture/Security-Assessment.md @@ -64,7 +64,7 @@ flowchart LR subgraph ext["External Services (3rd party)"] CH end - + RS <-->|Company data \n user role data \n T&C / consent agreements| RF RS <--> K RS -->|Company data \n user role data \n T&C consent agreements| PDB diff --git a/docs/03. User Management/01. User Account/04. Create new user account (bulk).md b/docs/03. User Management/01. User Account/04. Create new user account (bulk).md index 1aabe66cd..8c9a70a6d 100644 --- a/docs/03. User Management/01. User Account/04. Create new user account (bulk).md +++ b/docs/03. User Management/01. User Account/04. Create new user account (bulk).md @@ -11,14 +11,15 @@ Please note that it is suggested to separate the bulk user create groups per rol
#### Preparation + The bulk user creation overlay allows you to download the csv template. Download the template to get started and fill out the necessary details - each user account needs to get added in a own row. Depending on your IdP type, the mandatory fields might differ - generally following attributes are needed per user -* first name -* last name -* email +- first name +- last name +- email Make sure that you do not add duplicates. In case you do, they will run on an error while creating. @@ -36,9 +37,9 @@ Make sure that you do not add duplicates. In case you do, they will run on an er As soon as you have added all necessary users successfully, upload the csv file via the provided drag&drop element. Details steps: -* Locate and select the 'Upload CSV' or similar option -* Choose your prepared CSV file from your local storage -* Confirm the upload to proceed +- Locate and select the 'Upload CSV' or similar option +- Choose your prepared CSV file from your local storage +- Confirm the upload to proceed ##### Validation and Error Handling: @@ -48,7 +49,6 @@ Review error messages and make corrections in your CSV file as needed.

- #### Feedback As soon as all checks have been successful, the application process each user entry and create the respective user account. When the user creation process is finished, a summary of successful additions and any potential errors will get provided. diff --git a/docs/09. Others/12. Offer Authentication Flow.md b/docs/09. Others/12. Offer Authentication Flow.md index 07177d5f3..f41f1d4bd 100644 --- a/docs/09. Others/12. Offer Authentication Flow.md +++ b/docs/09. Others/12. Offer Authentication Flow.md @@ -6,12 +6,11 @@
->> Key Concepts ->> ->> - Get an understanding of the app/service CX listing, subscription and running the service for an customer process ->> - Understand the concept of user authentication and client separation ->> - Review the troubleshooting tips (coming soon) ->> +> > Key Concepts +> > +> > - Get an understanding of the app/service CX listing, subscription and running the service for an customer process +> > - Understand the concept of user authentication and client separation +> > - Review the troubleshooting tips (coming soon)

@@ -22,6 +21,7 @@ In the description below the high level process of app/service listing; subscrip The process is relevant for App Provider, Service Provider and the App/Service Customer. The integration to the operator keycloak enables: + - app provider to register the application instance (per customer) - app provider separate app customer instances (each instance has a own client) - customer to assign app user roles to their company user members and get access to the app client @@ -33,11 +33,9 @@ The integration to the operator keycloak enables: image -

- ## Background Information ### Client Concept @@ -47,14 +45,17 @@ This separation enhances security and manageability in the following ways:
->> #### Isolation ->> of Permissions: Each client application has its own set of permissions. This ensures that an application can only access the specific resources and data it needs, reducing the risk of unauthorized access. ->> ->> #### Security ->> Boundaries: Client separation establishes clear security boundaries between applications. If one client is compromised, it doesn't automatically jeopardize the security of other clients, as they operate independently. ->> ->> #### Auditing ->> and Monitoring: Separation makes it easier to monitor and audit the activities of individual clients. Suspicious behavior or security breaches can be detected more easily. +> > #### Isolation +> > +> > of Permissions: Each client application has its own set of permissions. This ensures that an application can only access the specific resources and data it needs, reducing the risk of unauthorized access. +> > +> > #### Security +> > +> > Boundaries: Client separation establishes clear security boundaries between applications. If one client is compromised, it doesn't automatically jeopardize the security of other clients, as they operate independently. +> > +> > #### Auditing +> > +> > and Monitoring: Separation makes it easier to monitor and audit the activities of individual clients. Suspicious behavior or security breaches can be detected more easily.
@@ -72,14 +73,14 @@ Overall, identity provider client separation is a best practice in identity and The catena-x marketplace is hosted/operated by an CX operator. As dataspace member (companies which have successfully registered for CX dataspace with one or several operators) app provider or service provider roles can get selected. The company role "App Provider" or "Service Provider" enables the participant to use the app/service release process to request app/service listing on the operator marketplace. -To view the app registration process and the single steps - follow the link [App Registration Process](/docs/04.%20App(s)/02.%20App%20Release%20Process/index.md) +To view the app registration process and the single steps - follow the link [App Registration Process]() The app registration is relevant to list your offer inside the CX marketplace. Clients/Technical user accounts get created with subscription activation. (see details below)
### #2 App Subscription and activation -Customers are able to subscribe app/services offered inside the marketplace. [Create a subscription request](/docs/04.%20App(s)/05.%20App%20Subscription/01.%20Subscription%20Request%20(Customer).md) +Customers are able to subscribe app/services offered inside the marketplace. [Create a subscription request]() The subscription triggers the request on the app/service provider side. The app/service provider gets informed via email and can look up the request inside the portal => app/service subscription management board. As soon as all data are reviewed, the app/service provider will ramp up the app/service in its domain and configure the app/service for the customer. In most of the cases the app/service needs access to a certain core applications provided by the operator. Via the technical user the connection is supposed to get established. If the app/service provider is ready for app/service configuration, the app/service provider can generate the necessary technical user by using the app/service subscription board and select for the specific customer "configuration". The configuration requests a app/service tenant url (depending on the offer type) - the endpoint url is the url with which the customer can access the app. The url is used to create the IdP app client and to configure allowed user roles (as per the defined roles by the app provider). At the end of the process, the technical user (as configured previously in the release process) is getting created and technical user client id as well as the secret is getting shared with the offer provider. @@ -93,9 +94,9 @@ Special Note: apps have generally additional user roles defined. In this scenari ### Connected Topics -* [>> Technical User Profiles]() -* [>> Technical Implementation Details]() -* [>> ...]() +- [>> Technical User Profiles]() +- [>> Technical Implementation Details]() +- [>> ...]() ## NOTICE From ff9ce983c0cdc3f4b31559e54832d62889ae101b Mon Sep 17 00:00:00 2001 From: Evelyn Gurschler Date: Thu, 23 Nov 2023 16:10:07 +0100 Subject: [PATCH 4/5] chore: remove security-assessment.md --- .../Architecture/Security-Assessment.md | 97 ------------------- 1 file changed, 97 deletions(-) delete mode 100644 developer/Technical Documentation/Architecture/Security-Assessment.md diff --git a/developer/Technical Documentation/Architecture/Security-Assessment.md b/developer/Technical Documentation/Architecture/Security-Assessment.md deleted file mode 100644 index ceda94806..000000000 --- a/developer/Technical Documentation/Architecture/Security-Assessment.md +++ /dev/null @@ -1,97 +0,0 @@ -# Security Assessment - -## Data Flow Diagram - -```mermaid -flowchart LR - - RF("Registration") - PF("Portal") - - RS(Registration service) - AS(Administration service) - MAS(Marketplace apps service) - MSS(Marketplace services service) - NS(Notification service) - - NC("Potential new company (admin)") - CU-Shared(Company user) - CU-Own(Company user) - - K("Keycloak (REST API)") - - BPDM(Business Partner Data Management) - SDT(Semantic Hub / Digital Twin) - SDR("SD-Registry \n (Self Description)") - MIW(Managed Identity Wallets) - - CH(Gaia-X Clearing House) - - subgraph Portal - subgraph Frontend - RF - PF - end - subgraph Backend - RS - AS - MAS - MSS - NS - end - PDB[(Portal DB \n Postgres \n EF Core for mapping \n objects to SQL)] - end - subgraph Keycloak - subgraph centralidp - K - end - subgraph sharedidp - subgraph Company realms - NC - CU-Shared - end - end - end - subgraph ownIdP - CU-Own - end - subgraph cross[Catena-X Cross functions] - BPDM - SDT - SDR - MIW - end - subgraph ext["External Services (3rd party)"] - CH - end - - RS <-->|Company data \n user role data \n T&C / consent agreements| RF - RS <--> K - RS -->|Company data \n user role data \n T&C consent agreements| PDB - RS -->|"Company data (e.g. name, etc.)"| BPDM - - AS --> K - AS <--> PF - AS -->|"User data \n (real and technical company data)"| PDB - AS -->|Data related to \n self description| SDR - AS -->|"Create MIW-tenant \n update MIW-tenant (BPN-VC, Member-VC) \n update MIW-framework-VC \n update dismantler-VC \n data: BPN, Auth, Contract, Version"| MIW - AS -->|Company data \n signed self description| CH - - MAS -->|Company app subscription data \n app service data + user preferences| PDB - MAS <--> K & PF - - MSS <--> PF & K - MSS -->|Company app subscription data \n app service data + user preferences| PDB - - NS --> PDB & PF & K - - PF -->|Product meta data| SDT - PF -->|"Company data (e.g. BPN)"| BPDM - - NC & CU-Shared & CU-Own --> |OIDC| K - - K <--> |"Authentication/authorization data (using JWT)"| RF & PF - - %% workaround to improve arrangement of subgraphs - K ~~~ ownIdP & cross & ext -``` From 7b02c790000526279589a46e6faeb69f5a9e674f Mon Sep 17 00:00:00 2001 From: Evelyn Gurschler Date: Thu, 23 Nov 2023 16:10:48 +0100 Subject: [PATCH 5/5] chore(data-flow): add footer --- .../Technical Documentation/Architecture/Data-Flow.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/developer/Technical Documentation/Architecture/Data-Flow.md b/developer/Technical Documentation/Architecture/Data-Flow.md index 469ed5b1d..8be269f58 100644 --- a/developer/Technical Documentation/Architecture/Data-Flow.md +++ b/developer/Technical Documentation/Architecture/Data-Flow.md @@ -111,3 +111,11 @@ flowchart LR K <--> |"Authentication/authorization data (using JWT)"| RF & PF ``` + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2021-2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/portal-assets