Documentation

• 1: Getting Started
• 1.1: System Requirements
• 1.2: Installation
• 1.3: Setting Up the Environment
• 1.4: HTTPS
• 1.5: Login
• 2: ID Provider
• 2.1: Local
• 2.2: LDAPS
• 2.3: Azure
• 2.4: Jazz
• 3: IQ-Software
• 3.1: Connect to CDM-Server
• 3.2: Login to CDM-Server
• 3.3: Managing Projects
• 4: User Interface
• 4.1: LDAP Attribute Mapping Configuration
• 4.2: Business Units & Projects
• 4.3: Groups Management
• 4.4: Roles Management
• 4.5: Users Management
• 4.6: IQ & CDM Users map
• 4.7: Settings
• 5: Role-Based Access Control
• 5.1: Users
• 5.2: Groups
• 5.3: Roles
• 6: Miscellaneous
• 6.1: Data Backup
• 6.2: Logs
• 6.3: Setup on Windows
• 6.4: Bill of Materials
• 6.5: Install Self-Signed Certificate
• 6.6: Create PFX

1 - Getting Started

1.1 - System Requirements

Processor

• x86-64 compatible server CPU
• 8-cores or more
• Example: Intel Xeon E5 or later/equivalent AMD Epyc

Memory (RAM)

• Minimum 16 GB
• 32 GB or more recommended

Storage

• SSD with at least 10 GB free storage space for application, database, and container
• Or more, depending on the data volume

Operating System

Recommended OS: Ubuntu 20.04 LTS and Ubuntu 24.04 LTS

We do not support Windows at this moment. If you still want to run it on Windows, here’s a guide.

Software requirements

Common Linux Utils

• curl, tar, nano (or alternatives)

Docker

• Docker Engine v27.2.0+ with docker-compose-plugin v2.29.7+

Network requirements

• Stable network connection with sufficient bandwidth for data transfer between server and clients. 1+ gbps recommended

Security requirements

User privileges

• Make sure that the server has the appropriate user rights for managing Docker containers.

Firewall

• Configure the firewall to allow the traffic required to access the application.
  • Incoming Port 443 (or custom) for HTTPS (For IQ-Software, CDM-Server Webapp).
  • Outgoing Port 636 (or custom) for LDAPS
  • Outgoing Port 443 for HTTPS for Azure, OCI Image Pulls, etc.

1.2 - Installation

Step 1: Install Docker Compose

Make sure Docker Engine (with docker-compose-plugin) is installed on your system. See System Requirements for more details.

You may also try alternatives such as Podman.

Step 2: Download the Docker-Compose File

curl -s https://get.apis.de/cdm.sh | bash

curl -s https://get.apis.de/cdm.sh | bash -s v1.0.0

#!/bin/bash

# URL of the tar.gz file
url="https://get.apis.de/cdm/latest.tar.gz"

# Download the tar.gz file
curl -O "$url"

# Extract the tar.gz file
tar -xzvf "latest.tar.gz"

# Optional: Remove the tar.gz file after extraction
rm "latest.tar.gz"

chmod +x download
chmod +x start
chmod +x stop

echo "CDM setup has been downloaded and extracted."

Step 3: Create the DotEnv Files

To use the server, you need to provide some data in the form of two DotEnv files:

• .env
• .env.idp

Create new DotEnv files, copy the contents of the example files, and update the values with your own configuration.

.env File

Example: .env.example

cp .env.example .env && nano .env

.env.idp File

Example: IdP (ID Provider) specific DotEnv files:

• .env.idp.azure.example
• .env.idp.ldaps.example
• .env.idp.local.example

• Select Identity Provider
• Local
• Azure
• LDAPS

cp .env.idp.local.example .env.idp && nano .env.idp

cp .env.idp.azure.example .env.idp && nano .env.idp

cp .env.idp.ldaps.example .env.idp && nano .env.idp

Step 4: Login and Download CDM-Server Images

Use the following command to login and download the CDM-Server images. You’ll be asked to enter username and password.

sudo ./download

Step 5. Start the CDM-Server Services

sudo ./start

sudo ./stop

Step 6. Access CDM-Server

Please see Login for more information.

1.3 - Setting Up the Environment

Please set some basic details of the server in the .env file. You can find the .env.example file in the root directory of the project.

Configuration

cp .env.example .env && nano .env

## HELP
# https://get.apis.de/docs/server/env/

## ABOUT
# This will be used to create the root business unit
# Do not use special characters
COMPANY_NAME=

## CDM HOST and PORT
# The hostname to access the server.
# Must not contain protocol such as https://
# Must not have port number
# Must not have trailing slash
# Example: cdm.example.com
CDM_HOST=localhost

# Just the port number; 443 recommended
# Default port is 443
CDM_PORT=443

