LDAP Configuration

Note

LDAP integration is a optional Connectware feature which can be purchased in addition to the standard feature set. If you are interested in LDAP integration for your organization please contact our sales team at sales@cybus.io.

The 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 the Connectware.

Connectware LDAP Parameters

  • CYBUS_LDAP_ENABLED: If true, the LDAP integration feature will be enabled. If false, LDAP will not be used and all other LDAP parameters are ignored.

  • CYBUS_LDAP_URL: The URL of the user directory database.

  • CYBUS_LDAP_SEARCH_BASE: This is the starting point (technically, the prefix) for all LDAP searches in the directory tree and thus has to be generally applicable to all Connectware users in the user database. An example would be to narrow down the amount of candidates to users in the tech department within the domain space cybus.io: ou=tech,dc=cybus,dc=io.

  • CYBUS_LDAP_SEARCH_FILTER: A filter that in combination with the CYBUS_LDAP_SEARCH_BASE forms the complete LDAP search query. This describes the user specific part of the query(see the Documentation for more details).

  • CYBUS_LDAP_ROLES_ATTRIBUTE: An LDAP attribute that has to be common to all Connectware users in the user directory. This attribute has to contain all roles the Connectware user is assigned to.

  • CYBUS_LDAP_USER_RDN: The LDAP user property (e.g. cn) that contains the username as it is typed into the Connectware login prompt.

Configuration

Important

Managed appliances can not be configured for LDAP integration. This tutorial is focusing on selfhosted instances only.

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 the 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:

# LDAP
CYBUS_LDAP_ENABLED=false
CYBUS_LDAP_SEARCH_FILTER=
CYBUS_LDAP_SEARCH_BASE=
CYBUS_LDAP_URL=
CYBUS_LDAP_ROLES_ATTRIBUTE=
CYBUS_LDAP_USER_RDN=

4. Set the individual parameters according to your local directory service configuration.

Example configuration:

# LDAP
CYBUS_LDAP_ENABLED=true
CYBUS_LDAP_SEARCH_FILTER=(cn={{username}})
CYBUS_LDAP_SEARCH_BASE=ou=tech,dc=example,dc=org
CYBUS_LDAP_URL=ldap://<LDAPSERVERURL>
CYBUS_LDAP_ROLES_ATTRIBUTE=employeeType
CYBUS_LDAP_USER_RDN=cn

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!

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.

User Management (Directory Service)

To assign roles to directory 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. Roles assigned to directory users are used for authorization and are identified through their respective role name.

Example scenario

Given situation:

  • You want to assign the role of connectware-operator to ldap_user_1 which already exists in you directory service.

  • The CYBUS_LDAP_ROLES_ATTRIBUTE in the .env file is set to employeeType.

Needed LDAP user configuration:

  • connectware-operator has therefore to be a value of the attribute employeeType in the directory user details.

Example Connectware .env file

# LDAP
CYBUS_LDAP_ENABLED=true
CYBUS_LDAP_SEARCH_FILTER=(cn={{username}})
CYBUS_LDAP_SEARCH_BASE=dc=cybus,dc=io
CYBUS_LDAP_URL=ldap://<LDAPSERVERURL>
CYBUS_LDAP_ROLES_ATTRIBUTE=employeeType
CYBUS_LDAP_USER_RDN=cn

Example LDAP user details

# LDIF Export for cn=ldap_user_1,dc=cybus,dc=io

version: 1

# Entry 1: cn=ldap_user_1,dc=cybus,dc=io
dn: cn=ldap_user_1,dc=cybus,dc=io
cn: ldap_user_1
gidnumber: 500
givenname: Max
homedirectory: /home/users/ldap_user_1
objectclass: inetOrgPerson
objectclass: posixAccount
objectclass: top
employeeType: connectware-operator <- necessary change to the LDAP user
employeeType: other-generic-roles
sn: Mustermann
uid: ldap_user_1
uidnumber: 1001
userpassword: ...

To revoke access to the Connectware for a certain user, the Connectware roles just have to be removed from the LDAP directory user details again.

The Connectware comes with two predefined user roles connectware-admin and connectware-operator but additional roles can be created and assigned to users in the same way.

User Management (Connectware)

../_images/ldap_user_view.png

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 the Connectware is different in a few ways from regular Connectware users:

../_images/ldap_user_details.png

Roles

You can not add or remove roles from within the 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 the Connectware as it uses the LDAP directory service for authentication.

Deleting LDAP Users

../_images/ldap_user_delete.png

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 the Connectware again. To completely revoke access of a LDAP user to the Connectware, you have to remove all Connectware user roles from that user in the LDAP directory.

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

EXCLAMATION    = %x21 ; exclamation mark ("!")
AMPERSAND      = %x26 ; ampersand (or AND symbol) ("&")
ASTERISK       = %x2A ; asterisk ("*")
COLON          = %x3A ; colon (":")
VERTBAR        = %x7C ; vertical bar (or pipe) ("|")
TILDE          = %x7E ; tilde ("~")

Example

Clear text search filter: '(cn=*)'

Escaped search filter: '(cn=*\2a*)'

For an exhaustive list of valid UTF-8 characters and their respective hex value, please consult UTF-8 .