Self-Description Factory

A Self Description document (SD-document) is provided for any participant of this data space. The Self Descriptions are stored inside the Self Description Hub. Self-Description F

actory (SD-Factory) component is responsible for the creation of Self Descriptions. This c o m p o n e n t gets input data from the Onboarding Tool, which prepares the data for the SD-Factory, creates a Verifiable Credential and passes the document to the Managed Identity Wallet based on the Custodian for the signature. The result is sent to the Compliance Service for further processing.

ADding title

adding something else

asdf asdf asdf

asdf asdf asdf

fafafafafafafafa

Software Version

Software version: 2.1.6
Helm Chart version: 2.1.6

Solution Strategy

Here the flow of Self-Description creation is shown:

sequenceDiagram
	actor User
	User-->>Identity Provider: authentication
	User->>Onboarding Service: participant data
    Note over SDFactory: Gaia-x-Profile
    Note over Onboarding Service: Cofinity-X Portal Backend
	Onboarding Service-->>Identity Provider: technical user
	Onboarding Service->>+SDFactory: SD-document 
    SDFactory-->>Identity Provider: technical user to access Compliance Service
    SDFactory-->>Identity Provider: technical user to access MIW Service
    SDFactory->>+MIW: Fetch wallet data by bpn as walletid
    MIW-->>+SDFactory: Return wallet data
    SDFactory->>+SDFactory: Prepare VC
    SDFactory->>+ClearingHouse Service: Unsigned Verifiable Credential
    SDFactory-->>+Onboarding Service: 202 ACCEPTED
    ClearingHouse Service->>ClearingHouse Service: asynchronous processing
    ClearingHouse Service->>+Onboarding Service: Signed Verifiable Credential

Loading

1. A user is authenticated in Identity Provider service on behalf of a company and receives the authentication ticket.
2. User calls On-boarding Service with request for creating and publishing SD-document. The service authenticates the user and prepare the data SD-Factory needs for creating SD-document. SDFactory takes document in a format, specified in OpenAPI document Pre-22.4 schema, AKA 1.06 and convert it to Trust Framework V.22.10. Currently, these documents are supported by SD-Factory:
   • LegalParticipant;
   • ServiceOffering;
3. On-boarding service (OS) calls SD-Factory for creating SD-document passing this data as a parameter. OS uses a credential with a role allowing for this request (e.g. add_self_descriptions, the default role for SD-document creation). The credential for this operation is taken from Identity Provider (keycloak).
4. SD-Factory creates a Verifiable Credential based on the information taken from On-boarding Service and Managed Identity Wallet Service (MIW).
5. SD-Factory sends unsigned Verifiable Credential to the Compliance Service for further (asynchronous) processing. Compliance Service is responsible for verification of the VC and signing. In the end the Compliance Service sends Self-Description document back to the On-boarding service endpoint. OS is responsible for storing and publishing it.

For the VC we have to provide valid JSON context where we have a reference to an object from known ontology. This object carries the claims the SD-Factory signs. The document is published on the github repository of the project. The vocabulary URL can be changed when will be provided by Trusted Framework. Currently, we support a vocabulary for Version 22.10 of Trust Framework.

REST Interface

The SD-Factory provides interfaces to create Verifiable Credential for one of mentioned documents. Only the authorized user can call these interfaces. They are protected with keycloak. The configuration parameters are given in application.yml. The user role for creating Self-Descriptions is specified in application.yml as well.

To trigger creation of the SD-document one shall call the endpoint available by path :

POST /api/rel3/selfdescription

OpenAPI specification is given in Pre-22.4 schema, AKA 1.06.

An example of the body for LegalParticipant is given bellow:

{
  "type": "LegalParticipant",
  "holder": "BPNL000000000000",
  "issuer": "CAXSDUMMYCATENAZZ", 
  "externalId": "ID01234-123-4321",
  "registrationNumber": [
    {
      "type": "local",
      "value": "o12345678"
    }
  ],
  "headquarterAddress.country": "DE",
  "legalAddress.country": "DE",
  "bpn": "BPNL000000000000"
}

The Self-Description in the format of Verifiable Credential is created. Here is an example of Verifiable Credentials for LegalParticipant:

{
   "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://f1c82785-5598-41c7-a083-01a8e1a80e19.mock.pstmn.io/ctxsd"
   ],
   "type": [
      "VerifiableCredential"
   ],
   "id": "5096f9c2-24fd-43c5-9d50-e43a409ebb33",
   "issuanceDate": "2023-07-26T17:07:31Z",
   "expirationDate": "2023-10-24T17:07:31Z",
   "credentialSubject": {
      "bpn": "BPNL000000000000",
      "registrationNumber": [
         {
            "type": "local",
            "value": "o12345678"
         }
      ],
      "headquarterAddress": {
         "countryCode": "DE"
      },
      "type": "LegalParticipant",
      "legalAddress": {
         "countryCode": "DE"
      }
   },
   "issuer": "CAXSDUMMYCATENAZZ"
}

