In Catena-X we provide self-descriptions for any participant of this data space. The Self Descriptions are stored inside the Self Description Hub, but need to be created first. Responsible for the creation of Self Descriptions is the Self Discription-Factory component. This components gets all necessary parameters and information from the Onboarding Tool, which prepares the data for the SD-Factory, and uses the CX-Wallet based on custodians to sign the Self Descriptions.
Here the flow of Self-Description creation is shown:
- A user is authenticated in Identity Provider service on behalf of a company and receives the authentication ticket.
- User calls Onboarding 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 such as:
company_number
,headquarter_country
,legal_country
,service_provider
,sd_type
andbpn
. Organization wallet of the company which runs the service shall be available at this point of time as it signs the Verifiable Credential with SD document. The wallet associated with the service shall be available as well. - Onboarding service (OS) calls SD-Factory for creating and publishing SD-document passing this data as a parameter. OS uses a credential with a role allowing for this request (e.g. ROLE_SD_CREATOR, currently ROLE_access). The credential for this operation is taken from ID Provider (keyclock).
- SD-Factory creates a Verifiable Credential based on the information taken from OS and signs it with organization key. The organization is acting as an Issuer. The wallet ID of the service is used as Holder Id. The Custodian Wallet is used for this operation.
- SD-Factory publishes the Verifiable Credential on the SD-Hub and saves it in MongoDB.
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. Currently, this context is published as a JSON-LD document at https://df2af0fe-d34a-4c48-abda-c9cdf5718b4a.mock.pstmn.io/sd-document-v0.1.jsonld
This context is going to be changed when corresponding vocabulary will be available in Trusted Framework. Currently, the vocabulary is defined in this file:
{
"@context": {
"id": "@id",
"type": "@type",
"ctx" : "https://catena-x.net/selfdescription#",
"SD-document": {
"@id": "ctx:SD-document",
"@context": {
"company_number": {
"@id": "ctx:company_number"
},
"headquarter_country": {
"@id": "ctx:headquarter_country"
},
"legal_country": {
"@id": "ctx:legal_country"
},
"service_provider": {
"@id": "ctx:service_provider"
},
"sd_type": {
"@id": "ctx:sd_type"
},
"bpn": {
"@id": "ctx:bpn"
}
}
},
"company_number" : {
"@id": "ctx:company_number",
"@type": "https://schema.org/taxID"
},
"headquarter_country": {
"@id": "ctx:headquarter_country",
"@type": "https://schema.org/addressCountry"
},
"legal_country": {
"@id": "ctx:legal_country",
"@type": "https://schema.org/addressCountry"
},
"service_provider": {
"@id": "ctx:service_provider",
"@type": "https://schema.org/url"
},
"sd_type": {
"@id": "ctx:sd_type",
"@type": "http://www.w3.org/2000/01/rdf-schema#label"
},
"bpn": {
"@id": "ctx:bpn",
"@type": "https://schema.org/name"
}
}
}
The SD-Factory provides an interface for creating and deleting SD-documents. Both
method are protected: the authorized user only can call it. Methods are protected
with keycloak, which configuration parameters are given in application.yml
.
The user roles for creating and deleting Self-Descriptions are specified in
application.yml
as well.
POST /selfdescription
where body is
{
"bpn" : "BPNL000000000000",
"company_number" : "123456",
"legal_country" : "DE",
"headquarter_country" : "DE",
"service_provider" : "http://test.example.com",
"sd_type" : "connector",
"holder" : "BPNL000000000000",
"issuer" : "BPNL000000000000"
}
this call creates a Self-Description and publishes it in the Database. The Self-Description in the format of Verifiable Credential is returned.
The fields are parameters of the Connector, holder is BPN or DID of the Connector wallet and issuer is BPN or DID of the wallet which signs the Verifiable Credential for this SD Document.
SD-Factory is installed on integration environment and available at https://sdfactory.int.demo.catena-x.net/
The Swagger documentation for SD-Factory is available at https://sdfactory.int.demo.catena-x.net/v3/api-docs as JSON and https://sdfactory.int.demo.catena-x.net/swagger-ui/index.html in human-readable format.
SD-Factory and SD-Hub are two microservices, each of them has its own configuration file.
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.yaml will be searched in custom-config dir.
An example of application.yaml
for SD-Factory is given bellow:
server:
port: 8080
keycloak:
auth-server-url: https://centralidp.demo.catena-x.net/auth
realm: CX-Central
resource: Cl2-CX-Portal
bearer-only: true
use-resource-role-mappings: true
principal-attribute: preferred_username
app:
build:
version: ^project.version^
verifiableCredentials:
durationDays: 90
idPrefix: http://sdhub.int.demo.catena-x.net/
custodianWallet:
uri: https://custodian-dev.germanywestcentral.cloudapp.azure.com/api
auth-server-url: https://catenaxdev003akssrv.germanywestcentral.cloudapp.azure.com/iamcentralidp/auth
realm: CX-Central
clientId: Client005-CustodianTest
clientSecret: <client secret>
username: <username>
password: <password>
security:
createRole: add_self_descriptions
Here keycloak
section defines keycloak's parameters for authentication client requests.
app.verifiableCredentials.durationDays
defines for how many days the VC is issued.
app.verifiableCredentials.idPrefix
specifies prefix for VC identifiers. Internally the
identifiers are represented as hexadecimal numbers, but need to accessible as URL. As SD-Hub
is responsible for serving the VCs, this parameter usually shall be set to the domain name
of the Hub.
app.custodianWallet
contains parameters for accessing Custodian Wallet:
uri
is custodian Wallet urlauth-server-url
,realm
,clientId
,clientSecret
,username
,password
- keycloak parameters for a user used for meking the calls to the Custodian Wallet. This user shall have enough rights to create Verifiable Credentials and Verifiable Presentations.
app.security
- sets the roles a user must hold for creating and removing
Self-Description to/from SD-Hub.
app.db.sd.collectionName
sets MongoDB collection nname for storing Self-Descriptions
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 ryn with this command:
java -jar target/sd-factory-1.0.0-SNAPSHOT.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:
./mvnw spring-boot:build-image
A Docker image will be built and installed to the local repository.
SD-Factory can be fired up locally in Docker environment. Before that
the images need to be created as it is described here. Pay attention
to the image names as they may change if the version of the sources was bumped up,
but the docker-compose.yml
has not been updated. Being in root directory of the
repository type this:
docker-compose up -d
Then you can call SD-Factory API or see Swagger documentation by address http://localhost:8081/swagger-ui/index.html for SD-Factory.