Documentation

• 1: Getting Started
• 1.1: System Requirements
• 1.2: Installation
• 1.3: Update
• 1.4: Setup Environment
• 1.5: HTTPS
• 1.6: Login
• 2: ID Provider
• 2.1: Local
• 2.2: LDAPS
• 2.3: Azure
• 2.3.1: Azure Portal Setup
• 2.3.2: Configure CDM-Server
• 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: Changelogs
• 6.2: Data Backup and Maintenance
• 6.3: Logs
• 6.4: Setup on Windows
• 6.5: Bill of Materials
• 6.6: Install Self-Signed Certificate
• 6.7: 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+
• Example:

➜  docker --version
Docker version 27.3.1, build ce12230
➜  docker compose version
Docker Compose version v2.29.7

You may also try alternatives such as Podman, we do not support it at the moment.

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.

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 - Update

If you want to update your CDM-Server instance to a new version, the steps are quite simple:

Step 1: Take a Backup

Please see this page for backup instructions.

Step 2: Update

You need to download the new version and (re)start the server.

This is essentially, step 4 and 5 of installation process.

1.4 - Setup 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.5 - 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.

Renew Certificate

Once you have the renewed certificate file

• Stop the server
• Replace the file
• Restart the server

This will apply the new 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.6 - 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

Setup Instructions for connecting CDM Server to LDAP

Purpose

This guide provides information and instructions for configuring CDM Server to log in using an LDAP as Identity Provider.

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 of 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.

Prerequisites

The CDM Server supports authentication of users on behalf of an LDAP Service. An existing or new Login-Group and an Admin-User is needed to configure the CDM-Server.

LDAP Authentication of users via CDM-Server

The CDM-Server embedded LDAPS ID-Provider can be used to authenticate user LDAP credentials against 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.

In the image above a CDM-Users group is defined which contains the users that are allowed to use the CDM Server. All of them can log in after configuration is finalized.

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 information 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: uid=admin,ou=users,o=companyname,dc=domainname,dc=country
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)
# Example: uid=admin,ou=users,o=companyname,dc=domainname,dc=country
LDAP_ADMIN_DN=

## The base DN for the LDAP group tree
# Example: ou=groups,o=companyname,dc=domainname,dc=country
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,o=companyname,dc=domainname,dc=country
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

Before first CDM-Server start an ID Provider specific configuration for the Admin User has to be setup in the environment of the docker container. Therefore 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.

The following table shows an example configuration.

2.3 - Azure

Setup Instructions for connecting CDM Server to Azure

Purpose

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

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.

Step 1: Configure an Azure application as ID-Provider for CDM Server

• Azure - Configure Application

Step 2: Configure the CDM Server to use the azure application for authentication in CDM Server using the azure users.

• Azure - Configure CDM-Server

After succedding above steps the Azure Users which are in the configured group should be able to 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

# The Microsoft Azure AD Directory (Tenant) ID
# The Tenant ID is an UUID and contains hexadecimal numbers (0-9a-f) seperated by - and
# can be found in Azure Portal on the Entra-ID welcome page.
#
# Example: "e53f2a45-f4d2-a11d-223a-77b654c12df5"
AZURE_TENANT_ID=

# The Azure Application (Client) ID
# The Application client ID is an UUID and belongs to the application which is configured
# for the authentication and authorization of azure users for CDM Server. The Id can be
# found in Azure Portal -> App registrations.
#
# Example: "53a12b45-1234-5566-8fe4-93b787a787d6"
AZURE_CLIENT_ID=

# The Azure Application (Client) Name
# The Application client Name is a Text and belongs to the application which is configured
# for the authentication and authorization of azure users for CDM Server. The Name can be
# found in Azure Portal -> App registrations.
#
# Example apis_cdm_authentication
AZURE_CLIENT_NAME=

# The Azure Admin UUID
# The Azure admin UUID must be the id of the Azure user who is going to configure CDM Server at first start.
# The user which belongs to the id is then an admin user and the only user which is able to log in to the
# CDM Server to complete the configuration.
#
# To get your Azure user id log in to https://portal.azure.com/ click on view entra and in the page feed
# in the middle area of the entra welcome page the user id is shown.
#
# Example fd163a2f-112a-7291-bdf4-a4325b78910a
AZURE_ADMIN_UUID=