Then the Verifiable Credential is sent to the Compliance Service.

Configuration

The configuration property file is located under resources folder and is incorporated into the fat jar during build process. It can be customized before building if needed. Or,the another one can be used as its location can be overridden:

java -jar myproject.jar --spring.config.location=file:./custom-config/

Here application.yml will be searched in custom-config dir.

Self-Description Factory Property file

An example of application.yml for SD-Factory is given bellow:

server:
  port: 8080
  error:
    include-message: always
keycloak:
  resource:
    clientid: Cl2-CX-Portal
spring:
  jackson:
    default-property-inclusion: non_null
  security:
    oauth2:
      resourceserver:
        jwt:
        #jwk-set-uri: https://centralidp.int.demo.catena-x.net/auth/realms/CX-Central/protocol/openid-connect/certs
springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    url: /SDFactoryApi-vRel3.yml
app:
  build:
    version: ^project.version^
  verifiableCredentials:
    durationDays: 90
    schema2210Url: https://github.com/catenax-ng/tx-sd-factory/raw/main/src/main/resources/verifiablecredentials.jsonld/sd-document-v22.10.jsonld
  usersDetails:
    custodianWallet:
    #uri: https://managed-identity-wallets.int.demo.catena-x.net/api
    #serverUrl: https://centralidp.int.demo.catena-x.net/auth
    #realm: CX-Central
    #clientId: sa-cl5-custodian-1
    #clientSecret:
    clearingHouse:
    #uri: https://dummy.dev.demo.catena-x.net/api/credentials
    #serverUrl: https://centralidp.int.demo.catena-x.net/auth
    #realm: CX-Central
    #clientId: sa-cl2-02
    #clientSecret:
  security:
    createRole: add_self_descriptions

Here keycloak section defines keycloak's parameters for client requests authentication.

app.verifiableCredentials.durationDays defines for how many days the VC is issued.

schema2210Url specify the JSON-LD vocabulary URL

app.custodianWallet contains parameters for accessing Custodian Wallet:

• uri is custodian Wallet url
• auth-server-url, realm, clientId, clientSecret are keycloak parameters for a user which calls the Custodian Wallet. This user shall have enough rights to create Verifiable Credentials and Verifiable Presentations. app.clearingHouse contains authentication parameters for calling the Compliance Service.

app.security sets a role a user must have for creating Self-Description.

Building

SD-Factory use Maven for building process. To build a service from sources one need to go to corresponding directory and trigger building process:

cd SDFactory
./mvnw clean install

Then fat jar file can be found in target folder as well as in local Maven repository. it can be run with this command:

java -jar target/sd-factory-2.0.0.jar

Please note the name of jar-file as it may differ if version is changed.

To build a Docker image one can use this command:

docker build .

A Docker image will be built and installed to the local repository.

Testing

SD-Factory can be fired up locally in Docker environment. Before that the image needs to be created. Do not forget to provide necessary configuration parameters in application.yml for keycloak and the Custodian Wallet.

Container images

This application provides container images for demonstration purposes. The base image used, to build this demo application image is eclipse-temurin:17-jdk-alpine

Notice for Docker image

DockerHub: https://hub.docker.com/r/tractusx/sdfactory
Eclipse Tractus-X product(s) installed within the image:

SD Factory

• GitHub: https://github.com/eclipse-tractusx/sd-factory
• Project home: https://projects.eclipse.org/projects/automotive.tractusx
• Dockerfile: https://github.com/eclipse-tractusx/sd-factory/blob/main/Dockerfile
• Project license: Apache License, Version 2.0

Used base image

• 17-jdk-alpine(https://hub.docker.com/layers/library/eclipse-temurin/17.0.6_10-jdk-alpine/images/sha256-c093675e143dc8023fb218c144e06491154491a7965d0664a93f99ada5259ec7?context=explore)
• Official Eclipse Temurin DockerHub page: https://hub.docker.com/_/eclipse-temurin
• Eclipse Temurin Project: https://projects.eclipse.org/projects/adoptium.temurin
• Additional information about the Eclipse Temurin images: https://github.com/docker-library/repo-info/tree/master/repos/eclipse-temurin

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc. from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

Installation Steps

INSTALL.md