Recommended Configuration parameters

Environment Settings

The settings in this section apply to both the classic XDM UI and the Prime UI.
EnvironmentID

The environment ID is a technical identifier that distinguishes one XDM installation or runtime environment (for example DEV, TEST, or PROD) from another. It is used by scripts, workflows, and automation logic to adapt behavior depending on where XDM is running.

It should be unique and stable for each environment. Use short, descriptive values such as DEV, TEST, or PROD so that scripts and reports can reliably detect the current environment and apply the correct logic or restrictions.

Name

Sets the environment name for the XDM installation. The name is used to visually and logically distinguish different XDM installations (DEV / TEST / PROD) and to integrate with Configuration as Code (CasC).

Each XDM installation can have a specific environment name that is displayed in the UI. This makes it easier to differentiate between different XDM installations, for example for a production and test environment.

Color

Set the primary color of the XDM UI. It is recommended to use a different coloring for the different XDM installations. This setting applies to both the classic XDM UI and the Prime UI.

  • PrimeUI

  • ClassicUI

For the Prime UI, the following predefined colors are available:

  • red

  • emerald

  • green

  • lime

  • orange

  • amber

  • yellow

  • teal

  • cyan

  • sky

  • blue

  • indigo

  • violet

  • purple

  • fuchsia

  • pink

  • rose

  • ubs

  • noir

For the classic XDM UI, the following predefined colors are available:

  • violet

  • red

  • blue

  • gray

  • green

Alternatively, you can use a valid CSS color definition. In the Prime UI, RGB and hex code color definitions are supported for custom colors. See Color palette and Color syntax for more information. Please consider that the text for the menu entries is always white, so the color should be chosen accordingly. For color names from CSS that are equal to the predefined colors, the predefined colors will be used.

In the classic XDM UI, the secondary column color (used for the background of the side menu footer) can be set using CSS color definitions with the variable secondary_environment_color. The default secondary color is black. In the Prime UI, secondary_environment_color is not supported. The side menu footer background cannot be configured separately.

  • Kubernetes

  • Docker

Parameters:

  • xdm.environment.id

  • xdm.environment.name

  • xdm.environment.color

    xdm:
  environment:
    id: DEV
    name: DEV
    color: green

Parameters:

  • xdm.core.environment-id

  • environment_name

  • environment_color

    services:
  core-server:
    environment:
      - xdm.core.environment-id=DEV
  web-ui:
    environment:
      - environment_name=DEV
      - environment_color=green

Execution concurrency and DB pool size

XDM allows parallel execution of tasks, hence several processes run on the dataflow server at the same time. Since the computing capacity of the dataflow server is not unlimited, the maximum number of parallel running tasks should be restricted.

Specify the parameter to limit the number of concurrent running tasks. It controls how many tasks can run simultaneously. As soon as more task executions are triggered than the maximum allowed, the surplus tasks are collected in a queue and processed sequentially as capacity allows.

The default value for the parameter is 5. A value of 0 indicates that no task executions are queued. In this case each task execution is executed immediately.

Due to technical reasons, the maximum number of concurrent tasks in the dataflow server is 20. Therefore, the maximum value for this parameter is 20. A higher value has no effect on the number of parallel executed tasks and can lead to dataflow aborts.

Depending on this parameter, the maximum pool size must be set in the dataflow server configuration. It controls the number of open connections from the dataflow service to the admin database. Each active execution requires one open connection. As a general rule, use the number of concurrent tasks + 5.

  • Kubernetes

  • Docker

Parameters:

  • execution.concurrent

  • DB pool size configured for dataflow (chart‑specific)

    execution:
  concurrent: 5

Parameters:

  • xdm.core.execution.concurrent-tasks

  • spring.datasource.hikari.maximumPoolSize

    services:
  core-server:
    environment:
      - xdm.core.execution.concurrent-tasks=5
  dataflow-server:
    environment:
      - spring.datasource.hikari.maximumPoolSize=10

Execution retention and cleanup cron

Controls how long task/workflow executions, logs and work directories are kept and when automatic cleanup runs.

XDM can automatically delete task and workflow executions and associated work files. You can specify a retention period, after which log files and other files associated with a specific execution are deleted.

By default, the automatic cleanup function is not enabled. To activate it, set the executionRetentionPeriod in your environment.

The retention period specify that task and workflow executions should be deleted after the specified period of time. If an execution is older than the specified retention period, the XDM service will delete the task execution including the working directories and log files of that execution. The value must start with P for a date period or with PT with a time period. It is based on the ISO-8601 duration format.

Examples:

  • P2D: Period for 2 days.

  • PT15M: Period for 15 minutes.

  • PT1H10M: Period for 1 hour and 10 minutes.

    XDM name:

    executionRetentionPeriod

    Type:

    String

    Default value:

    -1 (no execution were deleted)

The cron expression xdm.execution.cleanup-cron controls the execution of the process that cleans up the expired executions. It specifies what time the process that deletes old executions runs. All executions older than the specified executionRetentionPeriod will be deleted by this process.

The executionRetentionPeriod setting defines a period of time that controls how long an execution should be kept after it is automatically deleted. This setting can be configured globally, at template level or for specific tasks/workflows.

The cron expression controls the execution of the process that cleans up the expired executions. It specifies what time the process that deletes old executions runs. All executions older than the specified executionRetentionPeriod will be deleted by this process.

By default, the cleanup process runs every day at midnight. The default cron expression is 0 0 0 * * ?.

For very short retention periods, it is possible that the cleanup process for a task execution is triggered before the task execution has finished. In this case, XDM will wait for the task to finish before attempting to clean up again.

By default, the wait time before another cleanup attempt is made is 10 seconds. The wait time in seconds can be customized by specifying xdm.core.cleanupWaitTime.

When a task or a task template is deleted, the default behavior of XDM is to retain the task work files and logs. If you want XDM to delete these files when a task or a task template is deleted, specify xdm.core.cleanup-executions-on-task-delete.

If the parameter is missing, or if it is set to false, XDM will not delete any task work files or logs when a task or a task template is deleted.

  • Kubernetes

  • Docker

Parameters:

  • execution.retentionPeriod

  • execution.cleanupCron

  • execution.cleanup-executions-on-task-delete (optional)

execution:
  retentionPeriod: P30D
  cleanupCron: "0 0 0 * * ?"#

core-server:
  environment:
    cleanup-executions-on-task-delete: true

Parameters:

  • xdm.core.executionRetentionPeriod

  • xdm.execution.cleanup-cron

  • xdm.core.cleanup-executions-on-task-delete (optional)

    services:
  core-server:
    environment:
      - xdm.core.executionRetentionPeriod=P30D
      - xdm.execution.cleanup-cron=0 0 0 * * ?
      - xdm.core.cleanup-executions-on-task-delete=true

Define the execution cleanup process interval

The executionRetentionPeriod setting defines a period of time that controls how long an execution should be kept after it is automatically deleted. This setting can be configured globally, at template level or for specific tasks/workflows.

The cron expression controls the execution of the process that cleans up the expired executions. It specifies what time the process that deletes old executions runs. All executions older than the specified executionRetentionPeriod will be deleted by this process.

By default, the cleanup process runs every day at midnight. The default cron expression is 0 0 0 * * ?.

xdm.execution.cleanup-cron=0 0 0 * * ?
Task executions waiting in the queue are lost after restarting the dataflow server.

Specify the polling interval

The Dataflow Server periodically checks whether a task is still running. The waiting time between these periods can be set using the following parameter:

xdm.core.execution.polling-interval=<seconds>

The parameter <seconds> specifies how many seconds the process waits between the checks. By default, this parameter is set to 5 seconds.

