search
Contact Uscybus.io

Single Sign-On with LDAP

Configure LDAP Single Sign-On authentication and authorization for Connectware users with Active Directory or OpenLDAP integration.

circle-info

LDAP integration requires a Connectware Enterprise license.

LDAP (Lightweight Directory Access Protocol) is a standardized protocol for accessing directory services. In Connectware, LDAP can be used to authenticate users at login and assign permissions based on information from your directory service, such as Microsoft Active Directory or OpenLDAP.

This guide shows how to enable LDAP login in Connectware, choose an authorization model, and configure your directory so users receive the correct roles.

hashtag
Prerequisites

  • Connectware Enterprise license required. For more information, see cybus.ioarrow-up-right.

  • Active Directory or OpenLDAP server reachable from Connectware.

  • LDAP user and group structure prepared according to the configuration steps in this guide.

hashtag
How LDAP Works in Connectware

Connectware uses LDAP in two steps:

  1. Authentication: When a user signs in, Connectware verifies the username and password against your LDAP directory.

  2. Authorization: After successful authentication, Connectware assigns Connectware roles to the user based on your LDAP configuration.

On the first successful login, Connectware creates a corresponding user in its internal user database. On each subsequent successful login, role assignments are synchronized from LDAP.

You can choose between the following authorization modes:

  • Group mode: Roles are assigned based on LDAP group membership.

  • Attribute mode: Roles are assigned based on LDAP user attributes.

In both cases, role management happens in LDAP, not in Connectware.

hashtag
Choose Your LDAP Authentication Method

Decide how Connectware authenticates users against your LDAP directory. This choice depends on how your directory is structured and how users are organized within it.

Connectware provides the following methods for LDAP authentication:

  • Authentication with a dedicated bind user

  • Authentication without a dedicated bind user (direct user authentication)

A bind user is common in LDAP setups with complex directory structures. It is a limited user that you create in your LDAP directory. This user is usually read-only and has permission to search the LDAP directory tree.

You use it when users do not share a single LDAP base DN (i.e., when they are not in the same group). If your users are spread throughout the directory tree, you will likely want to use a bind user.

hashtag
Direct Authentication Without a Dedicated Bind User

You can authenticate without a dedicated bind user when your LDAP structure meets the following requirements:

  • All user entries are located in the same branch of the LDAP Directory Information Tree (DIT)

  • All users share the same base DN

    • Example: The base DN is ou=users,dc=corp,dc=com and the DN of all users follows the pattern <RDN_OF_USER>,ou=users,dc=corp,dc=com

  • Groups are not nested

    • Example of unsupported nesting: A user is a member of group A, group A is a member of group B, and group B is the group linked with a Connectware role.

When no dedicated bind user is used, Connectware takes the given bindDn, adds the userRdn, and binds with the user credentials to the LDAP server. Binding with user credentials is the actual authentication step with an LDAP server.

hashtag
Authentication Using a Dedicated Bind User

A dedicated bind user is required when your LDAP structure requires searches or involves complex group relationships. Configure this by setting the CYBUS_LDAP_BIND_PASSWORD environment variable.

You need this authentication method when:

  • User entries are distributed across different DIT locations

    • Example:

      • User 1: cn=user1,ou=production,dc=corp,dc=com

      • User 2: cn=user2,ou=operations,dc=corp,dc=com

    • In this case, Connectware needs to search from a common base DN (dc=corp,dc=com) to locate user entries

  • Your setup uses nested groups

    • The search base must be the common DN shared by all groups and users

If your directory needs additional constraints (e.g., multiple branches), configure a custom LDAP search filter. See LDAP Search Filters.

hashtag
Choose Your LDAP Authorization Mode

Connectware supports the following LDAP authorization modes:

  • Group mode: Sets permissions based on LDAP group membership.

  • Attribute mode: Sets permissions based on LDAP user attributes.

hashtag
Group Mode

Connectware roles can be associated with LDAP groups. When an LDAP user successfully logs in for the first time, a Connectware user is created. Depending on the LDAP group memberships of the LDAP user, corresponding roles are assigned to the Connectware user automatically. This way, permissions can be easily managed by adding or removing LDAP users to or from the related LDAP groups.

Example