## USE CUSTOM HTTPS CERTIFICATE FOR CDM-SERVER (PRIVATE-KEY)
# If you have a custom certificate (private-key), set this to true.
# You need to place the custom certificate in the same directory as your `docker-compose.yml` file (where you have downloaded CDM-Server).
# The certificate file name must be `cdm-server.pfx`
# For a false value, a self-signed certificate will be created and used for HTTPS.
# Please check [help docs for more information](https://get.apis.de/docs/server/https/).
# Default is false
USE_CUSTOM_CERT=false

### CUSTOM CERTIFICATE PASSWORD
# If you are using a custom certificate (`USE_CUSTOM_CERT=true`) and your certificate is password-protected, set the password here.
# Otherwise, leave it empty.
CUSTOM_CERT_PASS=

Example

COMPANY_NAME=APIS Informationtechnologien GmbH
CDM_HOST=cdm.apis.de
CDM_PORT=443
USE_CUSTOM_CERT=true
CUSTOM_CERT_PASS=supersecretpassword

COMPANY_NAME

This is the name of your company. It will be used to create the root business unit.

USE_CUSTOM_CERT

See HTTPS for more information.

Setup Up ID Provider (IdP)

After you are done setting up .env, please head over to the IdP Docs to setup .env.idp file.

Permissions for the DotEnv Files

It is recommended that you do not allow other users in same server system to read the DotEnv files as some of them can contain credentials. You can try chmod 600 on all of them.

1.4 - HTTPS

CDM-Server takes the secure-by-design approach and thus enforces HTTPS.

HTTPS to Access CDM-Server

If you set the USE_CUSTOM_CERT environment variable to true:

• You can provide your own certificate. The server will use these files to serve HTTPS.
• This can be self-signed or CA-signed (recommended).
• There is a dummy file ./cdm-server.pfx where you have downloaded the CDM-Server. Just replace it with your own certificate.

Self-Signed Certificate

If the variable is set to false, the server will generate and use a self-signed certificate. You can find it in

• ./.data/certs/<CDM_HOST>.cert.p7b - X.509 certificate (contains the public key) that you can import to your browser.
• ./.data/certs/<CDM_HOST>.pfx - Certificate in PKCS#12 format. It contains private Key that you should not share.

Install Self-Signed Certificate on User’s Machine

Please see Install Self-Signed Certificate for more information.

LDAP over SSL

For this, look into LDAP documentation.

1.5 - Login

1. Open your browser and navigate to the CDM-Server URL. The module select page will appear.
2. Click Dashboard
3. In case of Local or Ldaps, enter your username and password
4. In case of Azure, you will be redirected to Azure login page.

2 - ID Provider

The CDM-Server supports various ID Providers (IdP) for authentication and user management. You need to choose one according to your organization’s requirements and configure it accordingly.

The CDM-Server supports the following ID Providers:

• Local - Users are managed internally by the CDM-Server. Easiest to set up and use.
• LDAPS - Users are managed by an LDAP server. Requires an external LDAP server present.
• Azure - CDM-Server uses Microsoft Azure for authentication. This will be available soon.
• Jazz - CDM-Server uses IBM Jazz for authentication. This is not available yet.

2.1 - Local

This IdP is the default IdP for the CDM-Server. It is used to authenticate users against the local user database. It uses an industry standard hashing algorithm to store passwords securely and authenticate users against the stored hash. All passwords require rotation every 180 days and must be at least 8 characters long. The admin can reset passwords for users if needed.

Configuration

In the .env.idp file, the following variables are used to configure the local IdP:

## HELP
# https://get.apis.de/docs/idproviders/local/

## USER MANAGEMENT
# Available options: local, azure, ldaps
ID_PROVIDER=local

### User Management -> LOCAL
# Only required if ID_PROVIDER=local
# We will create one root admin user using credentials below
# You will need to change password after login

## Root User Login
# Example: admin
ROOT_LOGIN=

## Root User Password
# Must be at least 8 characters long.
# Don't use special characters.
ROOT_PASSWORD=

Example

ID_PROVIDER=local
ROOT_LOGIN=admin
ROOT_PASSWORD=admin

2.2 - LDAPS

The LDAPS ID Provider

The CDM Server provides an embedded LDAPS ID-Provider which enables LDAPS connections to e.g. a Company’s LDAP server. The connection(s) to the LDAP are established using a connection pool which needs an LDAP user account to connect.

This LDAP connection account is used for every query from CDM-Server to the configured LDAP independent from the rights of the authenticated user. This means all queries are executed on LDAP with the LDAP permissions of the configured Connection Pool user.

CDM Server only needs the permissions to read users and groups in sub nodes under one parent node which are relevant to be used in CDM Server workflows.

LDAP Authentication of users via CDM-Server

The CDM Servers embedded LDAPS ID-Provider can be used to authenticate users LDAP credentials agains the companies LDAP. LDAP group informations can also be connected to cdm server roles. After this configuration in cdm server setup CDM users automatically are linked to roles matching the users group - role configuration.

