.. _user/ldap: ################## 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 :code:`tech` department within the domain space :code:`cybus.io`: :code:`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. :code:`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 :code:`/opt/connectware`. 2. The directory contains a :code:`.env` file that is loaded when starting the Connectware. Open the :code:`.env` file in a text editor of your choice. 3. Locate the LDAP settings section in the :code:`.env` file. By default the settings should look like this: .. code-block:: bash # 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: .. code-block:: bash # 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:// CYBUS_LDAP_ROLES_ATTRIBUTE=employeeType CYBUS_LDAP_USER_RDN=cn This configuration would look for users applicable to the LDAP query :code:`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 :code:`docker-compose up -d` from within the installation folder. If the Connectware instance is running as system service please restart by executing :code:`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 :code:`.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 :code:`connectware-operator` to **ldap_user_1** which already exists in you directory service. - The **CYBUS_LDAP_ROLES_ATTRIBUTE** in the :code:`.env` file is set to :code:`employeeType`. **Needed LDAP user configuration:** - :code:`connectware-operator` has therefore to be a value of the attribute :code:`employeeType` in the directory user details. Example Connectware .env file ----------------------------- .. code-block:: bash # LDAP CYBUS_LDAP_ENABLED=true CYBUS_LDAP_SEARCH_FILTER=(cn={{username}}) CYBUS_LDAP_SEARCH_BASE=dc=cybus,dc=io CYBUS_LDAP_URL=ldap:// CYBUS_LDAP_ROLES_ATTRIBUTE=employeeType CYBUS_LDAP_USER_RDN=cn Example LDAP user details ------------------------- .. code-block:: # 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 :code:`connectware-admin` and :code:`connectware-operator` but additional roles can be created and assigned to users in the same way. User Management (Connectware) ============================= .. figure:: ../resources/ldap/ldap_user_view.png :width: 600px 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: .. figure:: ../resources/ldap/ldap_user_details.png :width: 600px 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 ------------------- .. figure:: ../resources/ldap/ldap_user_delete.png :width: 600px 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. .. _user/ldap/filters: 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 --------------- .. code-block:: bash 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 ------- .. code-block:: bash 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_ . .. _Documentation: https://github.com/trentm/node-ldapauth#expressconnect-basicauth-example .. _RFC4515: https://tools.ietf.org/search/rfc4515 .. _Chapter-3: https://tools.ietf.org/search/rfc4515#section-3 .. _UTF-8: https://www.utf8-chartable.de/unicode-utf8-table.pl