2.3.1 - Azure Portal Setup

The CDM Server supports authentication of users on behalf of Microsoft Azure. In Azure an application needs to be configured which provides the authentication flow.

Step 1: Start with the app registration

• Open azure portal in Web Browser and click on App registrations
  

• Now the app registrations page shows the registered azure apps.
  

  1. Click on “+ New registration” to register a new application in azure

• An application registration form is shown

  1. Enter the mandatory name
  2. Select a supported account type which matches your requirement
  3. Skip the step to add redirect URL here for now, we need more than one url, this can be done later.
  4. Click on Register, you will see the details of the registered app next

Step 2: Configure Application details

The values of the yellow highlighted fields are necessary for later use in CDM Server configuration. The Ids can be copied moving the mouse pointer to the right end of the value.

Please note the values for the following CDM Parameters for later use:

Redirect URIs

To configure allowed redirect destinations click on Add a Redirect URI on the Application details page.

In the following page click on + Add a platform. As a result a new form opens on the right side where you can select the type of platform.

Choose Web here.

Enter Redirect URI in the Redirect URIs field, enter the URI provided by the third-party software.

At the bottom of the form enable Access tokens and ID tokens:

Then click on Configure to finish the configuration.

Application Permissions

In the left menu select API permissions.

Add Permissions:

Click + Add a permission.

Select Microsoft Graph and then Delegated permissions. Add the permissions

• openid
• profile
• email
• User.Read
• Directory.Read.All
• Group.Read.All
• GroupMember.Read.All

If prompted, click Grant admin consent for the selected permissions. (This step may require admin privileges.)

The result should look like this:

The permissions Directory.Read.All, Group.Read.All and Group.Member.Read.All need Admin consent and are necessary to be able to read members of groups and groups of users which is necessary to provide RBAC flows in CDM Server which are based on group structures in external ID Providers.

2.3.2 - Configure CDM-Server

Prerequisites

To be able to configure the CDM-Server to start and for later use by members of a configured group, you need some values from the Azure Portal.

Values to collect from Azure Portal

Collect the values provided by Azure

The ID_PROVIDER for Azure is fixed and must be set to value azure in the environment.

First we will collect the Azure Tenant-ID, an admin user ID and a login group id.

The Admin user is able to log in to a fresh system to configure the necessary base settings.

• Log in to Azure Portal

• On the Welcome Page below Manage Microsoft Entra ID click on View button

  • You are now on the welcome page of your Tenant:

    1. Tenant-ID: You can click on the copy Icon after the value to copy it. Needed for AZURE_TENANT_ID.

    2. Click on the Number link on the right side of Users. In the appearing User list click on the name of the user, which is going to do the initial system configuration, in the column Display name. The Object ID value is needed in AZURE_ADMIN_UUID

    3. On the same page you can click on the Number link on the right side of Group memberships. In the appearing list of Groups click on the name of the group which you want to use as login group for all allowed users.

       

    The Object ID value is needed as AZURE_LOGIN_GROUP_UUID. This configuration setting is not part of environment setup, but it’s needed on first start.

    4. The AZURE_SCOPE value should be set to the value User.read

  Go back to Azure Portal Home

  Click in the left area menu on App registrations and click on your app to see the details:

  

  5. The Display Name value is needed as AZURE_CLIENT_NAME

  6. The Application (client) ID is needed as AZURE_CLIENT_ID

  7. The CLIENT_SECRET is configured in the App details below Client credentials on secret. Its value must be saved for later use when creating it, since it is only readable directly after adding it.

     If you missed that and the value is unknown you have to recreate it as described in Azure - Configure Application and save the value as CLIENT_SECRET.

Configure the CDM Server Environment

Go to the instance installation directory and open the .env.idp file with a text editor of your choice. In the file you have to write the parameter names and their assigned values in the schema ID_PROVIDER=azure

Example:

Test the Authentication Flow

Open the CDM-Server web interface 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.

Initial startup and configuration

Log in as admin user

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.

Configure Login Group

• Now add the ID of the group of the azure users which are allowed to log in to CDM Server in the form and click on validate.

  