Here is a sample .env.idp file with the ldaps IdP configured:

## HELP
# https://get.apis.de/docs/idproviders/ldaps/

## User Management
# Available options: local, azure, ldaps
ID_PROVIDER=ldaps

### User Management -> LDAP
# Only required if ID_PROVIDER=ldaps
# LDAPS server host
AUTH_HOST=

## LDAPS server port
# Change it if you are using a different port
AUTH_PORT=636

## The DN of the user to use to query the LDAP server. This user must have read access to the LDAP server.
# Example
AUTH_USER=

## Password for that user
AUTH_PASSWORD=

## User Management -> LDAP -> Internal References
# The full DN of the user in LDAP who is considered admin (This account is needed for server setup)
LDAP_ADMIN_DN=

## The base DN for the LDAP group tree
# Example: "ou=groups,o=apis,dc=apis,dc=de"
LDAP_GROUP_TREE_DN=

## The template for the login name. This is used to construct the full DN of the user to authenticate.
# Must contain {loginName} as a placeholder for the login name.
# Example: "uid={loginName},ou=users,ou=unix,o=apis,c=de,dc=apis,dc=de"
LDAP_LOGIN_TEMPLATE=

## USE CUSTOM HTTPS CERTIFICATE FOR LDAPS (PUBLIC-KEY)
# We always use HTTPS for LDAP.
# If you have a self-signed certificate for your LDAP instance, set this to true.
# You need to place the custom certificate (public key) in the same directory as your `docker-compose.yml` file (where you have downloaded CDM-Server).
# The certificate file name must be `cdm-ldaps.pfx`
# For a false value, we will attempt to validate the LDAP-Server certificate and it will fail for self-signed/expired certificates.
# Default is false
LDAP_CUSTOM_CERT=false

Inital CDM Server configuration workflow

On first CDM Server Start an ID Provider specific configuration for the Admin User has to be setup in the environment of the docker container. Therefor the parameters LDAP_ADMIN_DN and LDAP_Login_TEMPLATE have to be set to a valid LDAP DN (Distinguished Name) and matching Login Template. The LDAP_GROUP_TREE_DN parameter is needed, too.

2.3 - Azure

Basic Setup Instructions for CDM

Purpose

This guide provides information and instructions for configuring CDM Server to login using Microsoft Azure AD as Identity Provider.

Azure

Prerequisites

To be able to use Microsofts Azure Entra ID as ID Provider in CDM Server you need to make some configurations in Azure. Therefor you need

• Access to the Azure Portal.
• Permissions to create and manage Azure AD applications.
• The client redirect URI from the CDM-Server.

Tipp:

CDM Server users from external systems which should be able to access CDM-Server must be member of the same group in azure.

This group gets configured as Login-Group during initial configuration.

Configuration steps

This guide provides instructions for creating an Azure Active Directory (Azure AD) application that enables users to log into third-party software using Azure as Identity provider for authentication.

Step 1: Log in

Go to Azure Portal and log in with your Azure credentials. Then you will see a welcome page.

Step 2: Register an app for authentication

Tipp:

CDM Server uses 2 redirect URLs a login url which gets the response from azure after a login request and a logout url which queries the user to confirm the logout from azure.

Schema:

• https://hostname_or_domain:port/metaapi/login
• https://hostname_or_domain:port/metaapi/logout

Click on App registrations to register a new application which enables secure and controlled access to APIs and services for authentication and authorization in Azure.

Now click on “+ New registration” in the upper left area of page Home > App registrations.

Configure the Application Registration:

Name: Enter a descriptive name for the app e.g. “APIS CDM Server Authentication”.

Supported account types: Choose the account type required by your organization or users, e.g. “Accounts in this organizational directory only (Single tenant)”.

Redirect URL: Under Redirect URI, select Web and enter the LOGIN redirect URI provided by the CDM Server.

Make sure the URI is exact, as mismatched URIs will cause authentication errors.

Click on Register to complete the registration.

After registration, you’ll be directed to the application overview page.

Step 3:

Step 2: Configure Authentication Settings

Open Authentication Settings:

In the left menu, go to Manage -> Authentication.

Add Platform (if not already added):

Under Platform configurations, click “+ Add a platform”. Choose Web.

Enter Redirect URI:

CDM Server uses 2 redirect URLs a login url which gets the response from azure after a login request and a logout url which queries the user to confirm the logout from azure.

Add the missing URL(s)

Make sure the URLs are exact, as mismatched URLs will cause authentication errors.

Enable ID Tokens:

Under Implicit grant and hybrid flows, check Access tokens and ID tokens (used for implicit and hybrid flows). Then click Save.

After saving the application overview page is shown.

Add here the logout URL manually by editing the Web- Redirect URLS and save it.

Step 4: Configure API Permissions

Open API Permissions: In the left menu, select API permissions.

Click “+ Add a permission”. Select Microsoft Graph and then Delegated permissions. Add the permissions from the table below to allow user information retrieval.