This parameter only needs to be adjusted in rare cases. By default, a value of 5 seconds is sufficient to check whether a task is still running or not. The parameter should be set to a lower value if a large number of fast running tasks are to be executed and the waiting time for the user should be reduced.

Pre-execution checking from workflows

Every time before an execution starts, a pre-execution check will be executed to determine whether the task is correctly configured or not. This check can be deactivated for tasks started from workflows with the following boolean parameter:

xdm.execution.workflow-pre-check=false

Grafana and Prometheus (optional monitoring)

XDM can ship with Grafana and Prometheus for internal monitoring and dashboards. They are recommended but not required for core functionality.

Grafana is a cross-platform open source application for graphical representation of data from various data sources such as PostgreSQL or Prometheus.

The Grafana service uses tables of XDM’s admin database as a data source.

  • Kubernetes

  • Docker

Parameters:

  • enabled: Controls if an own Kubernetes pod is started with Grafana. This is not necessary if no graphical display of statistic data is required.

  • jsonData: Optional parameter to define own jsonData for the built-in data source of the administration database. More details how to configure a PostgresQL data source can be found here.

    If jsonData is specified, the database entry must be included within the jsonData block. If the database entry is missing, the Grafana Query Builder will not function properly. In particular, it will not display any tables or columns in the corresponding drop down list.

Parameters:

  • xdm.core.grafana.serverUri: Defines the URL of the Grafana service. This URL has to include the context path and always ends with reports/.

    Since XDM provides a link for reaching Grafana and both services share the user management, XDM needs to know how to reach Grafana. Therefore, the following settings are needed in the environment section of the core-server.

  • xdm_grafana_serverUri: Defines the URL of the Grafana service including the port for the Web UI. There will be a link from the user interface to the Grafana dashboard. Therefore, this setting is needed.

  • POSTGRES_URL: Specifies the host name, and port of the server running XDM’s administration database. When using docker, this is the name of the service running the admin database.

  • POSTGRES_DATABASE: Specifies the name of the administration database.

  • POSTGRES_USER: Specifies a username for database access.

  • POSTGRES_PASSWORD: Specifies the password for the user.

  • PROMETHEUS_URL: Specifies the url for the prometheus service.

  • GF_SERVER_ROOT_URL: Specifies the complete Grafana URL but is only needed when XDM is served from a context path!

    Grafana requires a user to read the administration database. For security reasons, this user should have read-only access to the database.

    The following example shows the relevant part of the default docker-compose.yml file. Here, XDM can be accessed under the context path xdm, so the Grafana configuration also has to include this context path. Without using a context path, the URL would become http://report-dashboard:3000/reports/.

    The built-in data source for Grafana can only be used with a PostgreSQL database. Other administration databases need a special setup.

  • POSTGRES_JSON_DATA:

    Optionally, it is possible to configure the values for jsonData yourself for the built-in data source of the administration database. By default, the sslmode is set to disabled and the postgresVersion to version 15. The default for database is xdm, but it can be set to any other database name if needed. If one of these values in POSTGRES_JSON_DATA needs to be changed, it is important to set the database value to the same database name as specified in POSTGRES_DATABASE, otherwise Grafana will not be able to connect to the database. More details on how to configure a PostgresQL data source can be found here.

    To configure your own jsonData values, the following must be added to the environment section of Grafana:

    environment:
   - POSTGRES_JSON_DATA="{\"sslmode\":\"disable\",\"postgresVersion\":1500,\"database\":\"xdm\"}"

Docker properties

Customizing Grafana

In XDM, Grafana is running as a Docker container. As a result, customization via the grafana.ini file, as described in the Grafana documentation, is not supported directly, because the file is packaged within the container image and cannot be modified in place.

Instead, all settings available in grafana.ini can be configured using environment variables. These variables can be defined in the docker-compose.yml file or in the Helm charts used for Kubernetes deployments. This works like the following schema shows:

GF_<SECTION>_<KEY>
GF_ – Always at the beginning.
<SECTION> – The name of the section in square brackets from grafana.ini (e.g., [smtp], [auth.google], [server]).
<KEY> – The specific setting key within that section (e.g., host, user, root_url).

Details:

  • Everything is written in UPPERCASE letters.

  • Any dots (.) or dashes (-) are replaced by underscores (_).

  • For compound keys like root_url, just convert to uppercase: ROOT_URL

Example how to customize an SMTP server in Grafana

This example in Grafana’s documentation shows how to customize an alert notification via email: Configure email for alert notifications

The following example shows how the SMTP server can be customized via the environment variables:

environment:
   - GF_SMTP_ENABLED=true
   - GF_SMTP_HOST=smtp.example.com:587
   - GF_SMTP_USER=youruser@example.com
   - GF_SMTP_PASSWORD=your_password
   - GF_SMTP_SKIP_VERIFY=false         # may be true for self signed certificates
   - GF_SMTP_FROM_ADDRESS=grafana@example.com
   - GF_SMTP_FROM_NAME=Grafana
   # Optional (required at some STMP servers):
   - GF_SMTP_EHLO_IDENTITY=grafana.example.com

Prometheus configuration

Prometheus is a data/metric collector service. It stores metric values over time that can later be visualized by the reporting service of XDM3. Prometheus collects metrics from the java virtual machine (JVM) and from the Spring services that is running the XDM3 core and dataflow server.

The service has to be configured in the docker-compose.yml file.

If you are using HTTPS for internal communication, change the CORE_URL and DATAFLOW_URL to https.

The following parameters can be set in the configuration:

CORE_URL

Specifies the url for the core server.

DATAFLOW_URL

Specifies the url for the dataflow server.

enabled

Controls if an own pod is started with Prometheus.

Optional parameters are GRAPH_STORE_URL, WEBSERVICE_EXTRACT_SOURCE_URL, WEBSERVICE_APPLY_SINK_URL,GENERATOR_SOURCE_URL,FILE_SINK_URL and MODIFICATION_PROCESSOR_URL.

Example

  • Kubernetes

  • Docker

Parameters:

  • grafana.enabled, grafana.jsonData

  • prometheus.enabled

    Parameters set in the helm chart that can be overwritten in values.yaml:

  • Core-Server:

    • xdm.core.grafana.serverUri

  • Web-UI:

    • xdm_grafana_serverUri

  • Grafana:

    • POSTGRES_URL

    • POSTGRES_DATABASE

    • POSTGRES_USER

    • POSTGRES_PASSWORD

    • PROMETHEUS_URL

    • GF_SERVER_ROOT_URL

    • POSTGRES_JSON_DATA (optional)

  • Prometheus:

    • CORE_URL

    • DATAFLOW_URL

      grafana:
  enabled: true
  # optional: override jsonData for PostgreSQL data source
  jsonData:
    database: xdm-db
    sslmode: disable
    postgresVersion: 1200

prometheus:
  enabled: true

