ID Provider

• 1: Local
• 2: LDAPS
• 3: Azure
• 3.1: Azure Portal Setup
• 3.2: Configure CDM-Server
• 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

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.

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=

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.

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=

4 - Jazz