Grant Admin Consent (if required): If prompted, click Grant admin consent for the selected permissions. (This step may require admin privileges.)

Microsoft Graph API / Permissions used by CDM Server

Step 5: Configure Client Secret

Open Certificates & Secrets: In the left menu, select Certificates & secrets.

Click “+ New Client Secret”.

Provide a description for the secret (e.g., “ClientSecret for ThirdPartyApp”).
Set the expiration period as required by your organization’s policies.
Click Add.

Save the Client Secret Value:

Once created, a value will be shown. Copy this value immediately, as it will be hidden later. This secret will be used in the CDM Server configuration.

Value and secret will be used in the CDM Server configuration and have to be noted outside of azure since value is only visible after creation, later its hidden!

Step 6: Configure the CDM Server Environment

Using the above information from Azure AD, configure the CDM-Server Environment variables.

Step 7: Test the Authentication Flow

In the CDM Server, open the Welcome Page and click on Dashboard to initialize the Authentication Flow.
You should be redirected to Azure AD for login. Log in using the credentials of the configured admin user!

After a successful login, you’ll be redirected back to the third-party software. Confirm that the authentication and authorization are working as expected.

Step 8: Maintain the Application

Periodically review and renew the client secret before expiration.
Adjust permissions or application settings in Azure AD if required by the third-party software or organizational policies.

Initial startup and configuration

Step 1: Log in as admin user

Caution:

If your user is not the declared admin user in the environment setup, authentication will fail!

• Open the public CDM Server Welcome Page in browser and click on Dashboard to start Azure authentication.

• In the popup window enter your azure credentials to login.

If you are the admin user and configuration is completely valid you will get logged in to the CDM Server and the Admin Dashboard is shown.

On the left side in the Navigation Azure should be selected, if not click on it.

On the right side in Azure configuration you have to enter the azure group id which contains all users which should be able to log in to CDM-Server.

After you entered the group, validate it by clicking the button “Validate”.
If validation failed you get a red message popup that group can not be validated. In this case the group for the id you entered does not exist.

If validation succedded the button gets green and you can Save and finalize the configuration.

Step 3: Save and finalize your configuration

• Click on Save to save the config

• Click on finalize to lock the config

• You get automatically logged out

Congratulations!

After succedding all of this steps the Azure Users which are in the configured group can log in to the CDM Server!

Here is a sample .env.idp file with the azure IdP configured:

## HELP
# https://get.apis.de/docs/idproviders/azure/

## User Management
# Available options: local, azure, ldaps
ID_PROVIDER=azure

## User Management -> AZURE
# Only required if ID_PROVIDER=azure
CLIENT_ID=
CLIENT_SECRET=
AZURE_CLIENT_ID=
AZURE_CLIENT_NAME=
AZURE_TENANT_ID=

2.4 - Jazz

3 - IQ-Software

3.1 - Connect to CDM-Server

Step 1: Open the IQ-Software

Step 2: (Top Menu) Tools -> Workstation Settings

Step 3: (Left Menu) Server Settings

Please enter the Server URL which must include:

• https:// at start
• The domain name part you will get from your administrator
• :XYZ the port number at the end

Step 4: Check Connection

Click on the Check Connection Settings button to verify the connection. You should see the following message box.

Certificate Error

If the CDM-Server has been setup using a self-signed certificate, you will see the following error if the certificate is not installed on your system.

The administrator can install it using group-policy or you can install it manually. Please see Install Self-Signed Certificate for more information.

3.2 - Login to CDM-Server

After starting the IQ-Software you have to login to the CDM-Server when performing your first command related to the CDM server (e.g. opening the Administration | CDM Administration). IQ-Software automatically prompts you for your credentials. Depending on the configured ID Provider on your CDM-Server the login procedure varies:

Local

Please enter the your username and your password as set up by your CDM administrator.

LDAPS

Please enter your LDAPS username and password.

Azure

Jazz

Logout

When closing the IQ-Software your login session on the CDM-Server is automatically terminated.

Should you need to log out and log in with a different user while using the IQ-Software, please use the File | Logout and File | Login menu commands in the Administration | CDM Administration window.

3.3 - Managing Projects

The CDM Server manages your IQ-Software data in seperate Projects. Each Project is stored on the CDM-Server in a Business Unit. These Business Units can be nested (one inside another) so that you can create tree-like structures similar to folders and subfolders within a regular file system.

Uploading .fme Files as CDM-Server Projects

The first step to working with the CDM-Server is to upload an existing project from one of your .fme files:

1. Open the .fme file in the IQ-Software
2. Choose File | Upload Project to the CDM-Server...
3. Choose the Business Unit into which the project should be uploaded

Note that you can only upload a project if the file contains exactly one project. If this is not the case please reorganize the data in the file in this respect.

Alternatively, you can create a new project via context menu directly in the CDM Administration (see below).

