Merge pull request #241 from FraunhoferISST/docs/incorporateArchitect…

…Feedback

Docs: incorporate architect feedback

docs/adminGuide/Admin_Guide.md

@@ -21,17 +21,21 @@ respective deployment scenarios for further information.
 Mainly one needs to configure the Frontend to reach the Backend. Thus, the Backend must be exposed or at least reachable
 for the Frontend.
 
-Mainly the environment variables with the prefixes `BACKEND_` and `ENDPOINT_` are needed for configuration. Please refer
-to the respective deployments for exact information.
+When not using the Helm deployment, mainly the environment variables with the prefixes `BACKEND_` and `ENDPOINT_` are
+needed for configuration. Please refer to the respective local deployment for exact information.
 
 The Backend secures all APIs except for the swagger ui with a backend key.
-This api key must be configured in the `application.properties` with the `puris.api.key` property.
+This api key must be configured in the backend via `backend.puris.api.key` (docker `PURIS_API_KEY`). In Helm, it's
+automatically set to the frontend.
 Additionally spring provides the context path that adds a path for the backend servlets.
 
 The Frontend therefore needs the following two variables:
-- `BACKEND_BASE_URL` - used to assemble requests to the backend in format: `http://<hostname:port>/<context path>`
-- `BACKEND_API_KEY `- the api key used in the backend
-- `ENDPOINT_XYZ` - endpoints of the backend used. But they are hardcoded in the backend.
+
+- `frontend.puris.baseUrl` (docker `BACKEND_BASE_URL`) - used to assemble requests to the backend in
+  format: `http://<hostname:port>/<context path>` where context path is assembled automatically via template. Is
+  automatically assembled via helm.
+- `frontend.puris.endpointXYZ` (docker `ENDPOINT_XYZ`) - endpoints of the backend used. But they are hardcoded in the
+  backend.
 
 _Note: The API key header is hard coded to `X-API-KEY`._
 
@@ -47,31 +51,49 @@ Configure EDC addresses in the Backend with prefix `edc.`. Refer to the respecti
 The Frontend provides a keycloak integration:
 
 It restricts the accessible views based on the client roles:
+
 - `PURIS_USER` - Common views related to short-term information needs
 - `PURIS_ADMIN` - EDC related views (may be used for debugging)
 
-All variables with the `IDP_` prefix are needed for configuration. `IDP_DISABLE` can be set to `true` to not use an idp
-(only recommended for development purposes). Refer to the respective deployment specific files.
+All variables with the `frontend.puris.keycloak.` (docker prefix is `IDP_`) prefix are needed for configuration.
+The `disable` property (docker `IDP_DISABLE`) can be set to `true` to not use an idp (only recommended for development
+purposes). Refer to the respective deployment specific files.
 
 Configuration and example:
 
 To host an example keycloak instance, configure the following:
 
 - `Realm` with name `Catena-X`
 - Create `Client` with name `Cl3-PURIS`
-  - `Client authentication` = false
-  - `Authentication flow `> `Standard flow` = `true` (rest `false`)
-  - `Access settings` 
-    - `Valid redirect URIs` = `http:<frontend hostname with port>/*`
-    - `Valid post logout redirect URIs` = `http:<frontend hostname with port>`
-    - `Web origins` = `http://<frontend hostname with port>`
-  - `Roles`: Create `PURIS_ADMIN`, `PURIS_USER`
+    - `Client authentication` = false
+    - `Authentication flow `> `Standard flow` = `true` (rest `false`)
+    - `Access settings`
+        - `Valid redirect URIs` = `http:<frontend hostname with port>/*`
+        - `Valid post logout redirect URIs` = `http:<frontend hostname with port>`
+        - `Web origins` = `http://<frontend hostname with port>`
+    - `Roles`: Create `PURIS_ADMIN`, `PURIS_USER`
 - Create `users` as wanted
-  - puris_test with same password (see credentials tab)
-  - add roles in client
+    - puris_test with same password (see credentials tab)
+    - add roles in client
 
 _Note: The application does NOT make use of the `Client Authentication` (private) feature of Keycloak Clients._
 
