This repository is part of the overarching Catena-X project.
BPDM is an acronym for business partner data management. This project provides core services for querying, adding and changing business partner base information in the Catena-X landscape.
Currently, BPDM consists of the Pool and Gate services.
The BPDM Pool is the single source of truth in Catena-X for business partner base information such as addresses and official identifiers. Each record in the Pool has a unique identifier with which it can be referenced across the entire Catena-X landscape, the business partner number. Business partner records are divided into legal entities, sites and partner addresses. Self-explanatory, a legal entity record represents the legal entity information about a business partner. A site may represent legal entity’s plant or campus which is big enough to contain several contact/delivery addresses. Finally, an address partner is a location of legal entity or site with a single contact/delivery address. A legal entity may have several sites and address partner. Further, a site may have several address partners.
The Pool offers an API to query these business partner records by BPN, other identifier or by text search.
-
Maven
-
JDK17
-
PostgreSQL 14.2
-
OpenSearch 2.1.0
-
Keycloak 17.0.0 (with enabled
authprofile) -
Connection to CDQ API v4.0 (with enabled
cdqprofile)
BPDM is a SpringBoot Kotlin software project managed by Maven.
The project can be run with the following command: mvn clean spring-boot:run
When running, the project requires a Postgresql database and an Opensearch instance to be available to connect to.
Per default configuration the application expects postgres to run on localhost on port 5432.
Opensearch needs to run on localhost on port 9200 on default.
You can find and edit the default configuration for the Pool in the application.properties, application-auth.properties and application-cdq.properties files in the resources folder.
The REST API documentation can be accessed at http://localhost:8080/api/swagger-ui.
The default configuration of the application is determined by the application.properties file.
Here you can find core application configuration such as Swagger documentation, BPN generation and Actuator.
Furthermore, here you can find the configuration for the connection to the Spring datasource (currently, developed against PostgreSQL) and Opensearch.
You can also run the project with Spring profiles to enable additional components on top of the default configuration.
Currently, the BPDM Pool offers the profiles auth and cdq.
In order to run the application with a specific profile you can use the appropriate maven flag Dspring.profiles.active.
For example, the command mvn clean spring-boot:run -Dspring.profiles.active=auth starts the application with additional auth configuration enabled.
You can also run several profiles at once, of course: mvn clean spring-boot:run -Dspring.profiles.active=auth,cdq.
The following sections detail the configuration properties for each profile.
application-auth.properties enables authorization of endpoints and configures the connection to a Keycloak instance on which the authorization relies on.
The application expects the Keycloak to run on localhost on port 8180.
However, as with the Spring datasource and Opensearch connections, the connection to the Keycloak can be freely configured.
The application uses the configured auth server URL to validate incoming tokens.
For authorization purposes the application checks incoming token’s permissions:
- add_company_data
-
For endpoints creating or updating business partner records including triggering imports from CDQ/exports to Opensearch
- view_company_data
-
For read-only endpoints of business partner data
The BPDM Pool looks for these permissions in the client/resource and not on the realm level.
This profile also enables/disables the login form in the auto-generated Swagger documentation.
The Swagger login uses the client specified in the property springdoc.swagger-ui.oauth.client-id.
The file application-cdq.properties enables and configures the connection to a remote CDQ API from which the application can import business partner records.
Depending on whether this component is enabled, the application offers endpoints to import records from and to export Business Partner Numbers to CDQ.
When enabled the application requires the environment variable BPDM_CDQ_KEY to contain an API key with necessary privileges for accessing the specified storage.
Further, you need to provide a CDQ storage ID (BPDM_CDQ_STORAGE) and datasource ID BPDM_CDQ_DATASOURCE from where the records should be imported by the application.
This repository contains Helm files for deploying the BPDM Pool to a Kubernetes environment.
In an existing Kubernetes cluster the application can be deployed with the following command:
helm install release_name ./charts/pool --namespace your_namespaceThis will install a new release of the BPDM Pool in the given namespace.
On default values this release deploys the latest image tagged as main from the repository’s GitHub Container Registry.
The application is run on default profile (without authorization and CDQ connection).
Additionally, the Helm deployment contains a PostgreSQL database and Opensearch instance which the BPDM Pool connects to.
On the default values deployment no further action is needed to make the BPDM Pool deployment run. However, per default ingress is disabled, as well as no authentication for endpoints and no import from CDQ.
By giving your own values file you can configure the Helm deployment of the BPDM Pool freely:
helm install release_name ./charts/pool --namespace your_namespace -f ./path/to/your/values.yamlIn the following sections you can have a look at the most important configuration options.
Per default, the Helm deployment references a certain BPDM Pool release version where the newest Helm release points to the newest Pool version. This is a stable tag pointing to a fixed release version of the BPDM Pool. For your deployment you might want to follow the latest application releases instead.
In your values file you can overwrite the default tag:
image:
tag: "latest"You can also activate Spring profiles in which the BPDM Pool should be run. In case you want to run the Pool with authorization and CDQ connection enabled you can write the following:
springProfiles:
- auth
- cdqYou can specify your own ingress configuration for the Helm deployment to make the BPDM Pool available over Ingress. Note that you need to have the appropriate Ingress controller installed in your cluster first. For example, consider a Kubernetes cluster with an Ingress-Nginx installed. An Ingress configuration for the Pool deployment could look like this:
ingress:
enabled: true
annotations:
kubernetes.io/ingress.class: nginx
nginx.ingress.kubernetes.io/backend-protocol: "HTTP"
hosts:
- host: partners-pool.your-domain.net
paths:
- path: /
pathType: PrefixThe Helm deployment comes with the ability to configure the BPDM Pool application directly over the values file.
This way you are able to overwrite any configuration property of the application.properties, application-auth.properties and application-cdq.properties files.
Consider that you would need to turn on auth and cdq profile first before overwriting any property in the corresponding properties file could take effect.
Overwriting configuration properties can be useful to connect to a remote service:
applicationConfig:
bpdm:
security:
auth-server-url: https://remote.keycloak.domain.com
realm: CUSTOM_REALM
client-id: POOL_CLIENTIn this example above a Pool with authenticated activated connects to a remote Keycloak instance and uses its custom realm and resource.
Entries in the "applicationConfig" value are written directly to a configMap that is part of the Helm deployment.
This can be a problem if you want to overwrite configuration properties with secrets.
Therefore, you can specify secret configuration values in a different Helm value applicationSecrets.
Content of this value is written in a Kubernetes secret instead.
If you want to specify a custom database password for example:
applicationSecrets:
spring:
datasource:
password: your_database_secretOn default, the Helm deployment also contains a PostgreSQL and Opensearch deployment.
You can configure these deployments in your value file as well.
For this, consider the documentation of the correspondent dependency PostgreSQL or Opensearch.
In case you want to use an already deployed database or Opensearch instance you can also disable the respective dependency and overwrite the default host address in the applicationConfig:
applicationConfig:
spring:
datasource:
url: jdbc:postgresql://remote.host.net:5432/bpdm
postgres:
enabled: falseThe BPDM Gate offers an API for Catena-X members to share their own business partner data with Catena-X. Such members are called sharing members. Via the Gate service they can add their own business partner records but also retrieve cleaned and enhanced data back in return over the sharing process. Shared business partner records that have successfully gone through the sharing process end up in the BPDM Pool and will receive a BPN there (or merge with an existing record).
BPDM is a SpringBoot Kotlin software project managed by Maven and can be run with the following command: mvn clean spring-boot:run
-
Maven
-
JDK17
-
Connection to CDQ API v4.0
-
Connection to BPDM Pool API
-
Keycloak 17.0.0 (with enabled
authorpool-authprofile)
When running, the BPDM Gate requires a remote CDQ storage and datasource to exchange data with.
Per default configuration the application connects to the host address https://api.cdq.com
and expects the environment variables BPDM_CDQ_STORAGE and BPDM_CDQ_DATASOURCE to contain the identifiers for the storage and datasource respectively.
The Gate also requires a connection to a BPDM Pool instance which is expected at localhost with port 8080 on default configuration.
You can find and edit the default configuration for the Gate in the application.properties, application-auth.properties and application-pool-auth.properties files in the resources folder.
The REST API documentation can be accessed at http://localhost:8081/api/swagger-ui.
The default configuration of the application is determined by the application.properties file.
Here you can find core application configuration such as Swagger documentation, CDQ and BPDM Pool connection.
You can also run the project with Spring profiles to enable additional components on top of the default configuration.
Currently, the BPDM Gate offers the profiles auth and auth-pool.
In order to run the application with a specific profile you can use the appropriate maven flag Dspring.profiles.active.
For example, the command mvn clean spring-boot:run -Dspring.profiles.active=auth starts the application with additional auth configuration enabled.
You can also run several profiles at once, of course: mvn clean spring-boot:run -Dspring.profiles.active=auth,auth-pool.
The following sections detail the configuration properties for each profile.
application-auth.properties enables authorization of endpoints and configures the connection to a Keycloak instance on which the authorization relies on.
The application expects the Keycloak to run on localhost on port 8180 and needs a client secret has to be submitted via environment variable BPDM_KEYCLOAK_SECRET.
But keep in mind that the connection to the Keycloak can be freely configured.
The application uses the configured auth server URL to validate incoming tokens.
For authorization purposes the application checks incoming token’s permissions:
-
change_company_data: For endpoints adding or updating business partner data
-
view_company_data: For endpoints reading the original unrefined business partner data
-
view_shared_data: For endpoints reading the business partner data which has been cleaned and refined through the sharing process
The BPDM Pool looks for these permissions in the client/resource and not on the realm level.
This profile also enables/disables the login form in the auto-generated Swagger documentation.
The Swagger login uses the client specified in the property springdoc.swagger-ui.oauth.client-id.
On default configuration, the BPDM Gate expects the API of the BPDM Pool to be accessible without authorization requirements.
In case the Pool instance to connect to have authorization activated, you need to activate this profile.
The file application-pool-auth.properties configures the oAuth2 client for connecting to a secured BPDM Pool.
Per default, the client will try to acquire a token via client credentials flow and expects the environment variable BPDM_KEYCLOAK_SECRET to contain the secret for the client.
This repository contains Helm files for deploying the BPDM Gate to a Kubernetes environment.
-
CDQ Storage and datasource
-
Running BPDM Pool instance
For the default deployment you need to specify a valid CDQ storage, datasource and API key for the application to connect with.
The easiest way to provide this information is by creating your own values files and overwrite the default applicationConfig and applicationSecrets values.
applicationConfig:
bpdm:
cdq:
storage: your_storage_id
datasource: your_datasource_id
applicationSecrets:
bpdm:
cdq:
api-key: your_api_keyGiven such a values file you can deploy the application via the following command:
helm install release_name ./charts/gate --namespace your_namespace -f /path/to/my_release-values.yamlThis will install a new release of the BPDM Gate in the given namespace.
On default values this release deploys the latest image tagged as main from the repository’s GitHub Container Registry.
The application is run on default profile (without authorization for its own endpoints or BPDM Pool endpoints).
This deployment requires a BPDM Pool deployment to be reachable under host name bpdm-pool on port 8080.
By giving your own values file you can configure the Helm deployment of the BPDM Gate freely. In the following sections you can have a look at the most important configuration options.
Per default, the Helm deployment references the latest BPDM gate release tagged as main.
This tag follows the latest version of the Gate and contains the newest features and bug fixes.
You might want to switch to a more stable release tag instead for your deployment.
In your values file you can overwrite the default tag:
image:
tag: "v2.0.2"You can also activate Spring profiles in which the BPDM Gate should be run. In case you want to run the Gate with authorization and oAuth Pool client enabled you can write the following:
springProfiles:
- auth
- pool-authYou can specify your own ingress configuration for the Helm deployment to make the BPDM Gate available over Ingress. Note that you need to have the appropriate Ingress controller installed in your cluster first. For example, consider a Kubernetes cluster with an Ingress-Nginx installed. An Ingress configuration for the Gate deployment could look like this:
ingress:
enabled: true
annotations:
kubernetes.io/ingress.class: nginx
nginx.ingress.kubernetes.io/backend-protocol: "HTTP"
hosts:
- host: partners-gate.your-domain.net
paths:
- path: /
pathType: PrefixFor the default deployment you already need to overwrite the configuration properties of the application.
The Helm deployment comes with the ability to configure the BPDM Gate application directly over the values file.
This way you are able to overwrite any configuration property of the application.properties, application-auth.properties and application-pool-auth.properties files.
Consider that you would need to turn on auth and pool-auth profile first before overwriting any property in the corresponding properties file could take effect.
Overwriting configuration properties can be useful for connecting to a remotely hosted BPDM Pool instance:
applicationConfig:
bpdm:
pool:
base-url: http://remote.domain.net/api/catenaEntries in the "applicationConfig" value are written directly to a configMap that is part of the Helm deployment.
This can be a problem if you want to overwrite configuration properties with secrets.
Therefore, you can specify secret configuration values in a different Helm value applicationSecrets.
Content of this value is written in a Kubernetes secret instead.
If you want to specify a keycloak client secret for example:
applicationSecrets:
bpdm:
security:
credentials:
secret: your_client_secretFor releasing new Docker images of the BPDM Pool and Gate we use GitHub Actions/Workflows, by convention found in the .github/workflows folder.
On pushing to the main branch or creating a new Git tag the applications are containerized and pushed to the repository’s GitHub Container Registry.
The containerization of the applications is based on the Dockerfiles found in the root folders of the Pool and Gate modules.
Released images are tagged according to the main branch or Git tag name.
In addition to the release of the applications' Docker images, there is also a workflow to release a corresponding Helm chart on Git tag creation.
Helm charts are released via the helm/chart-releaser-action and are stored in the gh-pages branch of the repository.
Furthermore, apart from the release workflows there also exists code scanning workflows for quality assurance:
-
Before any release of Docker images GitHub executes unit and integration tests.
-
Periodically, workflows execute a KICS and Trivy scan to ensure quality standards of the Docker images and Helm charts.
-
For a more thorough security check the packaged applications are send to a VeraCode scan, which happens periodically and after a push to main
Licenses of all maven dependencies need to be approved by eclipse. The Eclipse Dash License Tool can be used to check the license approval status of dependencies and to request reviews by the intellectual property team.
mvn org.eclipse.dash:license-tool-plugin:license-check -Ddash.summary=DEPENDENCIESmvn org.eclipse.dash:license-tool-plugin:license-check -Ddash.iplab.token=<token>Check the Eclipse Dash License Tool documentation for more detailed information.