Opening a Project from the CDM-Server

Once there are projects available on the CDM-Server, you can open a project in the IQ-Software as easy as opening an .fme file: Choose File | Open CDM-Server... (alternatively you can also use Administration | CDM Administration).

This opens the CDM Administration view, showing you the available Business Units and their projects:

Selecting a Business Unit (1) shows you the contained Projects. When you select a Project (2), the contained structures are shown (3).

You can open a Project via the context menu or by double clicking it.

CDM Administration

In the CDM Administration (File | Open CDM-Server... or Administration | CDM Administration) you can also do the following things apart from opening a Project:

1. Create a new Project or Business Unit
2. Change the name of a Project or Business Unit (in multiple languages)
3. Delete a Project or Business Unit from CDM-Server
4. Move a Project from onen Business Unit to another using Drag&Drop
5. Perform an explicit File | Login... or File | Logout

Points 1 to 3 are available from the context menu (right-click).

4 - User Interface

4.1 - LDAP Attribute Mapping Configuration

The LDAP Attribute Mapping page allows you to configure how user’s attributes from an external LDAP connection will be translated to the CDM-Server’s internal representation. In the first section you will be able to set a group dn, which will determine the users available in the system. Afterwards you can configure the individual mapping between attributes in the next section. Finally you will be able to save, review and finalize the configuration.

Key Features Overview

• Two distinguished configuration sections for more oversight
• Easy mapping possibility with validation

Procedure

Introduction

The first time you login (and after that as long as you have not finalized the mapping) to a freshly configured instance with an LDAP ID-Provider as the admin user, you will be automatically redirected to the LDAP Attribute Mapping Configuration page.

Group DN

The next action should be to configure the group dn. Therefore navigate to the text field and enter a previously copied (to prevent typing errors) group dn into this field. Next you should validate it by clicking on the validate button.

The following results are possible:

• The group dn is valid: Everything is fine and you can procede to the next bottom section.
• The group dn is not valid: Please check the group dn for errors and validate again.

Attribute Mapping

The goal of this section is to configure a mapping between CDM and LDAP attributes, so that the CDM-Server will have a proper translation between those.

It contains a table with two columns, the CDM attributes on the left side and the LDAP attributes on the right.

On the left upper side next to the table, you can choose the type of your LDAP installation (Unix or Microsoft) depending on the type of OS on the LDAP host machine, which is used to apply a preconfigured mapping. If you do not wish for this automatism, you can choose Manual instead.

For each attribute on the left you have the following options to procede on the right:

• Enter the name of an LDAP attribute: After typing in the name of an LDAP attribute you wish to map, please validate it directly afterwards. If it is valid, you will find additional information by clicking on the information icon to the right of the text field. If it is not valid, please adjust the entered name and validate again.

• Enter nothing: If you enter nothing, the attribute will not be mapped.

All attributes except those marked with a star (*) are optional, you can finish the mapping without those.

After you have finished the mapping, you have the possibility to save the mapping and finalize the configuration. To do so, you may click on Finalize, which will present you a side by side comparison of your chosen mapping. Please review it carefully, because it can not be changed after you finalize the configuration.

If you wish to modify the mapping again, before you have finalized the configuration, you are free to do so. Please note, as long as you do not finalize the configuration, no user except the admin will be able to login.

4.2 - Business Units & Projects

The Business Units & Projects Management section allows you to organize and manage your Business Units structure and Projects. This section provides hierarchical representation of the relationships between business units and projects, and allows for easy navigation and updates.

Key Features Overview

• Hierarchical Structure: The business units and projects are displayed in a tree-like format, making it easy to visualize their relationships. Business units can contain other business units and projects, helping you clearly organize your company’s structure.

• Search Functionality: At the top of this section, you will find a search input that allows you to quickly locate a specific business unit or project by name.

Working with Business Units and Projects

You can manage both Business Units and Projects using a context menu that appears when you right-click on an item. Here are the available actions:

Business Unit Actions

• New Business Unit: Create a new business unit within the selected unit.

• New Project: Create a new project within the selected business unit.

• Update Business Unit: Modify the name of the selected business unit.

• Delete Business Unit: Remove the selected business unit from the hierarchy.

Project Actions

• Update Project: Modify the name of the selected project.

• Delete Project: Remove the selected project from the hierarchy.

Adding or Editing Names in Multiple Languages

Each Business Unit and Project has a Name field, which can be defined in multiple languages. When adding or editing a name, you will see a language selector on the right side of the input field. Use this selector to specify the language for the name, allowing for multilingual support throughout your structure.

Reorganizing the Structure

The hierarchical representation of business units and projects can be easily reorganized using drag-and-drop functionality. You can drag both business units and projects to different positions within the hierarchy to adjust the structure as needed. This makes it simple to adapt to changes in your company’s organization.

4.3 - Groups Management