+## Configure Framework Agreement Credential Usage
+
+To configure the usage of a framework agreement credential, that is automatically enforced by the EDC during contracting
+(see further details in [ARC42 - Chapter 8](../arc42/08_concepts.md)), the following properties need to be configures:
+
+- `backend.frameworkagreement.use` (docker `PURIS_FRAMEWORKAGREEMENT_USE`) = true
+- `backend.frameworkagreement.credential` (docker `PURIS_FRAMEWORKAGREEMENT_CREDENTIAL`) = 'puris' (NOTE: not available
+  for R24.03)
+
+_**ATTENTION**: If the credential is NOT listed in the Connector Standard (CX-0018) of the current release, then the
+Tractus-X EDC will NOT technically enforce the credential by checking the availability in the Managed Identity Wallet.
+Thus, it may seem that the Credential is available, but isn't. Same applies to typos._
+
+_Note: Please refer to
+the [Portal's documentation on how to sign use case agreements](https://github.com/eclipse-tractusx/portal-assets/blob/main/docs/user/06.%20Certificates/01.%20UseCase%20Participation.md)._
+
 ## Serving with HTTPS / SSL
 
 Serving with SSL is available for Docker and Helm Deployment. In local deployment directly with mvn (backend) and
@@ -86,6 +108,7 @@ The Frontend uses a nginx-unprivileged image restricting access heavily. One can
 starting point.
 
 Let's assume the following structure:
+
 ```shell
 ls
 >> /
@@ -96,6 +119,7 @@ ls
 ```
 
 For testing purposes, create self-signed certificates:
+
 ``` sh
 mkdir ssl-certificates
 cd ssl-certificates
@@ -105,9 +129,11 @@ openssl req -x509 -out localhost.crt -keyout localhost.key \
   -subj '/CN=localhost' -extensions EXT -config <( \
    printf "[dn]\nCN=localhost\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:localhost\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")
 ```
+
 _NOTE: For productive use, you can use certificates provided by a Certificate Authority._
 
 Create a nginx.conf to provide certificates for listening on 443 for tls.
+
 ``` conf
 http {
     # other configurations 
@@ -130,6 +156,7 @@ http {
 ```
 
 Start the docker image mounting the certificates and the nginx.conf as follows:
+
 ``` sh
 
 docker run --rm --name frontend \
@@ -140,6 +167,7 @@ docker run --rm --name frontend \
 ```
 
 If you want to use of the dns alias for localhost:443, make sure to edit your /etc/hosts file:
+
 ```sh
 docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' <container_name_or_id>
 
@@ -153,6 +181,7 @@ sudo vim /etc/hosts
 Spring provides the possibility to provide ssl certificates.
 
 Let's assume the following structure:
+
 ```shell
 ls
 >> /
@@ -163,16 +192,19 @@ ls
 
 For testing purposes, create self-signed certificates using java keytool and follow the prompts.
 Remember the password. They generated key file is a pkcs12 keystore.
+
 ``` sh
 mkdir ssl-certificates
 cd ssl-certificates
 
 keytool -genkeypair -alias application -keyalg RSA -keysize 4096 -storetype PKCS12 -keystore application.p12 -validity 3650
 ```
+
 _NOTE: For productive use, you can use certificates provided by a Certificate Authority._
 
 Use your common application.properties and add the following section to the file. Name it e.g.,
 application-with-ssl.properties.
+
 ```application.properties
 server.ssl.enabled=false
 #server.port=8443
@@ -184,6 +216,7 @@ spring.ssl.bundle.jks.server.keystore.type=PKCS12
 ```
 
 Finally pass the created keystore and properties file via docker:
+
 ```shell
 docker run --rm -d -p 8433:8433 --name backend \
   -v $(pwd)/ssl-certificates/application.p12:/opt/app/ssl-certificates/application.p12 \
@@ -198,18 +231,18 @@ When using self-signed certificates, the frontend may result in a CORS error. Th
 problem. Please check if you created exceptions for both certificates, the frontend's and backend's certificates. You
 can see a related error in the Developer Tools (F12) > Network tab > select preflight header > tab security.
 
-
 ## Onboarding Your Data
 
 The application, per solution strategy, tries to provide visualization and manipulation capabilities to exchange only
 production related information.
 
-_Note: The routes in the following always need to be used based on your backend address configuration including the 
+_Note: The routes in the following always need to be used based on your backend address configuration including the
 context path._
 
 ### Onboard Master Data
 
-The application provides the following endpoints to update master data for your partner. This data may not be entered manually.
+The application provides the following endpoints to update master data for your partner. This data may not be entered
+manually.
 
 You can use this collection as an example for the REST API calls.
 
@@ -232,6 +265,6 @@ overwrite the existing stocks.
 
 ## Postgres
 
-The PURIS Backend uses a postgres Database. The helm installation already has a dependency that may be installed with 
-the chart. Optionally it may be disabled to use your own installation. Refer to the overall 
+The PURIS Backend uses a postgres Database. The helm installation already has a dependency that may be installed with
+the chart. Optionally it may be disabled to use your own installation. Refer to the overall
 [INSTALL.md](../../INSTALL.md) for further information.

docs/arc42/02_architecture_constraints.md

@@ -6,7 +6,7 @@ PURIS FOSS follows the following constraints:
 |--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | IDS & GAIA-X Compliance                    | Data sharing, storing and processing must be in compliance to the standards provided by GAIA-X and IDS.                                                                                                                                                                                                                                                  |
 | Data Sharing between Companies             | Companies must use IDS compliant and certified connectors along with an approved Catena-X information model for communication. This guarantees interoperability between certified participants. The Eclipse Dataspace Connector is highly recommended for this purpose. The data should stay inside the connector if full data sovereignty is necessary. |
-| Data sovereignty                           | To ensure data sovereignty, data owners need to attach machine readable usage policies to their data before sharing. The data consumer has to accept the usage policies before processing the data. Connectors (+ the underlying/corresponding systems) must technically enforce those usage policy descriptions.                                        |
-| DAPS                                       | DAPS Registration Service is a central Catena-X Service, which allows registering connectors remotely in Catena-X DAPS service. This Service can be used by all operators of connectors (on-premise, managed)                                                                                                                                            |
+| Data sovereignty                           | To ensure data sovereignty, data owners need to attach machine readable access policies and contract policies to their data before sharing. The data consumer has to accept the usage policies before processing the data. Connectors (+ the underlying / corresponding systems) must technically enforce those usage policy descriptions.               |
+| Managed Identity Wallet (MIW)              | MIW is a central Catena-X Service, which allows storing credentials to prove claims in the Catena-X data space.                                                                                                                                                                                                                                          |
 | Interoperability between Data Applications | Data exchange MUST follow standards so that different vendors applications may exchange data. This allows to reduce the risk of vendor-lock-ins.                                                                                                                                                                                                         |
-| Semantic Aspect Meta Model                 | Tooling used in Catena-X to semantically describe data.                                                                                                                                                                                                                                                                                                  |
+| Semantic Aspect Meta Model (SAMM)          | Tooling used in Catena-X to semantically describe data.                                                                                                                                                                                                                                                                                                  |