Parameters:

  • Core-Server:

    • xdm.core.grafana.serverUri

  • Web-UI:

    • xdm_grafana_serverUri

  • Grafana:

    • POSTGRES_URL

    • POSTGRES_DATABASE

    • POSTGRES_USER

    • POSTGRES_PASSWORD

    • PROMETHEUS_URL

    • GF_SERVER_ROOT_URL

    • POSTGRES_JSON_DATA (optional)

  • Prometheus:

    • CORE_URL

    • DATAFLOW_URL

      services:
  core-server:
    environment:
       - xdm.core.grafana.serverUri=http://report-dashboard:3000/xdm/reports/

  web-ui:
   environment:
      - xdm_grafana_serverUri=http://grafana:3000

  grafana:
    image: docker.ubs-hainer.com/xdm3-grafana:latest
    environment:
      - POSTGRES_URL=xdm-db:5432
      - POSTGRES_DATABASE=xdm
      - POSTGRES_USER=xdmro
      - POSTGRES_PASSWORD=xdmR0password
      - PROMETHEUS_URL=http://prometheus:9090
      - GF_SERVER_ROOT_URL=%(protocol)s://%(domain)s:%(http_port)s/xdm/reports/
      # Optional Parameter:
      - POSTGRES_JSON_DATA="{\"sslmode\":\"disable\",\"postgresVersion\":1200}"

  prometheus:
    image: docker.ubs-hainer.com/xdm3-prometheus:latest
    environment:
      - CORE_URL=http://core-server:8000
      - DATAFLOW_URL=http://dataflow-server:9393

JWT configuration (login and execution tokens)

XDM uses JSON Web Tokens to authorize users of the HTTP REST end points.

The JWT controls:

  • How long a user’s login session is valid.

  • How long internal execution tokens (core ↔ dataflow) are valid.

  • Which secret is used to sign tokens.

Login token expiration time

Specifies how many minutes the JWT token is valid. This token is generated by XDM, After a user has logged in. By default, the expiration time is 120 minutes.

Execution token expiration time

Specifies the expiration time of the execution token. This is used to authenticate executions between core and dataflow. The expiration time is specified in minutes. The default expiration time of this JWT is 1440 minutes.

Secret

Specifies the secret, with which the JWT token is generated and encrypted.

The secret must have at least 32 characters.

After changing the secret, you must restart the XDM core service for the change to take effect. After restarting the core service, all generated JWT tokens will be encrypted with the new secret.

Once a secret has been assigned for the JWT, it should not be changed since scheduled tasks use tokens for communication between the core server and the dataflow server. These tokens are created at the time when the task is scheduled. If the secret is changed, the already scheduled task will run into an error.

  • Kubernetes

  • Docker

Parameters:

  • security.jwt.expireTime

  • security.jwt.validTime

  • security.jwt.secret

    security:
  jwt:
    expireTime: 120        # minutes
    validTime: 1440        # minutes
    secret: "change_this_to_a_long_random_string"

Parameters:

  • xdm.core.jwt.token-expire-time

  • xdm.core.jwt.token-valid-time

  • xdm.core.jwt.secret

    services:
  core-server:
    environment:
      # UI login token (minutes)
      - xdm.core.jwt.token-expire-time=120
      # Execution token (minutes)
      - xdm.core.jwt.token-valid-time=1440
      # Secret (>= 32 characters)
      - xdm.core.jwt.secret=change_this_to_a_long_random_string

Persistence volumes and storage

XDM uses additional directories in its virtual file system which, by default, are not shared with the host system. It is possible to add or persist entries to the configuration in order to associate these directories with locations in your host file system. This allows easy data exchange between the host system, and the environment in which XDM runs.

The persistence volumes define, which directories should be persisted in XDM. These directories have to be persisted in XDM:

  • Task work directories

  • Backups / Icebox data

  • Admin DB data (if internal DB is used)

  • H2 tables if not stored in Mapping Table Container

  • Optional: Elasticsearch, Grafana, Neo4j graph

  • Kubernetes

  • Docker

Parameters:

  • persistence.* per volume: data, postgres, neo4j, sample, grafana, elasticsearch, graph_store (optional), file_sink (optional), loki (optional) and tempo (optional)

    For optional parameters, the enabled property can be used to control whether they are created or not, and the existingClaim property can be used to set them to an existing value. 
    persistence:
  data:
    storageClass: fast-storage
    accessMode: ReadWriteMany
    size: 100Gi

  postgres:
    storageClass: standard
    accessMode: ReadWriteOnce
    size: 50Gi

  neo4j:
    storageClass: standard
    accessMode: ReadWriteOnce
    size: 20Gi

  elasticsearch:
    storageClass: fast-ssd
    accessMode: ReadWriteOnce
    size: 50Gi

Parameters: volumes mounted to:

  • /xdm/tasks

  • /xdm/data

  • /xdm/backups

  • /xdm/mapping

  • /var/lib/postgresql/data (for xdm-db)

    services:
  core-server:
    volumes:
      - ./xdm-config:/xdm/config:ro
      - ./xdm-data:/xdm/data
      - ./xdm-tasks:/xdm/tasks
      - ./xdm-mapping:/xdm/mapping
  dataflow-server:
    volumes:
      - ./xdm-data:/xdm/data
      - ./xdm-tasks:/xdm/tasks
      - ./xdm-backups:/xdm/backups
      - ./xdm-mapping:/xdm/mapping
  xdm-db:
    volumes:
      - ./xdm-db-data:/var/lib/postgresql/data

Runner Deployment (only available for Docker)

Runner deployment

XDM supports the deployment of its xdm-runner via Spring Cloud DataFlow and Docker. Deployment via Spring Cloud DataFlow is the standard deployment method. Deployment via Docker uses the Docker-out-of-Docker (DooD) approach, which allows you to run the xdm-runner in a Docker container on your local host.

The runner provider can be configured in the core environment with the variable xdm.core.runner.provider. Possible values are:

LEGACY

Spring Cloud DataFlow REST API. This is the default runner provider, if the environment variable is not set.

DOCKER

Use the Docker API to start the xdm-runner in a Docker container on the local host.

To activate the Docker runner, the following variables must be set in the environment section of the core-server:

  - xdm.core.runner.provider=DOCKER
  - xdm_core_serverUri=http://core-server:8000/api/
  - xdm_loki_serverUri=http://loki:3100

When using the DOCKER runner provider, a configuration file runner.yaml has to be created in the xdm-config directory that is mounted on the core server.

The Spring Cloud DataFlow provider uses a configuration named "default" and does not require any configuration in the runner.yaml file. When switching from the Spring Cloud DataFlow to the DOCKER runner provider, a configuration named "default" must be provided in the runner.yaml file to be compatible with the existing task templates.
Please note that the Container socket proxy configuration is mandatory for using the DOCKER runner provider. For more information, see Container socket proxy configuration.

Runner configuration options

The runner.yaml configuration file can contain several (the main YAML structure is a list of) runner configurations. Each configuration has the following options:

  • executorType: The type of the executor to use for the runner.

  • name: The name of the runner configuration. This name is used to reference the configuration in the property Execution Platform of the task template. If not specified, "default" will be used as the name of the configuration. When using multiple configurations, each configuration must have a unique name.

  • defaultConfig: A boolean flag to indicate if this configuration should be used as the default runner configuration. If set to true, which is the default, this configuration will be used for all generic communication with the used runner API. The deployment of tasks and workflows will use the configuration referenced in the property Execution Platform. If there is only one configuration, it will be used as the default configuration and the flag can be omitted. When defining multiple configurations, only one of them can be marked as the default configuration. Naming one configuration as "default" and setting defaultConfig: true on another one will result in an error.

  • volumeMounts: A list of volume mounts to set for the runner. Each mount entry has a name, mountPath, readOnly, subPath field.

    • name: The path name of host directory to mount.

    • mountPath: The path inside the container where the volume should be mounted.

    • readOnly: A boolean flag to indicate if the volume should be mounted as read-only. If set to true, the volume will be mounted as read-only. The default value is false.

    • type: The type of the volume mount. Valid values are BIND and VOLUME. The default value is BIND.

  • resources: A map of resource requests and limits to set for the runner. Valid keys are memoryLimit, memorySwapLimit and cpuLimit.

    • memoryLimit: The maximum amount (MB) of memory that the container can use.

    • memorySwapLimit: The maximum amount (MB) of memory plus swap that the container can use.

  • environmentVariables: A map of environment variables to set for the runner. Each environment variable has a name and a value field.

  • repositoryUrl: The Docker repository URL. Default is docker.ubs-hainer.com.

  • image: The Docker image to use. Defaults to xdm3-runner.

  • imageTag: The tag of the Docker image to use. Defaults to latest.

  • imagePullPolicy: The image pull policy to use. Possible values are ALWAYS, IF_NOT_PRESENT and NEVER. Defaults to IF_NOT_PRESENT.

  • containerProxyName: The host and port of the Docker API to access. The value should be in the format tcp://host:port. Defaults to tcp://container-proxy:2375.

  • dockerNetworkName: The name of the Docker network to use for the runner.

  • dockerCredential: The credentials to use for accessing the Docker repository.

    • username: The username to use for accessing the Docker repository.

    • password: The password to use for accessing the Docker repository.

  • removeContainer: A boolean flag to control, if the runner container is removed automatically after task execution. Default is true.

  • executionUser: The executing user and group inside the runner container. The value should be in the format user:group.