The Groups Management Interface provides administrators with the tools to organize users into groups, a fundamental component of the Role-Based Access Control (RBAC) inside the CDM-Server.

This page allows you to create, view, update, and delete groups within the system, ensuring flexible and secure user management.

Types of Groups

There are three types of groups available on the Groups Management page:

• Normal Groups: These groups are fully managed within the system. Administrators can add or remove users from these groups as needed to align with access requirements.
• Remote Groups: Remote groups are synchronized from external ID-provider (LDAPS and Azure). These groups list remote users in a read-only mode.
• Singleton Groups: These are system-generated groups that are automatically created when a user is either created (for local) or registered (for LDAPS and Azure). Each Singleton Group contains only the individual user for whom it was created. Singleton Groups are read-only, meaning additional users cannot be added to them, nor can the user be removed from their Singleton Group.

Creating a Group

• Click on the + button in the table header to open the Create Group dialog.
• Fill the Name field (multiple languages are allowed) and the Remote Id field (only for LDAPS and Azure)
• Click Save to add the group to the system. The new group will appear in the groups table.

Assigning and Removing Users

Once a Group has been selected, in the right panel of the Groups Management page, administrators can assign or remove users from normal groups to adjust access as needed:

• Assign Users: Click on the + button of the panel and select a one or more users from the “search users dialog” and add them to the selected group, granting them the permissions associated with the group’s roles.
• Remove Users: Click on the “trash” icon button once at least one user has been selected to revoke the associated permissions.

4.4 - Roles Management

The Roles Management Interface allows administrators to define and organize roles within the CDM-Server.

On this page, you can create, view, and delete roles as needed, though roles cannot be updated once created. After creating roles, you can assign or remove groups to manage which users have specific access rights.

Creating a Role

• Click on the + button in the table header to open the Create Role dialog.
• Define the new role by selecting the Role Template and level in the organization’s tree (see RBAC integration).
• Click Save to add the role to the system. The new role will appear in the roles table.

Assigning and Removing Groups

Once a role has been selected, in the right panel of the Roles Management page, administrators can assign or remove groups as needed:

• Assign Groups: Click on the + button of the panel and select a one or more groups from the “search groups dialog” and add them to the selected role. This will grant all users in those groups the permissions defined by the role.
• Remove Groups: Click on the “trash” icon button once at least one group has been selected to detach it from the role. This action will revoke the permissions associated with that role for all the users of the group.

4.5 - Users Management

The Users Management Interface provides the capability to create, view, and manage user accounts.

Key Features Overview

This view provides a centralized interface to view and manage user profiles along with simplified user creation with optional system-generated passwords, workflows for password resets and forced password changes.

Creating a New User

(This option is available only when Local is selected as the Id-Provider)

• Click on the + button in the table header to open the Create User dialog.
• Fill in the required fields. Login should be a unique identifier for the user. Password should be either entered manually or click Generate Password for a secure system-generated password.
• Click Save to add the user to the system. The new account will appear in the user table.

Editing Existing Users

Locate the user in the table and click the Edit (pencil icon) to open the Edit User form. Update user details as necessary.

Password Reset

(This option is available only when Local is selected as the Id-Provider)
When a password reset is initiated for a user, a Temporary Password is generated and displayed in a pop-up. The administrator can copy this password and share it with the user. Temporary Password Validity Temporary passwords are valid for a limited period (e.g., 2 days). If the password expires, a new reset must be initiated by the administrator.

User Workflow with Temporary Passwords

When a user logs in using the temporary password, the system redirects the user to the Change Password dialog. The user must enter the current password (the temporary password). A new password must be set and confirmed before access is granted. Once the password is changed, the temporary password becomes invalid, and the user gains access to the system.

Self-Service Password Management for Users

Users have the ability to manage their passwords directly

From the user menu in the header, select Change Password. In the Change Password dialog, enter the current password. Set and confirm a new password. Click Continue to complete the password update.

Register a User

(This option is available only for LDAP and Azure as Id-Provider)
Registering an external user in the system is a crucial task that enables the CDM-Server to effectively manage and track users. Rather than duplicating user data, the server creates a reference entry in the database, allowing seamless integration of the external user into RBAC and other essential processes. This approach ensures that external users are fully enabled within the system without redundant data storage, maintaining efficient and streamlined access management.

4.6 - IQ & CDM Users map

The IQ & CDM Users Map section enables you to link IQ Persons (referred to as candidates) with CDM users.

Procedure

1. Selection of a project

To begin, select a project containing unapproved candidates. Only projects with unapproved candidates will be available in the project selection dialog. A candidate is considered approved once they are mapped/linked to a CDM user. Selecting a project will lock it to prevent simultaneous modifications by other users. If another user has locked the project, you will not be able to select it until they release the lock.

2. List of candidates

