Skip to content

Setup MDS EDC Connector

Jump to bottom
D.Hommen edited this page Oct 21, 2024 · 19 revisions

To access the Mobility Data Space in a convenient way you have to install and configure the MDS Version of the Eclipse Dataspace Connector.

These instructions provide a brief overview of the steps necessary to get a local instance of the MDS EDC Connector running. At the end of the guide, there are also tips for a deployment in a company infrastructure.

Expected audience of this tutorial: We assume, the reader of this tutorial to be familiar with software development and software deployment in corporate infrastructures. Thus, no introduction is given to setup the basics like Java, Docker, etc. Please also take measures to secure the Connector (change default passwords etc.)

MDS Test environment

1. Get your docker-compose

Download the docker-compose.yml

2. Extract

Unzip the contents of the downloaded archive.

3. Adjust your docker-compose

Open the docker-compose.yaml file and re-configure your Connector meta data

Use the data you saved after the connector registration to adjust the following attributes (settings are preconfigured for the test environement)

    MY_EDC_PARTICIPANT_ID: [The value of this variable must correspond to the MDS-ID assigned to you by MDS]
    EDC_OAUTH_TOKEN_URL: https://daps-next.test.mobility-dataspace.eu/realms/DAPS/protocol/openid-connect/token
    EDC_OAUTH_PROVIDER_JWKS_URL: https://daps-next.test.mobility-dataspace.eu/realms/DAPS/protocol/openid-connect/certs
    EDC_LOGGINGHOUSE_EXTENSION_URL: https://clearing-next.test.mobility-dataspace.eu

Note: Please read this hint if you are going to change the MY_EDC_PARTICIPANT_ID value later.

Adjust the Connector name, description, company details, Connector domain and API keys. Use the (sub)domain name you defined by deployment planning as Connector domain. Please use the same company name as MY_EDC_CURATOR_NAME as registered in the MDS Portal.

  # Connector Localized Name / Title
  MY_EDC_TITLE: "EDC Connector"

  # Connector Description Text
  MY_EDC_DESCRIPTION: "Community Edition EDC Connector by sovity"

  # Connector Curator
  # The company using the EDC Connector, configuring data offers, etc.
  MY_EDC_CURATOR_URL: "https://yourcompany.de"
  MY_EDC_CURATOR_NAME: "Your Company GmbH"

  # Connector Maintainer
  # The company hosting the EDC Connector
  MY_EDC_MAINTAINER_URL: "https://example.com"
  MY_EDC_MAINTAINER_NAME: "Example GmbH"

  # Connector Domain
  MY_EDC_FQDN: "[your connector domain]"
  EDC_UI_MANAGEMENT_API_URL: https://[your connector domain]/api/management
  EDC_DSP_CALLBACK_ADDRESS: https://[your connector domain]/api/dsp

  # Management API Keys
  # high entropy recommended when configuring the value (length, complexity, e.g. [a-zA-Z0-9+special chars]{32+ chars})
  EDC_UI_MANAGEMENT_API_KEY: [your API Key value]
  EDC_API_AUTH_KEY: [your API Key value]

Use your certificate

  • Make sure you're on Linux or on a bash console (e.g. WSL or Git Bash) and have openssl and keytool installed (you can use chocolatey to easily install openssl and keytool)
  • Download the following script: Generate SKI AKI
  • Run the script ./generate_ski_aki.sh [filepath].p12 [password] and substitute [filepath] to the p12 certificate filepath and [password] to the certificate password.
  • The jks file will be generated in the same folder as your p12 file and the SKI/AKI combination is printed out in the console.
  • Move the generated keystore jks file to the same folder as the docker-compose.yaml and please name the jks file to keystore.jks. Alternatively, the first part of the volume specification of the keystore entry of the edc in the docker-compose.yaml would have to be adjusted accordingly to the name and path of the keystore file, so it get's mounted into the edc docker container.
    EDC_OAUTH_CLIENT_ID: [Copy the SKI:AKI combination you have just generated]
    EDC_KEYSTORE_PASSWORD: [Adjust to your selected keystore password].

