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 spacecybus.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 toemployeeType
.
Needed LDAP user configuration:
connectware-operator
has therefore to be a value of the attributeemployeeType
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)¶
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:
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¶
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 ("~")