Once a project is selected, the left-side list will display IQ Persons (candidates) pending a match. Use the additional filter at the top of the list to refine your list as needed. Candidates are displayed with their Name, First Name, and E-mail by default. To reveal more details, click the button next to the “UNAPPROVED CANDIDATES” title. Changes to the displayed attributes are saved automatically and will be applied the next time you use the tool.

3. List of users

In the next step, you can search for CDM users by applying search criteria, then clicking “Search”. Users appear with their Login and First Name by default, but additional details can be displayed by clicking the button next to the “USERS” title. These display settings are saved for future sessions.

Create new Users (Local only)

If the required CDM user does not exist, you can create a new user by selecting the “New User” option. This option is available only if you are using local as the IdProvider on the CDM Server and you have admin privileges.

Creating Users

• Right-click on “New User” to open a dialog with all fields for a CDM user. Fill in the necessary information and submit to create the user.
• Create from Selected Candidates option is enabled when selecting at least one candidate and right-click “New User”. A dialog will open with all fields for a CDM user, with the option to select one of the previously selected candidates as template to pre-fill some of the fields and make the creation process faster.

4. Match Candidates with Users

To match a candidate with a user, select at least one candidate from the left list and exactly one user from the right list. This enables the " » " button, allowing you to move candidates to the user.
NOTE: This won’t perform any definitive change.

5. Review and apply changes

After mapping candidates to users, review the changes before applying them. Each candidate (IQ Person) can be mapped ONLY ONCE; this is a permanent action and cannot be undone. If you are ready to proceed, click the confirmation button to finalize the mappings.

6. Approved candidates

Once a candidate is mapped, they are considered approved and will be removed from the candidate list. If no candidates remain, the project selector will clear, and the project lock will automatically be released.

Reset changes

Click “Reset” to clear your progress, including any selected project, releasing the lock on the project and clearing all changes made in the current session.

4.7 - Settings

The Settings page allows all users to customize system preferences, including language settings and user interface layout. Changes made on this page are applied upon saving, and the page will automatically reload to reflect the updates.

Configuring General Settings

The General tab in the Settings page allows users to adjust their system-wide preferences, including language options and UI layout.

• Content Language The Content Language dropdown allows users to set the language for system content. For example, you can select “Deutsch” or “English” based on your preferred language for viewing data and content within the system.
• Interface Language The Interface Language dropdown allows users to change the language of the application’s user interface. This ensures that menus, buttons, and labels are displayed in the selected language.
• Identity Provider The IdProvider dropdown displays the authentication provider for your account. This setting can not be changed.
• Left-Side Menu Layout Left side menu collapsed: Checking this box collapses the menu on the left-hand side of the interface by default.
• Saving Changes Adjust the settings as needed in the General tab. Click Save to apply your changes. The page will reload automatically, and the new settings will be reflected immediately.

Configuring User-Specific Settings

The Users tab on the Settings page allows users to configure how attributes are displayed in the Users Management interface.

Attribute Order The Attributes Order section lets users reorder the fields displayed in the Users table, such as Title, Name, Login, Department, Email, Phone, and more. To reorder attributes:

• Drag and drop the fields to arrange them in your desired order.
• Click Save to apply the changes.
• The page will reload automatically, and the new order will be reflected in the Users table

5 - Role-Based Access Control

The Role-Based Access Control (RBAC) section enables efficient management of user permissions across your organization by assigning users to groups with predefined roles.

RBAC in the CDM-Server

As illustrated, Groups act as an intermediary layer between Roles and Users, streamlining the integration of local or external users from sources like LDAP and Azure.
By using groups, you can efficiently manage access for local and/or external users by assigning roles at the group level, reducing the need for individual permission management and ensuring seamless integration with external authentication systems.

Access Control

Users are classified into two categories based on the given rights at the specified level in the organization’s tree:

• Admin Users: These users have admin rights (write permissions) at the root level of the organization’s hierarchy.
• Non-Admin Users: These users lack write permissions on the root level of the organizational tree, restricting some functionalities and access to sections (see Roles page for more information).

5.1 - Users

The Users Management is the essential first step in defining and organizing access permissions, as all subsequent groups, roles and permissions rely on the accurate setup of user accounts.

Regardless of the chosen ID Provider, configuring users in the User Management section establishes the essential foundation for RBAC (Role-Based Access Control), enabling robust, secure, and scalable access control across the system.

How Users integrate with RBAC

By establishing users first, the organization can easily assign them to groups and later link these groups to roles as needed, creating a scalable, manageable RBAC hierarchy.

Typical Workflow

• User Registration: Users are created or imported from an external source (LDAPS or Azure). This provides a central repository for user accounts.
• Assign Users to Groups: Once added, users are assigned to Groups. Groups are logical collections of users with similar access requirements, such as departments, teams, or project members.
• Link Groups to Roles: Groups are then connected to Roles. Roles define the specific permissions for each group, streamlining the process by allowing permissions to be assigned collectively rather than individually.

For detailed guidance on managing users, visit the Users page.

5.2 - Groups