Sample Docker configuration

The following lines show a minimal configuration for the DOCKER runner provider in the runner.yaml file.

Please make sure to adjust the host paths according to your installation. Relative paths are not supported and will result in an error.

The Docker Credentials have to be filled with the credentials that were provided to you.

- executorType: DOCKER
  name: "default"
  volumeMounts:
    - name: "/xdm/xdmconfig"
      mountPath: "/xdm/config"
    - name: "/xdm/xdmbackups"
      mountPath: "/xdm/backups"
    - name: "/xdm/xdmdata"
      mountPath: "/xdm/data"
    - name: "/xdm/xdmmapping"
      mountPath: "/xdm/mapping"
    - name: "/xdm/xdmtasks"
      mountPath: "/xdm/tasks"
  dockerCredential:
    username:
    password:
  resources:
    memoryLimit: 2048

Container socket proxy (only available for Docker)

The Docker socket is a sensitive resource that allows access to the Docker daemon, and it is crucial to secure the communication between the container and the Docker daemon. Therefore, a proxy service is used to mediate the communication and enforce security policies. XDM provides a pre-configured image xdm3-container-proxy using CetusGuard. CetusGuard is a tool that protects the Docker daemon socket by filtering calls to its API endpoints.

The service has to be configured in the docker-compose.yml file.

The communication between the proxy and the Docker daemon can be established using either a Docker socket or a TCP socket.

Using a Docker socket

When using a Docker socket, the socket file is mounted into the container and the CETUSGUARD_BACKEND_ADDR environment variable is set to point to the socket file. Therefore, the service configuration has to be extended as follows:

  • add a volume mount to mount the host’s Docker socket into the container. For example, if the Docker socket is located at /var/run/docker.sock on the host, it can be mounted to /sockets/docker/docker.sock inside the container.

  • add an environment variable to specify the address of the Docker socket inside the container. The CETUSGUARD_BACKEND_ADDR environment variable should be set to unix:///sockets/docker/docker.sock to point to the previously mounted socket file.

services:
    container-proxy:
        image: docker.ubs-hainer.com/xdm3-container-proxy:latest
        volumes:
          - "/var/run/docker.sock:/sockets/docker/docker.sock:ro"
        environment:
          - CETUSGUARD_BACKEND_ADDR: "unix:///sockets/docker/docker.sock"

TCP socket

When using a TCP socket, you need to add the extra_hosts configuration to make the Docker Gateway available inside the container. The CETUSGUARD_BACKEND_ADDR environment variable should be set to the address of the TCP socket.

services:
    container-proxy:
        image: docker.ubs-hainer.com/xdm3-container-proxy:latest
        extra_hosts:
            - "host.docker.internal:host-gateway"
        environment:
          - CETUSGUARD_BACKEND_ADDR: "tcp://host.docker.internal:2375"

Common configuration options

There are some common configuration options that can be used regardless of the communication method. When securing the communication with TLS, the certificates and keys have to be mounted into the container and the corresponding environment variables have to be set to point to the mounted files.

CETUSGUARD_LOG_LEVEL

The minimum entry level to log, from 0 (No logging) to 7 (Logging at DEBUG level).

CETUSGUARD_BACKEND_TLS_CACERT

Path to the backend TLS certificate used to verify the daemon identity

CETUSGUARD_BACKEND_TLS_CERT

Path to the backend TLS certificate used to authenticate with the daemon

CETUSGUARD_BACKEND_TLS_KEY

Path to the backend TLS key used to authenticate with the daemon

CETUSGUARD_FRONTEND_TLS_CACERT

Path to the frontend TLS certificate used to verify the identity of clients

CETUSGUARD_FRONTEND_TLS_CERT

Path to the frontend TLS certificate

CETUSGUARD_FRONTEND_TLS_KEY

Path to the frontend TLS key

The lines shown below are an example configuration for using TLS for the frontend communication. The certificates and keys are mounted into the container from the host’s ~/certs directory and the corresponding environment variables are set to point to the mounted files.

services:
    container-proxy:
        image: docker.ubs-hainer.com/xdm3-container-proxy:latest
        volumes:
          - "~/certs:/certs:ro"
        environment:
          - CETUSGUARD_FRONTEND_TLS_CACERT: /certs/frontend-ca.crt
          - CETUSGUARD_FRONTEND_TLS_CERT: /certs/frontend.crt
          - CETUSGUARD_FRONTEND_TLS_KEY: /certs/frontend.key

User management (local, LDAP, OAuth2/OpenID)

Each user that intends to work with XDM needs to a username and a password. The Authentication can either be performed by an LDAP server, OpenID provider or by using the internal user management of XDM.

LDAP configuration

XDM can use an LDAP server to authenticate users. The LDAP server controls which users exist and how they have to authenticate. The LDAP server also controls what roles a user is a member of.

To configure the connection to LDAP:

  • Kubernetes

  • Docker

 userManagement:
   ldap:
     enabled: true
     url: <ldap-server-url>
     searchFilter: <search-filter>
     searchBase: <search-base>
     group:
        searchBase: <group-search-base>
        searchFilter: <group-search-filter>
     manager:
        user: <manager-user>
        password: <manager-password>
        secret: <secret-name>
services:
  core-server:
   - ldap.url=ldap://<hostname>:<port>/<base_db>
   - ldap.search_filter=<filter>
   - ldap.search_base=<directory>
   - ldap.manager.user=<username>
   - ldap.manager.password=<password>
   - ldap.group.search_base=<base> (optional)
   - ldap.group.search_filter=<filters> (optional)
ldap.url (Docker)/ ldap-server-url (Kubernetes)

Set <hostname> and <port> to the host name and port of your LDAP server. Set <base_db> to the distinguished name of the entry that is starting point of the search. You can use the ldaps protocol instead of ldap. Example: ldap://ldap.mycompany.com:389/dc=mycompany,dc=com

ldap.search_filter (Docker)/ search-filter (Kubernetes)

The search filter for the users. Example: uid={0}

ldap-search_base (Docker)/ search-base (Kubernetes)

The LDAP directory from which each search will start. If left empty, searches can take longer. Typically, cn=Users is a good value for search_base.

ldap.manager.user (Docker)/ manager-user (Kubernetes)

The username for the LDAP server, if it requires a login

ldap.manager.password (Docker)/ manager-password (Kubernetes)

The username for the LDAP server, if it requires a login

ldap.group.search_base (Docker, optional)/ group-search-base (Kubernetes)

Defines the part of the directory tree, under which group searches should be performed.