You can link the Connectware role LDAP-Admin to an LDAP group cn=cw-admin,ou=connectware,dc=corp,dc=com. Users in this group automatically receive the role when logging in.

For more information, see Example Setup for Group Mode.

hashtag
Attribute Mode

When an LDAP user successfully logs in for the first time, a Connectware user is created. A custom attribute in the LDAP user entry specifies which roles should be automatically assigned to the Connectware user. Authorization is controlled by adding or removing Connectware role names in the LDAP user's attributes.

Example

If the custom attribute employeeType contains the value connectware-admin, the admin role is assigned to the user.

For more information, see Example Setup for Attribute Mode.

hashtag
Enable LDAP Authentication

hashtag
Enabling LDAP Authentication (Kubernetes)

  1. To enable the LDAP feature in Connectware, set the global.authentication.ldap.enabled Helm value to true.

  2. Additionally, provide the following Helm values within the global.authentication.ldap context:

Value
Example
Description

bindDn

ou=users,dc=corp,dc=com

Base DN for direct authentication or full DN of a dedicated bind user. See parameter table for details.

url

ldap://ldap.corp.com:389

URL of the LDAP server in format scheme://hostname:port.

Example

If you are using a bind user to search through the directory tree, you must specify the full DN of the bind user as bindDn and provide the following additional values:

Value
Example
Description

bindPassword

ANc97WCO"!xcC=(

Password for the bind user as defined in your LDAP server.

searchBase

dc=corp,dc=com

Base DN for searching users when using a dedicated bind user.

Example

If you do not want to provide the bind user and its password through Helm values (for example, when following a GitOps approach), you can reference an existing Kubernetes secret via existingBindSecret. For more information, see Bind User Credentials via Existing Kubernetes Secret.

  1. After enabling LDAP authentication, you must configure how Connectware derives user roles from LDAP. This is controlled through the mode setting in the global.authentication.ldap context. Connectware supports group mode and attribute mode.

For more information, see Choose Your LDAP Authorization Mode.

hashtag
Configure LDAP Parameters

Once the authentication method and authorization model are defined, configure the LDAP parameters required by Connectware. The available parameters depend on the deployment type and the chosen configuration path.

The following tables list all supported LDAP parameters for Kubernetes and Docker Compose deployments.

hashtag
Helm Values (LDAP)

Helm value
Description

global.authentication.ldap.enabled

true/false. Enables LDAP integration.

global.authentication.ldap.bindDn

Without bindPassword: Base DN where all user entries are located (e.g., ou=users,dc=corp,dc=com). With bindPassword: Full DN of a dedicated bind user (e.g., cn=binduser,ou=users,dc=corp,dc=com).

global.authentication.ldap.bindPassword or global.authentication.ldap.existingBindSecret

Password for the dedicated bind user or reference a Secret with keys bindDn and bindPassword. When provided, bindDn must contain the full DN of the bind user, and searchBase becomes required. Note: If both are provided, existingBindSecret takes precedence.

global.authentication.ldap.searchBase

Base DN for searching users. Required only when using a dedicated bind user (i.e., when bindPassword is set).

global.authentication.ldap.searchFilter

Optional custom user search filter; overrides default username-based lookup. See LDAP Search Filters.

global.authentication.ldap.url

LDAP/AD server URL, e.g., ldap://host:389 or ldaps://host:636.

global.authentication.ldap.mode

group or attribute.

global.authentication.ldap.rolesAttribute

LDAP attribute containing Connectware roles. Used only with mode: attribute.

global.authentication.ldap.memberAttribute

LDAP attribute indicating group memberships (often memberOf). Used only with mode: group.

global.authentication.ldap.userRdn

LDAP user property (e.g., cn) used as the username at login.

global.authentication.ldap.caChain.trustAllCertificates

true accepts all certificates (not recommended). Default is false.

global.authentication.ldap.caChain.cert or global.authentication.ldap.caChain.existingConfigMap

Provide full CA chain in PEM via cert: or reference a ConfigMap (file must be ca.crt). No file path option. Note: If both are provided, existingConfigMap takes precedence.

global.authentication.ldap.autoEnforceMfa

Enforce MFA for LDAP users after first login. Requires global.authentication.mfa.enabled: true and keys configured.

