# LDAP - Updated on Jul 28, 2025 - 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_ Custom ```plaintext LDAP Server Address:FORMS_LOGIN_ENABLE_LDAP=true FORMS_LDAP_AUTH_URL=ldap:// ``` Plain text Copy - **LDAP search base** - **Example:** _ou=hs\_users,dc=example,dc=com_ Custom ```plaintext FORMS_LDAP_AUTH_SEARCH_BASE= ``` Plain text Copy - **LDAP admin group** - **Example:** _cn=hs\_admins,dc=example,dc=com_ Custom ```plaintext FORMS_LDAP_ADMIN_GROUP= ``` Plain text Copy With this example configuration, any user in the and the 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: Custom ```plaintext FORMS_LDAP_AUTH_ACTIVE_DIRECTORY_DOMAIN= ``` Plain text Copy 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 _@_, where __ 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_ Custom ```plaintext FORMS_LDAP_AUTH_USERNAME_FORMAT=bind dn pattern ``` Plain text Copy 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: Custom ```plaintext FORMS_LDAP_AUTH_USE_TLS=true FORMS_LDAP_AUTH_URL=ldap://:389 ``` Plain text Copy To configure LDAPS, you need to set the following variables: Custom ```plaintext FORMS_LDAP_AUTH_USE_TLS=false FORMS_LDAP_AUTH_URL=ldaps://:636 ``` Plain text Copy #### 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=)_: - **Example:** _cn=SpecialGroup,OU=hs\_users,dc=example,dc=com_ Custom ```plaintext FORMS_LDAP_AUTH_GROUP_FILTER= ``` Plain text Copy - When set up, the filter appends the value as an additional search filter. Example: ( _sn=Smith_): Custom ```plaintext FORMS_LDAP_AUTH_USER_FILTER= ``` Plain text Copy - Hyperscience supports Complex Expressions as well if they are represented as valid RFC2254 filters. For example: Custom ```plaintext (|(sn=specialuser)(uid=34)) ``` Plain text Copy > 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 (opens in new tab)](https://datatracker.ietf.org/doc/html/rfc2254). #### 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_ Custom ```plaintext FORMS_LDAP_AUTH_CONNECTION_USERNAME= FORMS_LDAP_AUTH_CONNECTION_PASSWORD= ``` Plain text Copy #### 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: - Custom ```plaintext FORMS_LDAP_AUTH_OBJECT_CLASS= # defaults to 'user' ``` Plain text Copy - Specifying username attribute: - Custom ```plaintext FORMS_LDAP_USERNAME_ATTRIBUTE_NAME= # defaults to 'sAMAccountName' ``` Plain text Copy