LDAP/S

Setup LDAP/S

To authenticate users in LUY via LDAP/S and Active Directory, it is necessary to configure and mount the luy_ldap_properties.yml.

In the following section, we describe how the property file looks like:

CODE

luy:
  auth:
    ldap:
      # A list of LDAP server URLs. Servers will be connected in the specified order.
      # An URL should start with 'ldap://' or 'ldaps://' and preferably include the port number.
      urls: 
        - ldap://URL:port
        # - ldap.url2
        # - ldap.url3
        # - ldap.url4

      # The base suffix from which all operations should originate. Example: dc=luy,dc=app
      base: dc=luy,dc=app
      
      # The user distinguished name (principal) to use for getting authenticated contexts as system user.
      # In an Active Directory, it is best written as username@FullDomainName, e.g. abc@luy.app      
      user-dn: username@FullDomainName

      # The system user's password (credentials) for getting authenticated contexts.      
      # Consider using environment variables or other secure methods for storing and accessing sensitive data.
      password: Password

      users:
        # If you're using an LDAP user search method that supports searching with multiple search bases,
        # you can specify multiple subtrees separated with '|' here. For instance:
        # ldap.users.searchbase=cn=Users|cn=Employee,ou=Research
        
        # If you're not using a LDAP user search method that requires this configuration,
        # it's recommended to keep this field blank.
        search-base: ~
        
        # The LDAP search filter used to identify the user object corresponding to the login attempt.
        # This filter should only return a single result. In some directories, user object DNs
        # may not contain the username but rather the common name. Therefore, a filter with a 
        # placeholder {0} representing the username is required. Ensure the filter includes this placeholder.
        # The default value is typical for Active Directory installations.
        # Only modify this property if you are familiar with LDAP filter syntax, your directory structure, 
        # and understand the implications.
        search-filter: (&(sAMAccountName={0})(objectClass=user))
        
        attributes:
          # The names of the fields within the directory to be used for users firstname, lastname and email address   
          first-name: givenname
          last-name: sn
          email: mail
          
      roles:
        # Subtree (relative to ldap.base!) where role objects are searched. Leaving this property empty
        # results in searching the entire directory, returning *every* role of the user. You can restrict
        # the search scope to a subtree with this property. It's generally safest to leave it empty.
        
        # If you're not using a LDAP roles search method that requires this configuration,
        # it's recommended to keep this field blank.        
        search-base: ~
        
        # The roles filter used to find roles where the user is a member. The placeholder {0} is replaced
        # by the user object's DN. Alternatively, you can use {1} to search with the username.
        # Most users can keep the default value, as 'member' is the most common attribute. However, some directories
        # use 'uniqueMember'.
        membership-filter: (member={0})
        
        # Prefix for all LDAP role names. This is only useful, if all LUY roles are
        # guaranteed to carry this prefix in their name 
        # For most users, this property should remain empty, i.e. LUY role names and LDAP role names
        # are mapped 1:1 onto each other. It's recommended to keep this field blank.
        name-prefix: ~
        
        # A role name that will be assigned to all users upon login.
        # This is useful for granting a minimum set of privileges to all users, regardless of
        # any explicitly assigned roles. To activate this setting, you must create a role with
        # the exact same name using LUY's role management.
        default-role: ~

default-role:

Specify a LUY role to be assigned to every authenticated user via LDAP/S by default. This role is additionally added to the sent groups from the logged in user.

Use the role "luy_Supervisor" to initially create and manage other roles.

E.g. default-role: luy_Supervisor

Afterwards, this role needs to be removed and the default value '~' can be set.
A restart of LUY is required to apply the changes.

Roles

LUY matches its own roles with the user groups sent by the Active Directory.

For example:
When Alice logs into LUY, her user profile indicates that she belongs to both the "admin" and "employee" groups which are sent by the Active Directory. Within LUY, predefined roles such as "admin" and "architect" exist. Upon login, Alice's "admin" group aligns with the "admin" role in LUY, thanks to the identical naming convention. The group "employee" as well as the LUY role "architect" are ignored since there is no match for them. Alice is then assigned only the permissions of the LUY role "admin".

Configure LDAPS

Some LDAP servers offer secured communication over SSL. In order to active LDAP-over-SSL, specify your server with an ldaps:// URL and import the respective CA certificate that is required to verify the LDAP server certificate.

Obtain the CA certificate from the LDAP server. Ideally, the certificate file is in PEM format. Import the certificate into the Java key management.

Extract the Java keystore from the Docker container:

CODE

# Determine container id
sudo docker ps
# Extract certificate store
sudo docker cp <container_id>:/usr/lib/jvm/jre/lib/security/cacerts ./cacerts

Import the certificate in the extracted keystore:

CODE

CMD:
"%JAVA_HOME%\bin\keytool" -importcert -file ca.crt -keystore "%JAVA_HOME\lib\security\cacerts" -storepass changeit -alias LdapCA
when the "JRE" is used
"%JRE_HOME%\bin\keytool" -importcert -file ca.crt -keystore "%JRE_HOME\lib\security\cacerts" -storepass changeit -alias LdapCA
 
Linux Terminal:
keytool -importcert -file ca.crt -keystore $JRE_HOME\lib\security\cacerts -storepass changeit -alias LdapCA

Map the adjusted keystore bin into the Docker container by adding the following line under the volumes section in the compose.yml:

CODE

- ./cacerts:/usr/lib/jvm/jre/lib/security/cacerts

PRE-AUTH-LDAP (LDAP+SSO)

We strongly recommend SAML2 over LDAP + SSO.

To authenticate users in LUY over LDAP + SSO with Active Directory, it is necessary to config and mount the luy-ldap-pre-auth-properties.yml.

The configuration is the same as for LDAPS above, with the exception of the line
“pre-auth-user-header-name” that needs to be configured:

CODE

      # It might be necessary to modify the logon-user header variable.       
      pre-auth-user-header-name: logon-user

If there are any issues with LDAP+SSO authentication, our LUY support can offer only limited assistance.