hashtag
Example LDAP Setups

This section shows a complete Docker example setup for both authorization models.

Each example follows the same structure: LDAP preparation, Connectware configuration, and role assignment behavior. You can use these examples as a reference and adapt them to your own directory structure.

hashtag
Example Setup for Group Mode

In order to assign permissions to Connectware users by grouping their LDAP user entries with LDAP groups, you need to perform the following steps:

  1. Define LDAP groups according to Connectware roles that you want to use.

  2. Configure Connectware with LDAP parameters.

  3. Link LDAP groups with Connectware roles.

  4. Assign LDAP users to these LDAP groups.

1

Define LDAP Groups According to Connectware Roles

In this example, additional groups are created and associated with Connectware roles. This is not a mandatory practice, but is intended to demonstrate the concept.

We assume that we have the following DIT structure:

  1. Create the groups cw-admin and cw-minimal as follows:

  1. Now add user1 to cw-minimal.

  2. Run the following command to retrieve and display all attributes for user1. Make sure to change PASSWORD to the actual password of user1.

Result of the command:

  1. If you are using OpenLDAP and you do not see the memberOf attribute, run the following command:

  • If you can see the memberOf attribute, your LDAP is correctly configured for group operations. You can proceed with the next configuration steps.

  • If the memberOf attribute is not visible, your OpenLDAP installation lacks the required memberOf module. In this case, your OpenLDAP instance needs additional configuration.

2

Configure Connectware with LDAP Parameters

  • Edit the .env file as follows:

Make sure to adjust the LDAP URL to match your environment.

3

Linking LDAP Groups with Connectware Roles

  1. Log into Connectware as administrator and select User > User Management. Select the Roles tab and click Add Role.

  2. In the Create Role dialog, do the following:

    1. In the Name field, enter LDAP-Admin.

    2. To associate this role with the LDAP group cw-admin, copy the DN of that LDAP group to the field DN of AD Group. In this example, this will be cn=cw-admin,ou=connectware,dc=corp,dc=com.

    circle-info

    The field is labeled "DN of AD Group" in the UI, but it accepts the DN of any LDAP group, whether from Active Directory or OpenLDAP.

    1. In the Copy Permissions field, select connectware-admin and click Add.

    2. Click Create to add your new role.

  3. Click Add Role again to add another role with the following configuration:

    1. In the Name field, enter LDAP-Minimal.

    2. In the DN of AD Group field, add the DN of the related LDAP group (cn=cw-minimal,ou=connectware,dc=corp,dc=com).

    3. In the Copy Permissions field, select minimum-access and click Add.

    4. Click Create to add your new role.

4

Assigning LDAP Users to LDAP Groups

  1. You can assign different Connectware roles to your users user1, user2, and user3 by adding them to or removing them from the groups cw-minimal or cw-admin.

  2. When you add user1 to the group cw-admin and log into Connectware, user1 will be created (if it is the first login) and the role LDAP-Admin will be assigned automatically.

  3. Log out from Connectware, remove user1 from group cw-admin, and add it to cw-minimal.

  4. Log into Connectware with user1 again. user1 has limited access and you cannot navigate to the user section. Permissions of user1 changed according to the LDAP group membership.

If you log in as user2 and user2 is not assigned to any LDAP group yet, user2 will be created but you will see an error dialog saying that no permission was added and thus you will be forced to log out again.

hashtag
Example Setup for Attribute Mode

  1. LDAP setup.

  2. Configure Connectware with LDAP parameters.

  3. Assign roles to the LDAP user entry.

1

LDAP Setup

The following examples assume that you have an LDAP DIT structure like the following:

This structure is not mandatory, but be aware to adjust the following examples according to your LDAP setup in the next steps.

2

Configuring Connectware with LDAP Parameters

  • Edit your .env file as follows:

Make sure to replace the CYBUS_LDAP_URL with your actual LDAP server address and port.

3

Assigning Roles to LDAP User Entry

  1. To assign roles to LDAP users, you have to add the Connectware role names as values to the user's CYBUS_LDAP_ROLES_ATTRIBUTE that you defined in the .env file. In our example, we will use the attribute name employeeType.

  2. To add the Connectware role connectware-admin to the LDAP user user1, add the attribute employeeType (defined as the roles attribute in the .env file) with the value connectware-admin to the LDAP user user1.

  3. Add the Connectware role minimum-access to user2 by adding the attribute employeeType with the value minimum-access to the LDAP user user2.

  4. Check if the attributes have been set correctly by running the following command:

