Basic Authentication: LDAP Policy | MuleSoft Documentation
# Basic Authentication: LDAP Policy
**Policy Name** | Basic Authentication: LDAP  
---|---  
Allows access based on the basic authorization mechanism, with user-password defined on LDAP  
Security  
**First Mule version available**  
**Returned Status Codes** | 401 - Unauthorized or invalid client application credentials  
## Summary
The Lightweight Directory Access Protocol (LDAP) authentication policy specifies how to restrict access to an API using LDAP authentication mechanism. This policy is available in Flex and Mule 4 or later.
When an error is encountered, the Basic Authentication - LDAP policy returns an "WWW-Authenticate" HTTP header field using the format:`WWW-Authenticate: Basic realm="mule-realm"`.
LDAP is an inverted tree, and each leaf has a username-password pair and associated metadata. Each level is like a tree branch. For more information about LDAP, see About LDAP.
## Configuring Policy Parameters
### Mule Gateway
When you apply the Basic Authentication - LDAP policy to your API from the UI, you can configure the following parameters to connect to your LDAP or Active Directory:
Parameter | Description  
---|---  
LDAP Server URL |  The URL of your LDAP OR LDAPS server, including the port number.  
LDAP User DN |  The name of the user or user group with access to traverse and list users of LDAP.  
LDAP User Password |  The password for the user or user group. The password must be a secure value that, once specified, is not visible or retrievable.  
LDAP Search Base |  The starting point for the search in the directory tree.  
LDAP Search Filter |  The criteria for the filter for the Active Directory or the OpenLDAP model, as shown in the examples.  
Note that all parameters are required to successfully configure LDAP or Active Directory.
## Example Configuration for an Active Directory
You can configure Active Directory for your LDAP authentication by providing the following values:
Field | Example Literal String Value | Example Secure Property Placeholder  
---|---|---  
LDAP Server URL |  ldap://174.19.33.17:389/ |  ${ldap.server.url}  
LDAP Secure Server URL (SSL) |  ldaps://my-company-ldap.cloudhub.io:1010/ |  ${ldap.server.url}  
LDAP Server User DN |  CN=Administrator,CN=Users,DC=my-company,DC=com |  ${ldap.user.dn}  
LDAP User Password |  somePassword |  ${ldap.password}  
LDAP Search Base |  CN=Users,DC=my-company,DC=com |  ${ldap.search.base}  
LDAP Search Filter |  (sAMAccountName={0}) |  ${ldap.search.filter}  
The search filter string in the example is specific to Active Directory applications.
## Example Configuration for OpenLDAP
You can configure OpenLDAP for your LDAP authentication by providing the following values:
Field | Example Literal String Value | Example Secure Property Placeholder  
---|---|---  
LDAP Server URL |  ldap://174.19.33.17:389/ |  ${ldap.server.url}  
LDAP Secure Server URL (SSL) |  ldaps://my-company-ldap.cloudhub.io:1010/ |  ${ldap.server.url}  
LDAP Server User DN |  cn=Manager,dc=my-company,dc=com |  ${ldap.user.dn}  
LDAP User Password |  somePassword |  ${ldap.password}  
LDAP Search Base |  ou=people,dc=my-company,dc=com |  ${ldap.search.base}  
LDAP Search Filter |  ${ldap.search.filter}  
The search filter string in the example is specific to OpenLDAP applications.
## How This Policy Works
The Basic Authentication - LDAP policy intercepts the request to the protected resource and looks for the `Authorization` HTTP header.
The policy then extracts the username and password encoded in Base64 and then requests the configured LDAP instance to determine if the user credentials are correct in the provided LDAP context.
You can configure the Basic Authentication: LDAP policy to credentials using the following methods:
  * Search for the valid username and password pair in the level specified.
  * Search for the valid username and password pair in the level specified, including lower levels. This search option is comprehensive, however, can result in slow performance.


### Search Scope
Your search scope options differ depending on your policy version. The search scope options are one level for LDAP 1.0.0 and two levels (subtree) for LDAP 1.1.0.
You can choose between `one level` and `subtree` search scopes by using the `LDAP Search in subtree` option.
The `LDAP search base` is the starting point for the search in the directory.
### One-Level Search Scope
With this option, the filter affects only the objects immediately subordinate to the `LDAP search base`, and not the `LDAP search base` itself.
In the following example, the first level has four entries: two users and two groups. These are the only entries that are a part of any search:
If you set the search filter to `(uid={0})`, only `Jane` and `Paul` are found. The group entries are not considered.
#### Subtree Search Scope
With this option, the Basic Authentication - LDAP policy examines the subtree below the `LDAP search base` and also includes the `LDAP search base` level. Notice that performance is affected by this behavior.
In the previous example, the analyzed area covers the entire organization. The group and user entries are considered at any level of the organization:
## Creating Requests for APIs with Basic Authentication Policies Applied
After applying the Basic Authentication - LDAP policy to the API, a request to that API must contain the following header:
```
Authorization: Basic <username:password>
```

The `username:password` value must be a Base64-encoded string. For example on a Mac OS X or Linux system, the username and password requirement is implemented as:
`echo -n '<Client Id>:<Client Secret>' | base64`
Mule runtime engine (Mule) separates the credentials of the header and sends the request to the LDAP server with the search filter.
From the `username` and search filter, LDAP finds the registered user and then verifies credentials. The valid result is returned to Mule:
The following diagram illustrates an invalid request:
The Basic Authentication: LDAP policy throws an HTTP 401 status code to indicate that the authorization header is malformed, not provided, or invalid.