# LDAP

LDAP Authentication integration provides the ability to authenticate your users directly against an LDAP service such as OpenLDAP or Active Directory.

LDAP Users are not imported into Form.io as Resources and exist only externally in LDAP. They still get assigned Form.io roles and can have ownership over forms and submissions.

## Setup

To start using LDAP for your authentication, you will need the following parameters from your LDAP provider.

| Setting       | Description                                                                                                                                                                         |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Server URL    | LDAP server URL, eg. *ldaps\://ldap.example.org:663*                                                                                                                                |
| Bind DN       | Admin connection DN, e.g. *uid=myapp,ou=users,dc=example,dc=org*.                                                                                                                   |
| Bind Password | Password for bindDN.                                                                                                                                                                |
| Search Base   | The base DN from which to search for users by username. E.g. *ou=users,dc=example,dc=org*                                                                                           |
| Search Filter | LDAP search filter with which to find a user by username, e.g. *(uid={{username}})*. Use the literal *{{username}}* to have the given username interpolated in for the LDAP search. |

### Test Configurations

If you wish to simply test the LDAP functionality, you can use the following parameters:

* Server URL: `ldap://ldap.forumsys.com:389`
* Bind DN: `cn=read-only-admin,dc=example,dc=com`
* Bind Password: `password`
* Search Base: `dc=example,dc=com`
* Search Filter: `(uid={{username}})`

With these configurations, you should then be able to use the following login credentials.

* Username: `einstein`
* Password: `password`

### Project Configuration

Once you have these configurations, you can setup LDAP within your Project Settings like so.

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FTbqNGtQVzc6Rr1vd0dJV%2Fldap1.png?alt=media\&token=64f61270-7869-42ec-b483-0f62a78dd674)

By default Form.io uses email addresses to login in users so using the email attribute in the search filter is recommended unless you change the User Login form to match the search filter. For example `(mail={{username}})`

{% hint style="info" %}
LDAP user accounts are created and managed outside of the Form.io environment. Users attempting to view their account information from the Portal UI will receive an Error since Form.io does not manage this information. Create and manage LDAP accounts from the LDAP service provider or contact your system administrator.
{% endhint %}

Click **Save Project Settings** once you have these values set.

## LDAP Login Form

Next, we will create a new form that will be used to Login to LDAP. We can do this by clicking on **New Form**, and then building it as follows.

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FCFjYJdz3EmGiqN2MUAXj%2Fldap2.png?alt=media\&token=ae2487dd-9aea-4f3e-b4d6-f94a40c0fb25)

Click **Create Form** button to create the new form.

## LDAP Login Form Access

You will now need to ensure that Anonymous users are able to "submit" this form, which will execute the actions assigned to the form. You can do this by clicking on the **Access** settings and adding the **Anonymous** role to the **Create Own** permission.

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FWCnlRv5g9hjNL1FZxlmD%2Fldap3.png?alt=media\&token=65747513-5fed-44f6-b7e0-f2bee8b1fffa)

## LDAP Login Action

Next, we will navigate to the Actions section of our form and first **Remove the Save Submission Action**.

After we have done, that we will add the LDAP Login action as follows.

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FDO2BSus8Q2kFgWdlJPyf%2Fldap4.png?alt=media\&token=d7bed997-503b-4b13-b49b-a62787b189cf)

Within the LDAP Login Action, you will then configure the following parameters.

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FPZqsLSzw9RPOHQ2lY6Ht%2Fldap5.png?alt=media\&token=4ba4fe49-7ba9-4a0a-8d51-b373bb109dbf)

If you choose the Passthrough option, any failures except for a failure to Bind the user account, will be ignored and the login information will be passed to the next form action. This allows using both LDAP and the Form.io Login action on the same form.

### Assign Roles

Next map any LDAP properties to user roles. Select the property, the matching value and the role to assign it true. Leave LDAP Property and Value blank to assign the role to all LDAP accounts.

For example:

* LDAP Property: group
* Value: Admins
* Role: Admin

Would assign the Admin role to any members of the Admins group.

The user’s DN is also mapped to the list of properties so if the DN is `dn=myname,ou=admins,dc=example,dc=org` you can do:

* LDAP Property: ou
* Value: admins
* Role: Admin

After you have the Login action set, you can save this action to add this to the form.

## Testing LDAP Login

If you provided the Test Credentials at the top of the page, then you should be able to perform the following API request within **Postman** to perform and test out an LDAP login.

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MPHoF2HwOA0s5HV_AIB%2F-Mfs6h87znix-NB0xRxf%2F-MfsAgUt4LucJS0yPKap%2FPostman%202021-07-30%2011-08-49.png?alt=media\&token=9bdbf94e-4a3e-48d0-abc4-1b8c2e2b332a)

Here you will see that the **Authenticated** role has been assigned to the user object.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.form.io/developers/auth/ldap.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.