Result of the command:

  1. If you now log into Connectware as user1, the Connectware role connectware-admin will be assigned to user user1.

  2. To revoke access to Connectware for a certain user, the Connectware roles just have to be removed from the LDAP user by deleting the corresponding attribute employeeType.

Connectware comes with predefined user roles like connectware-admin and minimum-access, but additional roles can be created and assigned to users in the same way.

hashtag
User Management for LDAP Users in Connectware

When LDAP authentication is enabled, user management in Connectware differs from local user accounts. These differences are important to understand when operating and troubleshooting an LDAP-based setup.

When using LDAP authentication, Connectware user management differs from regular local user accounts in several aspects. The following sections detail these differences and explain how LDAP users are handled within Connectware.

hashtag
Roles

You cannot add or remove roles from within Connectware. All roles have to be assigned in the user details of the directory user. Modified user roles are synchronized to the Connectware user on each successful login.

hashtag
Grant Types

Every LDAP user defaults to token authentication. This property is not modifiable.

hashtag
LDAP User Password

You cannot change the password from within Connectware as it uses the LDAP directory service for authentication.

hashtag
Deleting LDAP Users

You can still remove LDAP users from the Connectware user database. Note that this only deletes the Connectware internal user information. Deleting this local user information will not prevent the user from logging into Connectware again.

To fully revoke access, you must either remove their Connectware roles in LDAP or remove them from LDAP groups associated with Connectware roles, depending on your integration mode.

hashtag
Advanced LDAP Configuration

hashtag
Customizing the User RDN

The user RDN (relative distinguished name) defines which LDAP attribute is used to identify a user during authentication.

By default, Connectware uses the cn attribute as the user identifier during login. This means the username entered at the Connectware login screen is mapped to an LDAP distinguished name constructed with cn=<username>.

You may need to change the user RDN if your directory uses a different attribute to identify users, for example, uid, sn, or sAMAccountName. In such cases, you must configure Connectware to use the appropriate LDAP attribute as the user RDN.

  • The configured user RDN must match the directory schema used for user entries.

  • When using direct authentication without a dedicated bind user, the user RDN is combined with the base DN to form the bind DN.

  • When using a dedicated bind user, the user RDN is used during the search operation to locate the user entry.

Make sure the chosen attribute uniquely identifies users within the configured search scope.

Configuration examples for Kubernetes and Docker Compose are provided in the following sections.

Customizing the User RDN (Kubernetes)

  1. In the values.yaml file, configure the global.authentication.ldap.userRdn Helm value.

Example

With this configuration, Connectware uses uid=<username> instead of cn=<username> when authenticating users.

  1. Apply the configuration changes via the helm upgrade command.

Example

For more information, see Applying Helm Configuration Changes.

hashtag
TLS for LDAP Authentication

You can secure LDAP communication by using LDAPS. When TLS is enabled, Connectware validates the certificate presented by the LDAP server.

You can choose from the following options:

  • Use a certificate signed by a trusted root CA.

  • Provide a custom CA certificate chain to Connectware.

  • Disable certificate validation for non-production environments.

Enabling TLS for LDAP Authentication (Kubernetes)

  1. To enable TLS for LDAP, set a valid ldaps:// URL for the Helm value url in the global.authentication.ldap context.

  2. Adjust the TCP port number. By default, LDAPS uses port 636.

hashtag
Providing the CA Certificate

Providing the CA Certificate through Helm Values

  • To provide the CA certificate, set the Helm value caChain.cert in the global.authentication.ldap context. Provide the complete certificate chain necessary to validate the LDAP server's certificate.

Example

As an alternative, you can provide the CA certificate through a manually created Kubernetes ConfigMap.

Providing the CA Certificate through a Kubernetes ConfigMap

To provide the CA certificate necessary to validate the certificate used by your LDAP server, you can manually create a Kubernetes ConfigMap that contains the certificate as a file named ca.crt. You will then provide the name of this ConfigMap in the Helm value caChain.existingConfigMap in the global.authentication.ldap context.

