LDAP Configuration
LDAP integration is an optional Connectware feature which requires an Enterprise Edition License.
For the optional LDAP authentication feature, some extra configuration is needed.
Cybus Connectware supports user authentication and authorization through LDAP based on your existing local directory service like Active Directory or OpenLDAP. The following text guides you through setting up a connection and preparing your LDAP users to access Connectware.
Connectware LDAP Modes
The Connectware LDAP integration supports two ways of authentication and authorization called LDAP modes.
Group mode : permissions of Connectware users will be set by LDAP group memberships
Attribute mode - permissions of Connectware users will be set by LDAP user attributes
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 will be assigned to the Connectware user automatically. In this way, permissions can be easily handled by adding or removing LDAP users to or from the related LDAP groups.
Attribute Mode
When the LDAP user successfully logs in for the first time, a Connectware user is created. A custom user attribute of the LDAP user names any user roles that should be automatically assigned to the Connectware user. Authorization is controlled by removing or adding Connectware role names from or to the LDAP user.
Dedicated Bind User
Connectware supports 2 ways of authenticating a user: with and without a dedicated LDAP user to bind with the LDAP server. To make use of a dedicated bind user, set the environment variable CYBUS_LDAP_BIND_PASSWORD.
Not Using Dedicated Bind User
A dedicated bind user is not needed, when:
all user entries are leafs of the same tree whitin the LDAP Directory Information Tree (DIT) and share the same base DN. E.g. the base DN is
cn=users,dc=example,dc=organd the DN of all users are of kind<RDN_OF_USER>,cn=users,dc=example,dc=orggroups are not nested: E.g a user that is member of
group Aandgroup Ais member ofgroup Bandgroup Bis the groups that is linked with a Connectware role.
When no dedicated bind user is used, Connectware takes the given bind DN, adds the user RDN and binds with the user credentials to the LDAP server. Binding with user credentials is the actual authentication step with an LDAP server.
Using Dedicated Bind User
A dedicated bind user has to be used, when a search or groups is required, when:
user entries are spreaded within a DIT: E.g
user 1has the DNcn=user1,cn=foo,dc=example,dc=organduser2has the DNcn=user2,cn=bar,dc=example,dc=org. In order to find the user entry, a search is required with the basedc=example,dc=orgas this is the base DN that both users have in common.nested groups are used. In this case the search base is the DN that all groups and users have in common.
Connectware LDAP Parameters
In order to enable the LDAP feature, the following Environment Variables must be configured:
CYBUS_LDAP_ENABLED
Enables LDAP integration when set to true. If false, LDAP is disabled and all other LDAP parameters are ignored.
CYBUS_LDAP_BIND_DN
Specifies the bind DN for LDAP authentication.
CYBUS_LDAP_BIND_PASSWORD
Required for dedicated bind user. If not set, CYBUS_LDAP_BIND_DN is used as base DN to generate a bind DN with user login credentials.
CYBUS_LDAP_MODE
Specifies the LDAP mode: Either group or attribute.
CYBUS_LDAP_URL
The URL of the LDAP/AD server.
CYBUS_LDAP_SEARCH_BASE
Starting point for LDAP searches. Only used with dedicated bind user. Example: ou=tech,dc=cybus,dc=io.
CYBUS_LDAP_SEARCH_FILTER
Optional custom filter for user search requests. Only valid with dedicated user.
CYBUS_LDAP_ROLES_ATTRIBUTE
LDAP attribute containing user roles. Only valid with CYBUS_LDAP_MODE=attribute.
CYBUS_LDAP_MEMBER_ATTRIBUTE
LDAP attribute for group memberships. Only valid with CYBUS_LDAP_MODE=group. Usually set to memberOf.
CYBUS_LDAP_USER_RDN
LDAP user property (e.g., cn) containing the username used for Connectware login.
CYBUS_LDAPS_TRUST_ALL_CERTS
When true, accepts all servers without certificate check for Secure LDAP. Default is false.
CYBUS_LDAPS_CA_FILE
Path to CA file for LDAP server validation. Used with Secure LDAP when CYBUS_LDAPS_TRUST_ALL_CERTS is false.
CYBUS_LDAP_AUTO_ENFORCE_MFA
When true, enforces MFA for LDAP users after their first login.
Configuration
This description applies to a Docker Compose deployment (see Docker Compose), not a kubernetes one.
1. Navigate into your Connectware installation directory. If you have used the default values during installation this would be /opt/connectware.
2. The directory contains a .env file that is loaded when starting Connectware. Open the .env file in a text editor of your choice.
3. Locate the LDAP settings section in the .env file. By default the settings should look like this:
4. Set the individual parameters according to your local directory service configuration.
Example configuration for LDAP mode Attribute:
Example configuration for LDAP mode Group:
This configuration would look for users applicable to the LDAP query cn=username,ou=tech,dc=example,dc=org. Please do not use quotation marks to encapsule the variable values!
Configuration with dedicated Bind User
Example configuration for LDAP mode Attribute:
Example configuration for LDAP mode Group:
5. After saving the new configuration it has to be loaded by the running Connectware instance by executing docker compose up -d from within the installation folder. If the Connectware instance is running as system service please restart by executing systemctl restart connectware instead.
6. The new configuration is now loaded. The next step is to supply your directory service users with Connectware roles (LDAP mode attribute) or link LDAP groups with Connectware roles (LDAP mode group).
Example Setup for LDAP Mode Group
In order to assign permission to Connectware users by grouping their LDAP user entries with LDAP groups you have to do the following steps:
Define LDAP groups according to Connectware roles you want to use.
Configure Connectware with LDAP parameters.
Link LDAP groups with Connectware roles.
Assign LDAP users to these LDAP groups.
1. Define LDAP Groups According to Connectware Roles
In this example, extra groups are created, which will be associated with Connectware roles. This is not a mandatory practice but shall demonstrate the concept.
Assuming we have the following DIT:
Create 2 groups cw-admin and cw-minimal as follows:
Now add user1 to cw-minimal.
If you run the command (change PASSWORD to password of user1)
you shall see something like this:
If you are using OpenLDAP and you do not see the attribute memberOf you shall try the following command:
If you see the attribute memberOf now, your configuration is using memberOf as operation attribute (becomes important in the next step).
If you still do not see the attribute memberOf, your OpenLdap is missing the memberOf module. Thus the OpenLDAP instance in not applicable for the LDAP group mode and need modifications first.
2. Configure Connectware with LDAP Parameters
Edit the file .env as follows:
Be aware of adjusting the LDAP url, the given example uses an Active Directory service that runs on the local machine.
3. Link LDAP Groups with Connectware Roles
Login into Connectware as admin and navigate to the section User Management / Users and Roles. Click on Roles and afterwards on Add Role.
Name the new role LDAP-Admin and copy the permissions from the existing role connectware-admin.
To associate this role with the LDAP group cw-minimal, you have to copy the whole DN of that LDAP group to the field DN of AD group. In our example this will be CN=cw-admin,OU=connectware,DC=example,DC=org
Click on Create and your new role is added.
Add another role, name it LDAP-Minimal, copy permissions from minimum-access and add the DN of the related LDAP group CN=cw-minimum,OU=connectware,DC=example,DC=org.
4. Assign LDAP Users to LDAP Groups
Now you could assign different Connectware roles to your users user1 user2 user3 by adding them to, or removing them from the groups cw-minimal or cw-admin.
When you add user1 to the group cw-admin and login at Connectware, the user1 will be created (if it is the first login) and the role LDAP-Admin will be assigned automatically.
Now logout from Connectware, remove user1 from group cw-admin and add it to CW-Minimal.
Login at Connectware with user1 again. You’ll realize, that user1 has limited access and you can’t navigate to the user section. Permissions of user1 changed according to the LDAP group membership.
If you login as user2 and user2 is not assigned to any LDAP group yet, the user2 will be created but you’ll see an error dialog saying that no permission was added and thus you will be forced to logout again.
Example Setup for LDAP Mode Attribute
LDAP setup
Configure Connectware with LDAP parameters
Assign roles to LDAP user entry
1. LDAP Setup
The following examples assume to have an LDAP DIT 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. Configure Connectware with LDAP Parameters
Edit the file .env as follows:
Be aware of adjusting the LDAP url.
3. Assign roles to LDAP user entry
To assign roles to LDAP users you have to add the Connectware role names as values to the users CYBUS_LDAP_ROLES_ATTRIBUTE that you defined in the .env file. In our example, we will use the attribute name employeeType.
To add the Connectware role connectware-admin to the LDAP user user1, add the attribute employeeType (defined as roles attribute in the .env file) with the value connectware-admin to the LDAP user user1
Add the Connectware role minimum-access to the user2 by adding the attribute employeeType with the value minimum-access to the LDAP user user2.
You could check if the attributes have been set correctly by cunning the following command:
you shall see something like this:
If you now log into Connectware as user1, the Connectware role connectware-admin will be assigned to the user user1.
To revoke access to Connectware for a certain user, the Connectware roles just have to be removed from the LDAP user again 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.
User Management for LDAP Users in Connectware
LDAP can be used to connect to your local user directory service to authenticate and authorize Connectware users during login to verify credentials and synchronize with assigned roles.
LDAP User Management in Connectware is different in a few ways from regular Connectware users:
Roles
You can not 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 synched to the Connectware user on each successful login.
GrantTypes
Every LDAP user is defaulting to token authentication. This property is not modifiable.
Permissions
You are still able to add and remove additional permissions to the LDAP user. All additional permissions stay active until they are either individually removed from the user profile or the local user information are deleted from the Connectware (see Deleting LDAP Users).
LDAP User Password
You can not change the password from within Connectware as it uses the LDAP directory service for authentication.
Deleting LDAP Users
You can still remove LDAP users from the Connectware user database. Please keep in mind that this only deletes the Connectware internal user information. Deleting these local user information will not restrict the user from logging into Connectware again. To completely revoke access of an LDAP user to Connectware, you have to either remove all Connectware user roles from that user or remove him from LDAP groups linked with Connectware roles, depending on the LDAP integration mode you’re using.
LDAP Filters
All LDAP search filter values need to be escaped via the XX hex notation defined by the RFC4515 standard.
This means that every non basic UTF-8 character used as filter value needs to be replaced with the appropriate hex values defined in Chapter-3 of the IETF transcript.
RFC4515 Excerpt
Example
For an exhaustive list of valid UTF-8 characters and their respective hex value, please consult UTF-8 .
Last updated
