.. _user/ldap: ################## LDAP Configuration ################## .. note:: LDAP integration is an optional Connectware feature which requires Enterprise Edition License. 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 modes ====================== The Connectware LDAP integration supports to ways of authentication and authorization called LDAP modes. 1. **Group mode** : permissions of Connectware users will be set by LDAP group memberships 2. **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 authenticate 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 :code:`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 whithin the LDAP Directory Information Tree (DIT) and share the same base DN. E.g. the base DN is :code:`cn=users,dc=example,dc=org` and the DN of all users are of kind :code:`,cn=users,dc=example,dc=org` - groups are not nested: E.g a user that is member of :code:`group A` and :code:`group A` is member of :code:`group B` and :code:`group B` is the groups that is linked with a Connectware role. When no dedicated bind user is used, Connectware takes the given :code:`bind DN`, adds the :code:`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 :code:`user 1` has the DN :code:`cn=user1,cn=foo,dc=example,dc=org` and :code:`user2` has the DN :code:`cn=user2,cn=bar,dc=example,dc=org`. In order to find the user entry, a search is required with the base :code:`dc=example,dc=org` as 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 :ref:`user/configuration/env` must be configured: - **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_BIND_DN:** - **CYBUS_LDAP_BIND_PASSWORD:** Has to be set when dedicated bind user shall be used. If not set :code:`CYBUS_LDAP_BIND_DN` will be used as base DN for generating a bind DN with credentials of the user that logs in. - **CYBUS_LDAP_MODE:** The mode that shall be used. Either :code:`group` or :code:`attribute` - **CYBUS_LDAP_URL:** The URL LDAP/AD server . - **CYBUS_LDAP_SEARCH_BASE:** Only valid when dedicated bind user is used (:code:`CYBUS_LDAP_BIND_PASSWORD` is set) in order to perform search requests for the user that logs in. 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:** [optional] Only valid with dedicated user is used. Additional custom filter that could be used for user search requests. - **CYBUS_LDAP_ROLES_ATTRIBUTE:** Only valid in combination with :code:`CYBUS_LDAP_MODE=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_MEMBER_ATTRIBUTE:** The LDAP attribute name indicating the group memberships. Only valid in combination with :code:`CYBUS_LDAP_MODE=group`. The value usually is :code:`memberOf`. - **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. - **CYBUS_LDAPS_TRUST_ALL_CERTS** Only valid in combination with Secure LDAP. When set to :code:`true` Connectware will accept all servers without certificate check. When set to :code:`false` a certificate has to be given. The default value is :code:`false` - **CYBUS_LDAPS_CA_FILE** Only valid in combination with Secure LDAP and when :code:`CYBUS_LDAPS_TRUS_ALL_CERTS` is set to :code:`false`. Sets the path to the CA file that is used to validate the LDAP server. - **CYBUS_LDAP_AUTO_ENFORCE_MFA** When set to :code:`true`, then LDAP users get enforced to enable MFA after the very first login. Configuration ============= This description applies to a docker-compose deployment (see :ref:`user/configuration/env/docker`), not a kubernetes one. 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 CYBUS_LDAP_ENABLED=false CYBUS_LDAP_MODE= CYBUS_LDAP_BIND_DN= CYBUS_LDAP_URL= CYBUS_LDAP_USER_RDN= CYBUS_LDAP_ROLES_ATTRIBUTE= CYBUS_LDAP_MEMBER_ATTRIBUTE= 4. Set the individual parameters according to your local directory service configuration. Example configuration for LDAP mode :code:`Attribute`: .. code-block:: bash CYBUS_LDAP_ENABLED=true CYBUS_LDAP_MODE=attribute CYBUS_LDAP_BIND_DN=ou=tech,dc=example,dc=org CYBUS_LDAP_URL=ldap:// CYBUS_LDAP_USER_RDN=cn CYBUS_LDAP_ROLES_ATTRIBUTE=employeeType Example configuration for LDAP mode :code:`Group`: .. code-block:: bash CYBUS_LDAP_ENABLED=true CYBUS_LDAP_MODE=group CYBUS_LDAP_BIND_DN=ou=tech,dc=example,dc=org CYBUS_LDAP_URL=ldap:// CYBUS_LDAP_USER_RDN=cn CYBUS_LDAP_MEMBER_ATTRIBUTE=memberOf 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! **Configuration with dedicated Bind User** Example configuration for LDAP mode :code:`Attribute`: .. code-block:: bash CYBUS_LDAP_ENABLED=true CYBUS_LDAP_MODE=attribute CYBUS_LDAP_BIND_DN=cn=,ou=tech,dc=example,dc=org CYBUS_LDAP_BIND_PASSWORD= CYBUS_LDAP_SEARCH_BASE=dc=example,dc=org CYBUS_LDAP_URL=ldap:// CYBUS_LDAP_USER_RDN=cn CYBUS_LDAP_ROLES_ATTRIBUTE=employeeType Example configuration for LDAP mode :code:`Group`: .. code-block:: bash CYBUS_LDAP_ENABLED=true CYBUS_LDAP_MODE=group CYBUS_LDAP_BIND_DN=cn=,ou=tech,dc=example,dc=org CYBUS_LDAP_BIND_PASSWORD= CYBUS_LDAP_SEARCH_BASE=dc=example,dc=org CYBUS_LDAP_URL=ldap:// CYBUS_LDAP_USER_RDN=cn CYBUS_LDAP_MEMBER_ATTRIBUTE=memberOf (be aware to change the RDN prefix (cn) if needed for CYBUS_LDAP_BIND_DN=cn=,ou=tech,dc=example,dc=org) 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 (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 follwing steps: 1. Define LDAP groups according to Connectware roles 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 accoding 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 conecept. Assuming we have the following DIT: .. code-block:: bash dc=example,dc=org ├ cn=users │ ├ cn=user1 │ ├ cn=user2 │ └ cn=user3 └ ou=connectware Create 2 groups :code:`cw-admin` and :code:`cw-minimal` as follows: .. code-block:: bash dc=example,dc=org ├ cn=users │ ├ cn=user1 │ ├ cn=user2 │ └ cn=user3 └ ou=connectware ├ cn=cw-minimal └ cn=cw-admin Now add :code:`user1` to :code:`cw-minimal`. If you run the command (change :code:`PASSWORD` to password of :code:`user1`) .. code-block:: bash ldapsearch -LLL -b "cn=user1,cn=users,DC=example,DC=org" -D "CN=user1,cn=users,DC=example,DC=org" -w PASSWORD you shall see something like this: .. code-block:: bash dn: CN=user1,CN=users,DC=example,DC=org objectClass: top objectClass: person objectClass: organizationalPerson objectClass: user cn: user1 ... memberOf: CN=cw-minimal,OU=connectware,DC=example,DC=org ... If you are using OpenLDAP and you do not see the attribute :code:`memberOf` you shall try the following command: .. code-block:: bash ldapsearch -LLL -b "cn=user1,cn=users,DC=example,DC=org" -D "CN=user1,cn=users,DC=example,DC=org" -w PASSWORD + If you see the attribute :code:`memberOf` now, your configuration is using :code:`memberOf` as operation attribute (becomes important in the next step). If you still do not see the attribute :code:`memberOf`, your OpenLdap is missing the :code:`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 :code:`.env` as follows: .. code-block:: bash CYBUS_LDAP_ENABLED=true CYBUS_LDAP_MODE=group CYBUS_LDAP_BIND_DN=ou=users,dc=example,dc=org CYBUS_LDAP_URL=ldap://127.0.0.1:389 CYBUS_LDAP_MEMBER_ATTRIBUTE=memberOf CYBUS_LDAP_USER_RDN=cn Be aware of adjusting the LDAP url, the given example uses an Active Directory service that run on the local machine. 3. Link LDAP groups with Connectware roles ------------------------------------------ Login into Connectware as :code:`admin` and navigate to the section **User Management / Users and Roles**. Click on **Roles** and afterwards on **Add Role**. Name the new role :code:`LDAP-Admin` and copy the permissions from the existing role :code:`connectware-admin`. To associate this role with the LDAP group :code:`cw-minimal`, you have to copy the whole DN of that LDAP group to the field :code:`DN of AD group`. In our example this will be :code:`CN=cw-admin,OU=connectware,DC=example,DC=org` .. figure:: ../../resources/ldap/ldap_create_role_group.png :width: 600px Click on **Create** and your new role is added. Add another role, name it :code:`LDAP-Minimal`, copy permissions from :code:`minimum-access` and add the DN of the related LDAP group :code:`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 :code:`user1` :code:`user2` :code:`user3` by adding them to, or removing them from the groups :code:`cw-minimal` or :code:`cw-admin`. When you add :code:`user1` to the group :code:`cw-admin` and login at Connectware, the :code:`user1` will be created (if it is the first login) and the role :code:`LDAP-Admin` will be assigned automatically. Now logout from Connectware, remove :code:`user1` from group :code:`cw-admin` and add it to :code:`CW-Minimal`. Login at Connecteare with :code:`user1` again. You'll realize, that :code:`user1` has limited access and you can't navigate to the user section. Permissions of :code:`user1` changed according to the LDAP group membership. If you login as :code:`user2` and :code:`user2` is not assigned to any LDAP group yet, the :code:`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 ===================================== 1. LDAP setup 2. Configure Connectware with LDAP parameters 3. Assign roles to LDAP user entry 1. LDAP setup ------------- The following examples assume to have an LDAP DIT like the follwoing: .. code-block:: bash dc=example,dc=org └ cn=users ├ cn=user1 └ cn=user2 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 :code:`.env` as follows: .. code-block:: bash CYBUS_LDAP_ENABLED=true CYBUS_LDAP_MODE=attribute CYBUS_LDAP_BIND_DN=ou=users,dc=example,dc=org CYBUS_LDAP_URL=ldap://127.0.0.1:389 CYBUS_LDAP_ROLES_ATTRIBUTE=employeeType CYBUS_LDAP_USER_RDN=cn 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 :code:`.env` file. In our example, we will use the attribute name :code:`employeeType`. To add the Connectware role :code:`connectware-admin` to the LDAP user :code:`user1`, add the attribute :code:`employeeType` (defined as roles attribute in the :code:`.env` file) with the value :code:`connectware-admin` to the LDAP user :code:`user1` Add the Connectware role :code:`minimum-access` to the :code:`user2` by adding the attribute :code:`employeeType` with the value :code:`minimum-access` to the LDAP user :code:`user2`. You could check if the attributes have been set correctly by cunning the following command: .. code-block:: bash ldapsearch -LLL -b "cn=user1,cn=users,DC=example,DC=org" -D "CN=user1,cn=users,DC=example,DC=org" -w PASSWORD you shall see something like this: .. code-block:: bash dn: CN=user1,CN=users,DC=example,DC=org objectClass: top objectClass: person objectClass: organizationalPerson objectClass: user cn: user1 ... employeeType: connectware-admin ... If you now log into Connectware as :code:`user1`, the Connectware role :code:`connectware-admin` will be assigned to the user :code:`user1`. To revoke access to the Connectware for a certain user, the Connectware roles just have to be removed from the LDAP user again by deleting the corresponding attribute :code:`employeeType`. The Connectware comes with predefined user roles like :code:`connectware-admin` and :code:`minimum-access` but additional roles can be created and assigned to users in the same way. User Management for LDAP Users in Connectware ============================================= .. figure:: ../../resources/ldap/ldap_user_list.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 ------------------- 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 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. .. _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