Example

  • Create the Kubernetes ConfigMap from a file named ca.crt in your current directory:

  • Specify the name of the ConfigMap:

hashtag
Disabling Certificate Validation

While we do not recommend skipping certificate validation for production use, it is possible to tell Connectware to accept any certificate the LDAP server presents.

Disabling Certificate Validation (Kubernetes)

  • To disable certificate validation, set the Helm value caChain.trustAllCertificates in the global.authentication.ldap context to true.

Example

hashtag
LDAP Search Filter

Connectware uses an LDAP search filter to locate a user entry during authentication. The filter is constructed dynamically based on the configured user RDN, the username entered during login, and an optional custom filter extension.

hashtag
Filter Format and Construction

By default, Connectware constructs the LDAP search filter as:

Where:

  • CYBUS_LDAP_USER_RDN (Docker Compose) or userRdn (Kubernetes) is configured in Connectware.

  • username is the value entered by the user during login.

If you configure an additional search filter extension, Connectware combines both parts using an AND condition. The resulting filter has the following structure:

hashtag
RFC 4515 Encoding Requirements

LDAP search filters must follow RFC 4515. Certain special characters in filter values must be escaped using hexadecimal notation.

See the official RFC for full details: https://datatracker.ietf.org/doc/rfc4515/arrow-up-right

Characters Requiring Escaping

The following characters must be escaped when used in LDAP filter values:

Character
Hex Escape
Description

*

\2a

Asterisk

(

\28

Left parenthesis

)

\29

Right parenthesis

\

\5c

Backslash

NUL

\00

Null character

Non-ASCII Characters

Non-ASCII characters (such as international characters) should be encoded as hex-escaped UTF-8 bytes. Each byte of the UTF-8 representation must be escaped individually.

Example: The German character ü is represented in UTF-8 as bytes 0xC3 0xBC, which must be escaped as \c3\bc in an LDAP filter.

Encoding Example

When used as an extension, only the escaped expression is added.

hashtag
When to Use a Custom Search Filter

Extending the search filter is useful in scenarios such as:

  • Users are not uniquely identifiable by their username alone.

  • Multiple entries share the same RDN within a large search base.

  • You want to restrict authentication to a specific subtree or object type.

hashtag
Example Scenario

Given the following directory structure, we have two entries with the same RDN cn=a.smith:

If the search base is set to dc=corp,dc=com, the username alone is not sufficient to uniquely identify the entry.

To restrict authentication to employees only, you can extend the filter to match entries whose DN contains ou=employees.

Testing the Custom Search Filter

You can validate the filter using ldapsearch before applying it to Connectware:

hashtag
Configuring the Filter Extension

Configuring the Filter Extension (Kubernetes)

  • In the values.yaml file, configure the global.authentication.ldap.searchFilter Helm value.

Example

circle-info

Be aware that no surrounding brackets are used for the additional expression. Brackets within your expression can be used, e.g., &(objectClass=iNetOrgPerson)(ou:dn:=employees).

hashtag
Bind User Credentials via Existing Kubernetes Secret

If you do not want to provide the bind user for LDAP authentication through the Helm values bindDn and bindPassword within the global.authentication.ldap context, you can also manually create a Kubernetes secret in Connectware's namespace through your preferred method of managing secrets in Kubernetes. You will then need to provide the name of this secret in the Helm value existingBindSecret.

This secret needs to contain two keys, bindDn and bindPassword, containing the parameters that you did not specify directly as Helm values. If you want to use different keys, you can customize these as shown below.

Example

  1. Create your Kubernetes secret:

  1. Specify the name of the secret in your values.yaml file:

hashtag
Customizing Kubernetes Secret Keys

If you want to customize the keys used in the Kubernetes secret, you can do so and specify the keys you want to use instead in the Helm value existingBindSecretDnKey and existingBindSecretPasswordKey within the global.authentication.ldap context.

Example

  1. Create your Kubernetes secret:

  1. Specify the name of the secret in your values.yaml file:

PreviousSingle Sign-On with Microsoft Entra IDNextAccess Permissions for Admin-UI

Last updated

Was this helpful?