---
title: "LDAP"
slug: "ldap"
updated: 2025-07-28T23:10:40Z
published: 2025-07-28T23:10:40Z
canonical: "help.hyperscience.ai/ldap"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.hyperscience.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LDAP

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.

> [!NOTE]
> 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*

```plaintext
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*

```plaintext
FORMS_LDAP_AUTH_SEARCH_BASE=<search base>
```

- **LDAP admin group**
  - **Example:** *cn=hs_admins,dc=example,dc=com*

```plaintext
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:

```plaintext
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*

```plaintext
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:

```plaintext
FORMS_LDAP_AUTH_USE_TLS=true
FORMS_LDAP_AUTH_URL=ldap://:389
```

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

```plaintext
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*

```plaintext
FORMS_LDAP_AUTH_GROUP_FILTER=<group>
```

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

```plaintext
FORMS_LDAP_AUTH_USER_FILTER=<additional user filter>
```

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

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

> [!NOTE]
> 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](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*

```plaintext
FORMS_LDAP_AUTH_CONNECTION_USERNAME=
FORMS_LDAP_AUTH_CONNECTION_PASSWORD=
```

#### Advanced user mapping

> [!NOTE]
> 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:
  - ```plaintext
FORMS_LDAP_AUTH_OBJECT_CLASS= # defaults to 'user'
```
- Specifying username attribute:
  - ```plaintext
FORMS_LDAP_USERNAME_ATTRIBUTE_NAME= # defaults to 'sAMAccountName'
```