LDAP

  • Updated on Nov 6, 2024
  • Published on Sep 17, 2024
  • 2 minute(s) read

LDAP (Lightweight Directory Access Protocol) is a protocol used to access and manage directory information. It’s applied for centralized authentication and stores information about users and groups. It allows for single sign-on across multiple applications or services. LDAP directories organize data hierarchically and can be accessed by various applications to retrieve or update information such as user credentials, contact details, or organizational structures.

LDAP is available only for on-premise / private cloud instances of Hyperscience.

LDAP parameters

Mandatory configurations

  • LDAP server address

    • Example: ldap://dc.example.com:389

LDAP Server Address:FORMS_LOGIN_ENABLE_LDAP=true
FORMS_LDAP_AUTH_URL=ldap://<LDAP server address>

  • LDAP search base

    • Example: ou=hs_users,dc=example,dc=com

FORMS_LDAP_AUTH_SEARCH_BASE=<search base>

  • LDAP admin group

    • Example: cn=hs_admins,dc=example,dc=com

FORMS_LDAP_ADMIN_GROUP=<LDAP admin group>

With this example configuration, any user in the <search base> and the <LDAP admin group> can log in and be granted admin privileges. An admin can configure additional LDAP groups and related permissions through the UI.

Active Directory

When using Microsoft Active Directory, you need to provide the following additional configuration:

FORMS_LDAP_AUTH_ACTIVE_DIRECTORY_DOMAIN=<domain>

Make sure that the domain's value is the DNS name and not the NetBIOS domain name. For example, the NetBIOS name could be HSCORP while the DNS name is hscorp.hyperscience.com.

The bind to the AD server will be done using <user>@<domain>, where <user> is taken from what is typed into the username box during login. 

Open LDAP 

When using OpenLDAP or OpenLDAP-based solution you need to provide the following additional settings:

  • Example: %username%@example.com

FORMS_LDAP_AUTH_USERNAME_FORMAT=bind dn pattern

The value must be a string with a placeholder called “%username%”.  

When you log in to Hyperscience, this string is used to create a personalized bind DN by replacing “%username%” with the username you type into the login box.

Optional Configurations

LDAP over TLS or LDAP over SSL

Hyperscience also allows you to configure LDAP over TLS (STARTTLS) or LDAP over SSL (LDAPS).

To configure STARTTLS, you need to set the following variables:

FORMS_LDAP_AUTH_USE_TLS=true
FORMS_LDAP_AUTH_URL=ldap://:389

To configure LDAPS, you need to set the following variables:

FORMS_LDAP_AUTH_USE_TLS=false
FORMS_LDAP_AUTH_URL=ldaps://:636

Advanced user filtering

By default, any users within FORMS_LDAP_AUTH_SEARCH_BASE and of the correct FORMS_LDAP_AUTH_OBJECT_CLASS will be considered valid users. You can apply further filtering by setting custom groups and user filters.

  • Note that you can supply only one group when setting up. The filter appends (memberOf=<group>):

    • Example: cn=SpecialGroup,OU=hs_users,dc=example,dc=com

FORMS_LDAP_AUTH_GROUP_FILTER=<group>

  • When set up, the filter appends the value as an additional search filter. Example: (sn=Smith): 

FORMS_LDAP_AUTH_USER_FILTER=<additional user filter>

  • Hyperscience supports Complex Expressions as well if they are represented as valid RFC2254 filters. For example:

(|(sn=specialuser)(uid=34))

Complex expressions are intricate search conditions in LDAP queries, incorporating logical operators and grouping. RFC2254 filters define how search criteria are structured in LDAP queries. Learn more at Datatracker.

Search User

Hyperscience performs searches using the user who is currently logging in. However, there are situations where certain users have restrictions and cannot perform searches. In such cases, you have the option to designate an alternative user who will perform the searches instead.

  • Example: cn=searchuser,ou=hs_users,dc=example,dc=com

FORMS_LDAP_AUTH_CONNECTION_USERNAME=
FORMS_LDAP_AUTH_CONNECTION_PASSWORD=

Advanced user mapping

Hyperscience does not provide custom mappings for names, it always uses 'givenName' for the first name and 'sn' for the last name. Learn how to map authentication groups from your identity provider to Hyperscience permission groups in the “Managing Authentication Groups” article for your version of the product.

The following options should not be changed from their defaults unless there is an explicit environment requirement.

  • Specifying the object class for users:

    • FORMS_LDAP_AUTH_OBJECT_CLASS= # defaults to 'user'

  • Specifying username attribute:

    • FORMS_LDAP_USERNAME_ATTRIBUTE_NAME= # defaults to 'sAMAccountName'