ldap.group.search_filter (Docker, optional)/ group-search-filter (Kubernetes)

The filter that is used to search for group membership. The default is uniqueMember={0}.

manager-secret (Kubernetes)

If the LDAP server requires a login, a Kubernetes secret can be used as an alternative to storing the login credentials as plaintext. The name of the secret can be chosen freely but must contain the keys 'username' and 'password'.

Details on the use of these properties can be found in the Spring LDAP documentation.

If you specify the username and password for the LDAP server in a plain text file, you should restrict access to this file using the access control mechanisms of your operating system to prevent unauthorized users from accessing the file.

To test your settings, you can use the ldapsearch utility. This utility is available in all Microsoft Windows Enterprise versions, and under Linux.

Use this command:

ldapsearch -x -h <ldap_host> -p <ldap_port> -D "<ldap_admin_user>" -w
"<ldap_admin_password>" -b "<base_dn>" "(cn=<user_name_to_lookup>)"

This command will establish a connection to the specified LDAP and retrieve information about the user specified under <user_name_to_lookup>.

If the LDAP server requires a login, a Kubernetes secret can be used as an alternative to storing the login credentials as plaintext. The name of the secret can be chosen freely but must contain the keys 'username' and 'password'.

SSL/TLS Configuration

In order to establish an encrypted connection via SSL to an LDAP server, further configuration is necessary. For this, one or more certificate is required for the client (core-server) to establish a connection to the LDAP server. The installation of certificates see chapter installation of certificates.

Example

Invoke the following command in a shell:

ldapsearch -x -h ldap.mycompany.com -p 3268 -D "myldapuser" -w "myldappassword" -b "dc=intranet,dc=mycompany,dc=com" "(cn=demouser)"

The result might look similar to this:

CN=demouser,CN=Users,DC=intranet,DC=mycompany,DC=com
objectClass=top
objectClass=person
objectClass=organizationalPerson
objectClass=user
cn=demouser
distinguishedName=CN=demouser,CN=Users,DC=intranet,DC=mycompany,DC=com
instanceType=4
whenCreated=20150729072952.0Z
whenChanged=20150729072952.0Z
displayName=demouser
uSNCreated=8201
memberOf=CN=Users,CN=Builtin,DC=intranet,DC=mycompany,DC=com
uSNChanged=8201
name=demouser
objectGUID=NOT ASCII
userAccountControl=544
primaryGroupID=513
objectSid=NOT ASCII
sAMAccountName=demouser
sAMAccountType=805306368
objectCategory=CN=Person,CN=Schema,CN=Configuration,DC=intranet,DC=mycompany,DC=com
dSCorePropagationData=20150729073055.0Z
dSCorePropagationData=16010101000001.0Z

To get all the necessary groups for a user, the group search base and group search filter need to be set. Those filters should return a list of all groups in the LDAP the user belongs to, and the groups that should be used for group related permission settings in XDM.

The ldapsearch utility can be used as follows for a group search:

ldapsearch -h ldap.mycompany.com -p 3268 -D "myldapuser" -w "myldappassword" -b "dc=intranet,dc=mycompany,dc=com" "(&(&(objectClass=group)(member=CN=U123456,OU=Users,dc=intranet,dc=mycompany,dc=com))(name=XDM*))"

This searches for all groups the user U123456 belongs to, and the group name starts with XDM

OpenID connect authentication configuration

XDM supports the user authentication with an external OpenID Connect provider. XDM forwards login requests to the configured OpenID Connect provider and the user needs to log in at that system. After a successful login the OpenID system redirects to XDM. These settings must be configured with options that are described in this section.

As a prerequisite for using an OpenID provider with XDM, some information must be set and defined in the provider. Here the corresponding client to be used for the authentication within XDM must be defined and configured.

Parallel to the OpenID Connect authentication, the internal user management or LDAP authentication can also be used. When only OpenID Connect authentication should be used, it is possible to deactivate the internal user management by setting the internal user management property file.user to an empty value.

To configure the connection to an OpenID Connect (Oauth2 in Kubernetes) provider:

  • Kubernetes

  • Docker

userManagement:
  oauth2:
    registration:
      <name>:
        client-id: <client-id>
        client-secret: <client-secret>
        client-name: <client-name>
        client-authentication-method: <client-authentication-method>
        authorization-grant-type: <authorization-grant-type>
        redirect-uri: <redirect-uri>
        scope: <scope>
    provider:
      <name>:
        authorization-uri: <authorization-uri>
        token-uri: <token-uri>
        jwk-set-uri: <jwk-set-uri>
        user-info-uri: <user-info-uri>
        user-info-authentication-method: <user-info-authentication-method>
        userNameAttribute: <userNameAttribute>
        issuer-uri: <issuer-uri>
environment:
- [...]
- spring.security.oauth2.client.registration.<provider>.client-id=<your client id>
- spring.security.oauth2.client.registration.<provider>.client-name=<your client name>
- spring.security.oauth2.client.registration.<provider>.redirect-uri=<your xdm uri>
- spring.security.oauth2.client.registration.<provider>.client-secret=<your client secret>
- spring.security.oauth2.client.registration.<provider>.scope=openid
- spring.security.oauth2.client.registration.<provider>.authorization-grant-type=authorization_code

- spring.security.oauth2.client.provider.<provider>.issuer-uri=<your issuer uri>
- spring.security.oauth2.client.provider.<provider>.user-name-attribute=<preferred user name attribure>
- spring.security.oauth2.client.provider.<provider>.user-info-uri=<your user info URI>
- spring.security.oauth2.client.provider.<provider>.jwk-set-uri=<your JWKS URI>
- spring.security.oauth2.client.provider.<provider>.token-uri=<your token URI>
- spring.security.oauth2.client.provider.<provider>.authorization-uri=<your authorization URI>
name (Kubernetes) / provider (Docker)

Specifies the name of the provider, e.g. keycloak, okta, google, etc.

client-id

The ID that uniquely identifies the client.

client-name

A descriptive name used for the client. The name is displayed in the login page.

client-authentication-method (only Kubernetes)

The authentication method used when authenticating the client with the authorization server. Valid values are:

  • client_secret_basic

  • client_secret_jwt

  • client_secret_post

  • none

  • private_key_jwt

redirect-uri

The client’s registered redirect URI that the authorization server redirects the end-user’s user-agent to, after the end-user has authenticated and authorized access to the client. Typically, this is set to <base-url>/api/login/oauth2/code/<provider-name> where <base-url> is the base URL of your XDM installation.

client-secret

Client specific secret. If not specified, it’s supposed to be a public OpenID Connect provider.

scope

Sets the scope used for the client. Must be openid for the OpenID Connect protocol.

authorization-grant-type

Authorization grant type specifies the method that the client uses to obtain an access token. Valid values are:

  • authorization_code

  • client_credentials

  • jwt_bearer

  • password

  • refresh_token

issuer-uri

The URI used to initially configure a ClientRegistration using discovery of an OpenID Connect provider’s configuration endpoint.

user-info-authentication-method (Kubernetes only)

The authentication method used when sending bearer access tokens in resource requests to resource servers. Valid values are:

  • FORM

  • HEADER

  • QUERY

user-name-attribute

The name of the attribute returned by the ID-token or by the UserInfo response that references the name or identifier of the end-user. Common values are: name, preferred_username, given_name or family_name.

user-info-uri

The URI for the user info endpoint which provides additional details about the user.

jwk-set-uri

The URI for the JSON Web Key (JWK) Set endpoint.

token-uri

The URI for the token endpoint.

authorization-uri

The URI for the authorization endpoint.

