ID Provider

• 1: Local
• 2: LDAPS
• 3: Azure
• 4: Jazz

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

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=

4 - Jazz