---
schema_version: "1"
id: 06eee78a4e8c7c49fc8907525a3f80c684f6f843d2ac2dd1ddc2a59082dcea0a
title: "Basic Authentication: LDAP Policy"
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/mule-gateway/policies-included-basic-auth-ldap.md
canonical_url: https://docs.mulesoft.com/mule-gateway/policies-included-basic-auth-ldap
source_site: docs.mulesoft.com
content_type: documentation
content_hash: aa2098edb8d13cfbd9a3a3be97032dde129ad23ad208a643e692153fada8a776
description: MuleSoft Documentation Site
latest: true
---
---
product: Mule Gateway
keywords: basic authentication, ldap, api gateway, mule 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 Mule version available</strong></p></td><td><p>v4.0.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. This policy is available in Omni 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](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol).

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

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

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

![A hierarchical chart displays organizational structure and user IDs](/mulesoft/current/en-us/mule-gateway/_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 hierarchical chart displays a company’s organizational structure](/mulesoft/current/en-us/mule-gateway/_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`

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:

![A sequence diagram that illustrates the message flow for client authentication through an LDAP Server](/mulesoft/current/en-us/mule-gateway/_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/mule-gateway/_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.