xdm.core.ui.serverUri (only Docker)

The base URL of your XDM installation. This is the URL that users will use to access XDM in their web browser.

The Spring Security properties are prefixed with spring.security.oauth2.client.registration, followed by the client name and the name of the client property. The client name represents the name specified in the OpenID Connect provider.

User roles

XDM derives user roles from the tokens issued by the Identity Provider (ID Token and/or Access Token). There are predefined default scenarios and configurable options. If the provider does not assign any roles to a user in the tokens, XDM does not assign any default role.

1. Roles in the ID Token (default claim roles)

By default, XDM reads roles from the roles claim in the ID Token.

The roles claim may be:

  • a single string (exactly one role), or

  • a list of strings (multiple roles).

This variant is suitable if:

  • the Identity Provider already writes roles into the ID Token in this format, or

  • role information is intended to be provided exclusively via the ID Token.

2. Roles in the Access Token (default claims realm_access / resource_access)

Some providers (e.g. Keycloak, Microsoft Entra ID) place role information in the Access Token using these structures:

  • realm_access.roles

  • resource_access.<client-id>.roles, where <client-id> usually matches the value of the azp (authorized party) claim.

Requirements:

  • roles is always a list of strings.

  • For resource_access:

    • the claim azp must exist (for example "azp": "xdm"),

    • under resource_access there must be an entry with the same name ("xdm" in this example).

Example: roles in realm_access and resource_access
{
  "azp": "xdm",
  "realm_access": {
    "roles": [
      "GLOBAL_ADMIN"
    ]
  },
  "resource_access": {
    "xdm": {
      "roles": [
        "XDM_ADMIN",
        "OTHER"
      ]
    }
  },
}

XDM reads:

  • GLOBAL_ADMIN from realm_access.roles

  • XDM_ADMIN and OTHER from resource_access.xdm.roles

This variant is suitable if:

  • a provider such as Keycloak or Microsoft Entra ID is used that already supports these claims or can easily be configured to do so, and

  • roles are intended to be taken from the Access Token.

3. Custom claims in ID Token or Access Token

If the default options do not match the token structure, the XDM core server can be configured to read roles from custom claims.

Two environment variables are available:

For roles in the ID Token

  • xdm.core.idTokenRolesClaim

For roles in the Access Token

  • xdm.core.accessTokenRolesClaim

Both variables behave the same way but apply to different tokens.

3.1 General claim evaluation behavior

The following general behavior applies to all configured claims, regardless of whether they are read from the ID Token or the Access Token (and independent of the default locations described in sections 1 and 2):

  • The configured claim may be:

    • a single string (one role), or

    • a list of strings (multiple roles).

  • Nested claims can be addressed using dot notation:

    • outer.inner.roles corresponds to JSON of the form:

      {
  "outer": {
    "inner": {
      "roles": [ ... ]
    }
  }
}

XDM collects roles additively:

  • from the default locations (ID Token roles, realm_access, resource_access),

  • plus from the configured claims via xdm.core.idTokenRolesClaim and/or xdm.core.accessTokenRolesClaim.

All roles found are merged into a single role set.

3.2 Custom role claim in the ID Token (xdm.core.idTokenRolesClaim)

The variable xdm.core.idTokenRolesClaim is intended for use when:

  • the ID Token contains roles, but not in the default roles claim, or

  • roles are nested inside a custom structure in the ID Token.

Example: roles in ID Token claim groups
{
  "sub": "123",
  "name": "Alice",
  "groups": [
    "XDM_USER",
    "XDM_ADMIN"
  ]
}
Configuration
xdm.core.idTokenRolesClaim=groups
Example: roles nested in custom.roles in the ID Token
{
  "sub": "123",
  "name": "Alice",
  "custom": {
    "roles": [
      "XDM_USER",
      "XDM_ADMIN"
    ]
  }
}
Configuration
xdm.core.idTokenRolesClaim=custom.roles
Example: single role as string in ID Token claim role_name
{
  "sub": "123",
  "name": "Alice",
  "role_name": "XDM_USER"
}
Configuration
xdm.core.idTokenRolesClaim=role_name

In this case, XDM treats the string as a single role.

3.3 Custom role claim in the Access Token (xdm.core.accessTokenRolesClaim)

The variable xdm.core.accessTokenRolesClaim is intended for use when:

  • the Access Token contains roles, but not in realm_access or resource_access, or

  • the Identity Provider can only populate flat (non-nested) claims, or

  • the roles are placed in a custom structure inside the Access Token.

This is especially useful with some ADFS setups where:

  • only the Access/Bearer Token can be modified,

  • no nested JSON structures can be created in claims,

  • the system decides automatically whether a claim value is a string (one role) or an array (multiple roles).

Example: roles in Access Token claim roles
{
  "aud": "...",
  "iss": "...",
  "roles": [
    "XDM_USER",
    "XDM_ADMIN"
  ]
}
Configuration
xdm.core.accessTokenRolesClaim=roles
Example: single role as string in Access Token claim groups
{
  "aud": "...",
  "iss": "...",
  "groups": "XDM_USER"
}
Configuration
xdm.core.accessTokenRolesClaim=groups

In this case, XDM interprets "XDM_USER" as one role.

Example: nested custom claim in Access Token
{
  "aud": "...",
  "iss": "...",
  "custom": {
    "security": {
      "roles": [
        "XDM_USER",
        "XDM_ADMIN"
      ]
    }
  }
}
Configuration
xdm.core.accessTokenRolesClaim=custom.security.roles

Token based authentication configuration

XDM supports the user authentication with an API Token. XDM uses a non-interactive mode for logging in via API Token meaning that the user is not forwarded to the authentication provider’s login page. Instead, the user may log in via the username and the API token directly from XDM.

As a prerequisite for using an API Token within XDM, the corresponding role must be set and defined in the docker compose file. Therefore, the environment variable xdm.core.security.required-token-creation-role must be set to the name of the role which should be able to create and use API Tokens.

If the external user is deactivated or deleted at the authentication provider, the respective XDM user has to be deactivated manually inside XDM. By this, the corresponding API Token will also be deactivated and can not be used for authentication anymore. This will not happen automatically.

To configure the connection via an API Token, you need to edit for docker installations the docker_compose.yml file or for Kubernetes installations the values.yaml file.

  • Kubernetes

  • Docker

security:
    requiredTokenCreationRole:<any role>
core-server:
  environment:
    - xdm.core.security.required-token-creation-role=<any role>

Examples

  • Kubernetes

  • Docker

To allow users with the role XDM_USER_GROUP to create and use API Tokens, add the following line to the values.yaml file:

security:
    requiredTokenCreationRole:XDM_USER_GROUP

You can as well define multiple roles that are allowed to create and use API Tokens. To allow users with the role XDM_USER_GROUP and XDM_TESTER_GROUP to create and use API Tokens, add the following line to the values.yaml file:

security:
    [...]
    requiredTokenCreationRole:XDM_USER_GROUP,XDM_TESTER_GROUP

To allow users with the role XDM_USER_GROUP to create and use API Tokens, add the following line to docker-compose.yml in the environment section in the core-server configuration block:

environment:
- xdm.core.security.required-token-creation-role=XDM_USER_GROUP

You can as well define multiple roles that are allowed to create and use API Tokens. To allow users with the role XDM_USER_GROUP and XDM_TESTER_GROUP to create and use API Tokens, add the following line to docker-compose.yml in the environment section in the core-server configuration block:

environment:
- xdm.core.security.required-token-creation-role=XDM_USER_GROUP,XDM_TESTER_GROUP

Further information on how to use API Tokens and the concepts behind it can be found in the Token based authentication concepts.