4. Start your EDC using docker

  • Login into GitHub Container Registry (GHCR): $ docker login ghcr.io You can also login using a GitHub token: echo [token] | docker login ghcr.io -u [username] --password-stdin
  • Fetch latest images via $ docker compose pull in the docker-compose file folder
  • Start via $ docker compose up in the docker-compose file folder
  • Open the MDS EDC Frontend (by default under http://localhost:11000/dashboard)

image

Congratulations! You are now running the MDS version of the EDC connector.

For further information (a.o. our Postman collection) see our Q&A section.

MDS Productive environment

Use the data you saved after the connector registration to adjust the following attributes (settings are preconfigured for the productive environement)

    MY_EDC_PARTICIPANT_ID: [The value of this variable must correspond to the MDS-ID assigned to you by MDS]
    EDC_OAUTH_TOKEN_URL: https://daps-next.mobility-dataspace.eu/realms/DAPS/protocol/openid-connect/token
    EDC_OAUTH_PROVIDER_JWKS_URL: https://daps-next.mobility-dataspace.eu/realms/DAPS/protocol/openid-connect/certs
    EDC_LOGGINGHOUSE_EXTENSION_URL: https://clearing-next.mobility-dataspace.eu

Then follow the steps for obtaining a certificate for the MDS Productive Environment and the steps above under Use your certificate and replace your test certificate with the productive one.

Tips for a deployment in the company infrastructure

The requirements and concrete steps needed for the deployment of an EDC in a company infrastructure depend on the details of the company infrastructure itself, for example whether an Azure-Cluster or an AWS-Cluster is used or the server is set up manually on-premises. Therefore, we can only give general advice here on what needs to be taken into account and what must definitely be present in the infrastructure in some way.

Deployment Units

  • Auth Proxy: auth solution of your choice - required to secure the Connector-UI and Management-API, so they are not openly accessible to everyone on the Internet
  • Reverse Proxy: merges multiple services and removes the ports - the Connector-Backend opens up ports with different functionalities. They are expected to be merged by a reverse proxy, at least the connector-protocol-endpoint needs to be
  • Postgresql DB: a database to persistently store the EDC's metadata, such as asset metainformation
  • EDC Backend: the EDC itself, which can be addressed via the Management-API (from behind auth proxy) and the connector-protocol-endpoint (via internet from other connectors). Includes the data-plane as well as the control-plane.
  • EDC UI: The UI belonging to the EDC backend to interact via a UI with the EDC backend instead of using its Management-APIs directly

Reverse Proxy Configuration

  • The MDS variant of the EDC Connector is meant to be deployed with a reverse proxy merging the following ports:
    • The UI's 8080 port. Henceforth, called the UI.
    • The Backend's 11002 port. Henceforth, called the Management API.
    • The Backend's 11003 port. Henceforth, called the Protocol API.
  • The mapping should look like this:
    • https://[MY_EDC_FQDN]/api/dsp -> edc:11003/api/dsp
    • https://[MY_EDC_FQDN]/api/management -> Auth Proxy -> edc:11002/api/management
    • All other requests -> Auth Proxy -> edc-ui:80
  • Regarding TLS/HTTPS:
    • All endpoints need to be secured by TLS/HTTPS. A productive connector won't work without it.
    • All endpoint should have HTTP to HTTPS redirects.
  • Regarding Authentication:
    • The UI and the Management API need to be secured by an auth proxy. Otherwise, access to either would mean full control of the application.
    • The backend's 11003 port needs to be unsecured. Authentication between connectors is done via the Data Space Authority / DAPS and the configured certificates.
  • Exposing to the internet:
    • The Protocol API must be reachable via the internet.
    • Exposing the UI or the Management Endpoint to the internet requires an intermediate auth proxy.

Adjustment of parameters

If the EDC is deployed in a company infrastructure, regardless of what the infrastructure actually looks like, some of the parameters also present in the docker-compose must be adjusted, to no longer point to localhost.

  • (edc-ui) EDC_UI_MANAGEMENT_API_URL: Must point to the management API of the running EDC backend instead of localhost
  • (edc) MY_EDC_JDBC_URL: JDBC settings like MY_EDC_JDBC_URL must point to the PostgreSQL DB deployed
  • (edc) MY_EDC_PROTOCOL: should be changed to https:// instead of http:// for an infrastructure deployment

Ready-made templates for the deployment

You can use this template to deploy the connector with Traefik reverse proxy.

You can also use this template to deploy the connector with Traefik reverse proxy und oauth2 proxy

Clone this wiki locally