The Groups Management is a central component in the system’s Role-Based Access Control (RBAC) in the CDM-Server. It enables administrators to create, edit, view, and delete Groups—the critical link between users and roles. By assigning users to groups, and then associating those groups with roles, you can efficiently manage permissions across the organization without needing to configure each user individually.

How Groups integrate with RBAC

Groups act as a bridge between users and roles. By defining permissions at the group level, administrators can simplify access control, making it easier to manage permissions for multiple users at once.

Typical Workflow

• Create a Group: Define a new group and specify its purpose (e.g., “Project Managers” or “Quality Assurance”).
• Assign Users: Add users to the group who need similar access levels.
• Associate Roles: Link the group to specific roles that define permissions.
• Review and Adjust: Regularly view and update group memberships and role associations as team compositions change.

For detailed guidance on managing groups, visit the Groups page.

5.3 - Roles

The Roles Management section is the final and essential piece of the Role-Based Access Control (RBAC) in the CDM-Server.

Roles define specific permissions within the system, determining what actions can be taken and what resources can be accessed by groups and their members. Roles are the end-point in the RBAC hierarchy, serving as the permission layer that applies to users indirectly through their assigned groups.

How Groups integrate with RBAC

In the CDM-Server there are 3 predefined Role Template which already have specific permissions:

• Admin: Grants full write permissions on the selected level within the organization’s tree, including all subordinate levels. Admin users have complete control over the selected node and any of its child nodes, allowing them to modify, add, or delete resources.
• Editor: Provides write permissions ONLY on the child nodes of the selected level within the organization’s tree. Editors can modify content and make updates at subordinate levels without altering permissions or resources at the main (selected) level, preserving the structure while enabling focused updates.
• Viewer: Offers read-only access on the selected level within the organization’s tree. Viewers can view resources and data within this level but cannot make any changes, ensuring secure and restricted access for users who need visibility without modification rights.

Typical Workflow

• Create a Role: Define a new role by selecting the Role Template and level in the organization’s tree (Business Unit or Project).
• Assign Groups: Add groups to the role.
• Review and Adjust: Regularly view and update group and role associations as team compositions change.

For detailed guidance on managing roles, visit the Roles page.

6 - Miscellaneous

6.1 - Data Backup

Stop server and copy the .db and .data directory to a safe location. You might need sudo rights for this.

6.2 - Logs

Application Logs

In the .logs directory, you can find all the logs generated by the server.

Container Logs

There are also some logs generated by OCI containers. You can find them in the /var/lib/docker/containers (or equivalent if you are using something else) directory. For database, 10x 10mb files are retained. For application, 10x 100mb files are retained.

6.3 - Setup on Windows

Prerequisites

• Latest Windows Version with WSL2 Support
  • Recommended: Windows Server 2022
  • Should Work: Windows 11 23H2+
• Access to Windows Store
• Internet Connection

Installation Steps

1. Install: Ubuntu LTS on Windows Store
   • Alternatively, open Windows Store, Search for Ubuntu (by Canonical Group Limited) and Install it
2. Open Ubuntu from START and follow the instructions to set up your user inside WSL Ubuntu
3. Install Docker Engine with Docker Compose Plugin
   • (Recommended) Uninstall Old Versions
   • From the official Docker website: Install Docker Engine
     • This involves two steps: add canonical apt repository and then installing docker engine
4. Once done, optionally type: cd ~ && mkdir cdm && cd cdm
5. Now that you have a working linux inside windows, you can follow the CDM-Server installation on linux steps: See here
6. After the installation, you can find the CDM-Server in ~/cdm directory

Troubleshooting

• I can access CDM-Server from the server computer but not from other devices
  • Check your firewall settings and make sure the port is open
  • The specified CDM_HOST should resolve to the server’s IP address
• I want to run CDM-Server as a service in Ubuntu
  • You need to follow WSL2 Systemd Guide to run services in WSL2

6.4 - Bill of Materials

CDM-Server SBOM

We provide the SBOM in OWASP’s CycloneDX v1.6 format which has been officially ratified as an Ecma International standard.

You can find the SBOM for CDM-Server here:

• v1.0.0: View SBOM

Additional Information

• CDM-Server utilizes Java 21 (Temurin)
• CDM-Server utilizes PostgreSQL v16.4 (postgres:16-alpine)
• CDM-Server docker image utilizes Ubuntu 24.04

6.5 - Install Self-Signed Certificate

Manual Installation Steps

First, you receive the certificate from the administrator. Then, you can install it using the following steps:

6.6 - Create PFX

At the moment, we only support .pfx file for custom certificates. If you have a different format, you can convert it to .pfx using the following command:

openssl pkcs12 -export -out cdm-server.pfx -inkey example.key -in example.cer -certfile fullchain.cer

Where:

• example.key: Your private key file.
• example.cer: Your certificate file.
• fullchain.cer: The additional CA certificate chain.