Redirect URI

The redirect URI must be a valid link to which a browser can redirect after a successful login.

Example: https://xdm-ui:4280

Example configuration for the identity and access management client Keycloak:

environment:
- [...]
- spring.security.oauth2.client.registration.keycloak.client-id=xdm
- spring.security.oauth2.client.registration.keycloak.client-name=Keycloak
- spring.security.oauth2.client.registration.keycloak.scope=openid
- spring.security.oauth2.client.registration.keycloak.redirect-uri=https://xdm-ui:4280/api/login/oauth2/code/keycloak
- spring.security.oauth2.client.provider.keycloak.issuer-uri=https://keycloak.dev/auth/realms/xdm-test
- spring.security.oauth2.client.provider.keycloak.user-name-attribute=preferred_username
- xdm.core.ui.serverUri=https://xdm-ui:4280
If the OpenID provider and also a context path is configured, you need to change the xdm.core.ui.serverUri accordingly. For example, if the context path is set to /xdm/, adjust xdm.core.ui.serverUri in the core-service section to https://xdm-ui:4280/xdm/ and the redirect-uri to https://xdm-ui:4280/xdm/api/login/oauth2/code/keycloak.

To set the XDM credential panel to be visible initially if an OpenID Provider is configured for an XDM installation, add the following line in the section services→web-ui→environment:

always_open_login_panel=true

Internal user management

XDM offers a built-in user management system that allows you to maintain the usernames, passwords, and roles in a plain text file. Each line represents a separate user and must have the following format:

<user_name>;{<hash_method>}<password>;<roles>;<full_name>;<email>
user_name

Specifies the name of the user.

hash_method

Specifies the hash method for the password. This must be one of the following values:

  • argon2 - Argon2 password hash

  • bcrypt - BCrypt password hash

  • ldap - LDAP SHA password hash

  • SHA-256 - SHA-256 password hash

    password

    Specifies the hash sum of the password of the user. The password must be hashed with the previously specified hash method.

    roles

    Specifies a list of roles for that user. These roles can be used later while granting permissions.

    full_name

    The full name of the user. This property is used to identify the user in the graphical user interface. The full name is displayed in the user settings and is used to synchronize the display name of a permission recipient.

    This field is optional, but required if the e-mail is to be specified.

    email

    The e-mail address of the user. The e-mail address can be accessed in the various Java Scripts / Groovy scripts.

    This field is optional, but required if the full name of the user is to be specified.

  • Kubernetes

  • Docker

In Kubernetes, the users are specified in the Helm chart:

 userManagement:
   local: |
     # User name ; Password ; Roles
     admin;{sha-256}8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918;ADMIN
     user;{sha-256}04f8996da763b7a969b1028ee3007569eaf3a635486ddab211d512c85b9df8fb;USER
     tech;{sha-256}fe9bbd400bb6cb314531e3462507661401959afc69aae96bc6aec2c213b83bc1;ADMIN

In Docker, the users are specified in a file, e.g. my-users.txt. The user file must be created in the XDM configuration directory.

services:
  core-server:
    volumes:
      - ./xdm-config:/xdm/config:ro
    environment:
       - file.user=/xdm/config/my-users.txt

The file my-users contains the information about the users:

admin;{sha-256}8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918;ADMIN
user;{sha-256}04f8996da763b7a969b1028ee3007569eaf3a635486ddab211d512c85b9df8fb;USER
tech;{sha-256}fe9bbd400bb6cb314531e3462507661401959afc69aae96bc6aec2c213b83bc1;ADMIN
If you manage the credentials of the XDM users in a plain text file, you should restrict access to this file using the access control mechanisms of your operating system to prevent unauthorized users from accessing the file.
It is possible to run XDM using only Internal User Management. However, XDM should generally be connected to an LDAP or OpenID system. The users file is then optional, for example, to use technical users in XDM that are not stored in LDAP or OpenID.

Example

The following example defines a user with the name hugo, and the password test. An SHA-256 hash of the password is used. This user has the roles ADMIN and EDITOR.

  • Kubernetes

  • Docker

In Kubernetes, the user has to be added in the Helm chart:

 userManagement:
   local: |
     # User name ; Password ; Roles
     ...
     hugo;{SHA-256}9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08;ADMIN,EDITOR

In Docker, the users has to be added to a file named my-users.txt. The user file must be created in the XDM configuration directory, if not exists.

...
hugo;{SHA-256}9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08;ADMIN,EDITOR

If the file not exists, it has to be added to the configuration:

Parameter:

  • file.user points to a local users file in /xdm/config

    services:
  core-server:
    volumes:
      - ./xdm-config:/xdm/config:ro
    environment:
       - file.user=/xdm/config/my-users.txt
To obtain the SHA-256 hash of the password test, you can execute the following command in a Linux or UNIX shell that has access to the sha256sum program: echo -n test | sha256sum. Furthermore, echo -n test | openssl dgst -sha256 will also show the SHA-256 hash value of the password.

Users and Roles

User name

LDAP and OpenID authenticators provide additional user information upon successful login. This information can be used to adapt the username to a more meaningful value. By default, the 'givenName' property is used, but the following properties can also be used:

LDAP attributes:

carLicense, departmentNumber, description, destinationIndicator, displayName, employeeNumber, givenName, homePhone, homePostalAddress, initials, mail, mobile, o, ou, postalAddress, postalCode, roomNumber, sn, street, telephoneNumber, title, uid

OAuth2 claims:

birthdate, email, family_name, gender, given_name, locale, middle_name, name, nickname, picture, preferred_username, profile, updated_at, website, zoneinfo

