---
schema_version: "1"
id: 1f036314d90cb4601c7c482a0436d96d82370f13efffa5a0650d4941a65575ec
title: "Basic Authentication: LDAP Policy"
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/1.9/policies-included-basic-auth-ldap.md
canonical_url: https://docs.mulesoft.com/gateway/1.9/policies-included-basic-auth-ldap
source_site: docs.mulesoft.com
content_type: documentation
content_hash: f2ecbf37d97b94c6dafa7969706bedde907464155e25f69cf38dde0c99e6e7e2
description: MuleSoft Documentation Site
release: "1.9"
latest: false
---
---
product: Omni Gateway
version: 1.9
keywords: basic authentication, ldap, api gateway, flex gateway, gateway, policy
---

# Basic Authentication: LDAP Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Basic Authentication: LDAP</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Allows access based on the basic authorization mechanism, with user-password defined on LDAP</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Flex Gateway version available</strong></p></td><td><p>v1.1.0</p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>401 - Unauthorized or invalid client application credentials</p></td></tr></tbody></table>

## 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](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol).

## 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

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>ldapServerURL</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>ldap://127.0.0.1:389</code></p></div></div></td><td><div><div><p>Address and port of the location to the LDAP server</p></div></div></td></tr><tr><td><div><div><p><code>ldapServerUserDn</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The name of the user or user group with access to traverse and list users of LDAP</p></div></div></td></tr><tr><td><div><div><p><code>ldapServerUserPassword</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The password for the user or usergroup</p></div></div></td></tr><tr><td><div><div><p><code>ldapSearchBase</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The place where the LDAP search begins</p></div></div></td></tr><tr><td><div><div><p><code>ldapSearchFilter</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div></div></td><td><div><div><p>The criteria for the filter for the Active Directory or the OpenLDAP model</p></div></div></td></tr><tr><td><div><div><p><code>ldapSearchInSubtree</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>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</p></div></div></td></tr></tbody></table>

#### 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:

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>LDAP Server URL</p></div></div></td><td><div><div><p>The URL of your LDAP OR LDAPS server, including the port number.</p></div></div></td></tr><tr><td><div><div><p>LDAP User DN</p></div></div></td><td><div><div><p>The name of the user or user group with access to traverse and list users of LDAP.</p></div></div></td></tr><tr><td><div><div><p>LDAP User Password</p></div></div></td><td><div><div><p>The password for the user or user group. The password must be a secure value that, once specified, is not visible or retrievable.</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Base</p></div></div></td><td><div><div><p>The starting point for the search in the directory tree.</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Filter</p></div></div></td><td><div><div><p>The criteria for the filter for the Active Directory or the OpenLDAP model, as shown in the examples.</p></div></div></td></tr></tbody></table>

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

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Field</th><th>Example Literal String Value</th><th>Example Secure Property Placeholder</th></tr></thead><tbody><tr><td><div><div><p>LDAP Server URL</p></div></div></td><td><div><div><p>ldap://174.19.33.17:389/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Secure Server URL (SSL)</p></div></div></td><td><div><div><p>ldaps://my-company-ldap.cloudhub.io:1010/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Server User DN</p></div></div></td><td><div><div><p>CN=Administrator,CN=Users,DC=my-company,DC=com</p></div></div></td><td><div><div><p>${ldap.user.dn}</p></div></div></td></tr><tr><td><div><div><p>LDAP User Password</p></div></div></td><td><div><div><p>somePassword</p></div></div></td><td><div><div><p>${ldap.password}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Base</p></div></div></td><td><div><div><p>CN=Users,DC=my-company,DC=com</p></div></div></td><td><div><div><p>${ldap.search.base}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Filter</p></div></div></td><td><div><div><p>(sAMAccountName={0})</p></div></div></td><td><div><div><p>${ldap.search.filter}</p></div></div></td></tr></tbody></table>

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:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Field</th><th>Example Literal String Value</th><th>Example Secure Property Placeholder</th></tr></thead><tbody><tr><td><div><div><p>LDAP Server URL</p></div></div></td><td><div><div><p>ldap://174.19.33.17:389/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Secure Server URL (SSL)</p></div></div></td><td><div><div><p>ldaps://my-company-ldap.cloudhub.io:1010/</p></div></div></td><td><div><div><p>${ldap.server.url}</p></div></div></td></tr><tr><td><div><div><p>LDAP Server User DN</p></div></div></td><td><div><div><p>cn=Manager,dc=my-company,dc=com</p></div></div></td><td><div><div><p>${ldap.user.dn}</p></div></div></td></tr><tr><td><div><div><p>LDAP User Password</p></div></div></td><td><div><div><p>somePassword</p></div></div></td><td><div><div><p>${ldap.password}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Base</p></div></div></td><td><div><div><p>ou=people,dc=my-company,dc=com</p></div></div></td><td><div><div><p>${ldap.search.base}</p></div></div></td></tr><tr><td><div><div><p>LDAP Search Filter</p></div></div></td><td><div><div><p>(uid={0})</p></div></div></td><td><div><div><p>${ldap.search.filter}</p></div></div></td></tr></tbody></table>

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:

![Diagram of a hierarchical organizational structure](/mulesoft/current/en-us/gateway/1.9/_images/search-scope.png)

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:

![A flowchart that shows an example organizational structure](/mulesoft/current/en-us/gateway/1.9/_images/search-scope2.png)

## 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:

![Here’s a sequence diagram that illustrates the message flow for client authentication through an LDAP Server](/mulesoft/current/en-us/gateway/1.9/_images/ldap-verification.png)

The following diagram illustrates an invalid request:

![A sequence diagram that illustrates the message flow for authorization](/mulesoft/current/en-us/gateway/1.9/_images/ldap-verification-invalid.png)

The Basic Authentication: LDAP policy throws an HTTP 401 status code to indicate that the
authorization header is malformed, not provided, or invalid.