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 Flex Gateway 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.
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
### Flex Gateway Local Mode
In Local Mode, you apply the policy to your API via declarative configuration files. Refer to the following policy definition and table of parameters:
```
- policyRef:
  name: ldap-authentication-flex
 config:
  ldapServerURL: <string> // OPTIONAL, default: "ldap://127.0.0.1:389"
  ldapServerUserDn: <string> // REQUIRED
  ldapServerUserPassword: <string> // REQUIRED
  ldapSearchBase: <string> // REQUIRED
  ldapSearchFilter: <string> // OPTIONAL, default: "(uid={0})"
  ldapSearchInSubtree: <bool> // OPTIONAL, default: false
```

Parameter | Required or Optional | Default Value | Description  
---|---|---|---  
`ldapServerURL` |  `ldap://127.0.0.1:389` |  Address and port of the location to the LDAP server  
`ldapServerUserDn` |  The name of the user or user group with access to traverse and list users of LDAP  
`ldapServerUserPassword` |  The password for the user or usergroup  
`ldapSearchBase` |  The place where the LDAP search begins  
`ldapSearchFilter` |  The criteria for the filter for the Active Directory or the OpenLDAP model  
`ldapSearchInSubtree` |  Whether to examine the subtree below the base DN and include the base DN level. Performance will be affected by this. Otherwise, the one-level scope will be used, examining only the level immediately below the base DN  
#### Resource Configuration Example
```
- policyRef:
  name: ldap-authentication-flex
 config:
  dapServerURL: "ldap://localhost:369"
  ldapServerUserDn: "cn=admin,dc=example,dc=org"
  ldapServerUserPassword: "admin"
  ldapSearchBase: "dc=example,dc=org"
  ldapSearchFilter: "(uid={0})"
  ldapSearchInSubtree: true
```

### Managed Flex Gateway and Flex Gateway Connected Mode
When you apply the policy to your API instance from the UI, the following parameters are displayed:
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.  
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`
From the `username` and search filter, LDAP finds the registered user and then verifies credentials. The valid result is returned:
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.