Obviously, not all possible properties will provide a better username. Furthermore, it depends on the authentication provider which properties are available and have a value. When another property instead of the default should be used, add the key `fullNameProperty and specify the property name. The following line will change the displayed username to the user’s family name:

  • Kubernetes

  • Docker

 userManagement:
   fullNameProperty: family_name
services:
  core-server:
    environment:
      - xdm.user.full-name-property=family_name

Login group

Specifies a role to which the usage of XDM will be limited. This property enables the administrator to define a list of roles, which will restrict the access to XDM. In order to use XDM, an authorized user has to be a member of one of these roles. By default, all authorized users are able to use XDM.

With the following property definition all authorized users have to be a member of either XDM_USER_GROUP or XDM_TESTER_GROUP.

  • Kubernetes

  • Docker

 security:
   requiredUserRole: XDM_USER_GROUP,XDM_TESTER_GROUP
services:
  core-server:
    environment:
      - xdm.required-user-role=XDM_USER_GROUP,XDM_TESTER_GROUP

Configuring unauthorized user login message

This setting controls the message that is displayed if a user tried to log in, that is not a member of the roles specified by the property xdm.required-user-role. By default, the following message will be displayed: Missing one of the following roles: <roles set in xdm.required-user-role>

With the following property definition, all unauthorized users will get the following message on the login screen: Login has currently been restricted to Admins only. XDM_USER_GROUP,XDM_TESTER_GROUP

This message is always extended by all roles that were specified in the environment variable requiredUserRole.

  • Kubernetes

  • Docker

 security:
      requiredUserRoleMessage: "Login has currently been restricted to Admins only."
services:
  core-server:
    environment:
      - xdm.required-user-role.message="Login has currently been restricted to Admins only."

Configuring the administrative role

Adjust the name of the administrator role

Sets the names of the administrator role. The default name of the administrator role is ADMIN. When specifying multiple administrator roles, then use a comma separated list. This can be set to conform to your naming conventions. Every user who is in one or more of the roles in this list, will receive administrative privileges in XDM.

To change the name of the administrator role to SYSADM, the following line must be added to the configuration:

  • Kubernetes

  • Docker

security:
   adminRole: SYSADM
services:
  core-server:
    environment:
      - xdm.core.admin.role=SYSADM
Adjust the permissions for the administrator role

Users that have administrative privileges in XDM can read and create all XDM objects and can grant privileges to other non-administrative users. The privileges of the administrative users can be customized with this property. One or more entries of the following options can be specified:

Privilege Description

READ

Allows administrators to see objects in lists, to see details about objects, and to request a data shop order.

WRITE

Allows administrators to modify attributes of an object.

DELETE

Allows administrators to delete an object.

CREATE

Allows administrators to create new objects in a list.

EXECUTE

Allows administrators to execute or schedule a task or workflow template, and to place a data shop order.

ADMINISTRATION

Allows administrators to grant permissions for an object to other users.

SOURCE USAGE

Allows an environment or a connection to be used as the source of a task.

TARGET USAGE

Allows an environment or a connection to be used as the target of a task.

BROWSE

For connections only. Allows administrators to see the contents of tables in the schema browser, and in the output of XDM tasks that provide a data preview.

APPLY SQL

For connections only. Allows administrators to execute SQL statements for tables in the schema browser, and in the output of XDM tasks that provide a data preview.

DIAGNOSE

For task templates, tasks, workflow templates and workflows only. Allows users to see diagnostic data like stage outputs or batch reports.

SCRIPT

For credentials only. Allows the usage of this credential in a task stage hook.

MODIFY DATA

For data reservation only. Allows modification of a data reservation.

n this example, the admin role permissions have been limited to read and administration. So any user who has the admin privileges can only read any object and assign rights to other non-administrative users.

  • Kubernetes

  • Docker

security:
   adminDefaultPermissions: READ,ADMINISTRATION
services:
  core-server:
    environment:
      - xdm.admin-default-permissions=READ,ADMINISTRATION

Data shop purchaser role

Specifies the role, of which the members will be treated as data shop users. These users don’t need full access to all functions of XDM and will receive a customized UI with which they can more easily order test data and see the results of their orders. When specifying multiple purchaser roles, then use a comma separated list.

All users in this role are only able to use the web interface with reduced functionality. See description of purchaser layout for more details and recommended permission settings for data shop purchaser users.

  • Kubernetes

  • Docker

security:
   purchaserRole: <purchaser-role-name>
services:
  core-server:
    environment:
      - xdm.core.purchaser.role=<purchaser-role-name>
Adjust the permissions for the purchaser role

The permissions of the purchaser users can be adjusted with this property. The default setting of the property is READ and DELETE. This property is applied when a user from the purchaser role requests a data shop. The permissions set in the property are applied to the resulting execution. One or more entries of the following options can be separated by comma:

Privilege Description

READ

Allows purchaser to see objects in lists, to see details about objects, and to request a data shop order.

WRITE

Allows purchaser to modify attributes of an object.

DELETE

Allows purchaser to delete an object.

ADMINISTRATION

Allows purchaser to grant permissions for an object to other users.

BROWSE

For connections only. Allows purchaser to see the contents of tables in the schema browser, and in the output of XDM tasks that provide a data preview.

DIAGNOSE

For task templates, tasks, workflow templates and workflows only. Allows purchaser to see diagnostic data like stage outputs or batch reports.

To adjust the permissions for the purchaser role, the following line must be added to docker-compose.yml. Please add the line in the section services→core-server→environment and specify the permissions of the purchaser role.

In this example, the read permissions are set for all executions executed by a purchaser user.

  • Kubernetes

  • Docker

security:
   purchaserDefaultPermissions: READ
services:
  core-server:
    environment:
      - xdm.purchaser-default-permissions=READ

System object role

Specifies a role, that will be able to see and use the pre-defined matchers, comparable fields, and modification methods, that XDM ships with. By default, access to these pre-defined entities is restricted to the system, and only users with administrative permissions are able to see, use and change them.

Users that are a member of the specified role will be able to see and use the pre-defined matchers, comparable fields, and modification methods, however they will not be able to change them. These objects can only be changed by users with administrative permissions.

  • Kubernetes

  • Docker

security:
   systemObjectsRole: <user-role-name>
services:
  core-server:
    environment:
      - xdm.core.system-objects.role=<user-role-name>

  • Kubernetes (examples)

  • Docker (examples)

Main parameters:

  • userManagement.local

  • userManagement.ldap.*

  • userManagement.oauth2.*

  • userManagement.fullNameProperty

    userManagement:
  fullNameProperty: family_name

  local: |
    admin;{noop}default;ADMIN
    user;{noop}default;USER

  ldap:
    enabled: true
    url: ldap://ldap.example.com:389/dc=example,dc=com
    searchFilter: uid={0}
    searchBase: cn=Users
    group:
      searchBase: ou=Groups,dc=example,dc=com
      searchFilter: member={0}
    manager:
      user: ldap-admin
      password: change_me
      # secret: ldap-credentials

  oauth2:
    registration:
      keycloak:
        client-id: xdm
        client-secret: change_me
        client-name: Keycloak
        authorization-grant-type: authorization_code
        redirect-uri: https://xdm.example.com/xdm/api/login/oauth2/code/keycloak
        scope: openid
    provider:
      keycloak:
        issuer-uri: https://keycloak.example.com/auth/realms/xdm
        userNameAttribute: preferred_username

Main parameters (core‑server environment):

  • file.user

  • ldap.*

  • spring.security.oauth2.client.*

  • xdm.user.full-name-property

    services:
  core-server:
    environment:
      # Local users file
      - file.user=/xdm/config/users.txt

      # LDAP example
      - ldap.url=ldap://ldap.example.com:389/dc=example,dc=com
      - ldap.search_filter=uid={0}
      - ldap.search_base=cn=Users
      - ldap.manager.user=ldap-admin
      - ldap.manager.password=change_me

      # OpenID example (Keycloak)
      - spring.security.oauth2.client.registration.keycloak.client-id=xdm
      - spring.security.oauth2.client.registration.keycloak.client-name=Keycloak
      - spring.security.oauth2.client.registration.keycloak.redirect-uri=https://xdm.example.com/xdm/api/login/oauth2/code/keycloak
      - spring.security.oauth2.client.provider.keycloak.issuer-uri=https://keycloak.example.com/auth/realms/xdm
      - spring.security.oauth2.client.provider.keycloak.user-name-attribute=preferred_username

      # Display full name in UI
      - xdm.user.full-name-property=given_name

Rootless Container Execution Users

The execution user is the user inside the container running the application. Below are instructions on handling the individual behavior of Docker and Kubernetes environments.

  • Kubernetes

  • Docker

For a Kubernetes environment, the default execution user is root. It is recommended to use a rootless execution user. To achieve this, you can follow the instructions below.

The two variables, runRootless and migrateToRootless can be set to true.

runRootless lets the containers run as non-root users.

migrateToRootless automatically migrates the existing volumes to be owned by the new non-root user 1000:1000.

runRootless: true
migrateToRootless: true

If you set another user or group via Security context, then these settings will be used instead of the default user 1000:1000.

After the migration, the option migrateToRootless should be set to false to avoid unnecessarily running the temporary migration container with root privileges.
For a Docker environment, the default execution user is 1000.

The volume permissions must be adjusted to allow the non-root user access to the volumes.

Execute the following command on your host machine to change the ownership of the XDM volumes to user 1000 and group 1000:

sudo chown -R 1000:1000 /path/to/xdm/volumes
Replace /path/to/xdm/volumes with the actual path of your persistent XDM volumes.