• When validation succeeds the validate button changes to green

  

• Then click on the button “Save” to store the initial configuration in the database.

  

• To finally activate the change you have to click the “Finalize” Button. This means the configuration gets locked and is no longer editable. But you have to finalize when you are sure to enable all users in the configured group to log in to the CDM-Server.

  

  After clicking on finalize you have to confirm that you are sure and want to proceed. Confirm and select your account to log out your current azure session.

  

  In case you logged out your current azure session you get redirected to the welcome screen and all users which are member of the login group can now log in to CDM-Server using Azure.

  Possible Error Szenarios

  • The Login Group ID does not or no longer exist in Azure:
    An error message will be displayed and saving the configuration is not possible.

  • Admin user is not member of the login group:
    It is not possible to lock out the admin user, in this case an error message gets displayed.

Congratulations!

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

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.

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

# The Microsoft Azure AD Directory (Tenant) ID
# The Tenant ID is an UUID and contains hexadecimal numbers (0-9a-f) seperated by - and
# can be found in Azure Portal on the Entra-ID welcome page.
#
# Example: "e53f2a45-f4d2-a11d-223a-77b654c12df5"
AZURE_TENANT_ID=

# The Azure Application (Client) ID
# The Application client ID is an UUID and belongs to the application which is configured
# for the authentication and authorization of azure users for CDM Server. The Id can be
# found in Azure Portal -> App registrations.
#
# Example: "53a12b45-1234-5566-8fe4-93b787a787d6"
AZURE_CLIENT_ID=

# The Azure Application (Client) Name
# The Application client Name is a Text and belongs to the application which is configured
# for the authentication and authorization of azure users for CDM Server. The Name can be
# found in Azure Portal -> App registrations.
#
# Example apis_cdm_authentication
AZURE_CLIENT_NAME=

# The Azure Admin UUID
# The Azure admin UUID must be the id of the Azure user who is going to configure CDM Server at first start.
# The user which belongs to the id is then an admin user and the only user which is able to log in to the
# CDM Server to complete the configuration.
#
# To get your Azure user id log in to https://portal.azure.com/ click on view entra and in the page feed
# in the middle area of the entra welcome page the user id is shown.
#
# Example fd163a2f-112a-7291-bdf4-a4325b78910a
AZURE_ADMIN_UUID=

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

You are redirected to your webbrowser which shows the Azure Login page (depending on your previous activity one of the following pages will be shown):

Select the account you want to use by clicking on it or providing your account name and clicking Next. Then enter your password on the following screen. After successful authentication, this message is shown in the browser:

Authentication complete. You can close the browser and return to the application.

Now you can close the browser (tab) and switch back to the IQ-Software window.

On subsequent login attempts you might not even need to provide your username and password and are at once redirected to a page showing the above “Authentication complete” message. In this case, simply close the browser (tab) and switch back to the IQ-Software window.

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:

• Local 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. A Singleton Group is a special case of a Local 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. Candidates are 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, including all subordinate levels. Viewers can view resources and data within these levels 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 - Changelogs

v1.0.1

Release Date: 2024-11-19

Features

• Support for IQ-Software V8.0
• Azure (Entra) integration

Fixes

• Minor bug fixes

v1.0.0

Release Date: 2024-11-06

Features

• Server support for IQ-Software V8.0
• Candidate approval workflow
• Local user management
• LDAP integration
• Role-based access control (RBAC) (No Enforcement)
• User and group management

6.2 - Data Backup and Maintenance

Backup

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

Maintenance

We automatically run some maintenance tasks on the database every week on Sunday at 04:00 (Server time).

6.3 - 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.4 - 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.5 - Bill of Materials

CDM-Server SBOM

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

You can find the SBOM for CDM-Server here:

• v1.0.1: JSON | Summary
• v1.0.0: JSON | Summary

Additional Information

CDM-Server also utilizes:

• Java 21 (Temurin 21.0.5)
• PostgreSQL v16.4 (postgres:16-alpine)
• Ubuntu 24.04
• pg_repack 1.5.0
• Bulma 0.9.4
• font-awesome 6.1.2
• jsonld 1.0.0
• zxcvbn 4.4.2

6.6 - 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.7 - 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.