LDAP policy

What

Use the LDAP Policy when access to protected resources should be limited to users in your LDAP provider—such as your admin users, organization users, and developers—especially when OAuth token access is either unnecessary or too heavyweight. The policy is also designed for retrieving DN metadata for use in API proxy flows.

For example you can have an API call execute only when a user is successfully authenticated against LDAP; and then optionally retrieve DN attributes for the user after authentication succeeds.

This policy is available only in Apigee Edge on-premises.

Where

This policy can be attached in the following locations, but see the notes following the table for specific guidance.

This policy references a custom LDAP provider. It uses the email address in the request header to identify the user, then retrieves the user’s address, phone, and title from LDAP. The retrieved DN attributes are stored in a variable. See "Policy-specific variables".

To search LDAP and retrieve DN attributes, the request must include administrator credentials.

Element reference

Following are descriptions of the LDAP Policy elements and attributes.

The name attribute for this policy is restricted to these characters: A-Z0-9._\-$ %. However, the Management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Element

Description

Ldap

Parent element with a name attribute for you to enter the policy name.

LdapConnectorClass

When using the LDAP Policy with a custom LDAP provider (not provided by Apigee), specify the fully qualified LDAP connector class. That’s the class in which you implemented Apigee’s ExternalLdapConProvider interface.

ref: A reference to the username in the request, such as request.header.username

value: The username itself

If you aren't authenticating with username, or if username isn't included in the request, you don't need to include this element.

If username is in the request, but you want to authenticate a user with a DN attribute other than username, such as email, include a SearchQuery to get the user email associated with the password. The LDAP policy uses username to query the LDAP provider for the corresponding email address, which is then used for authentication.

Password

Empty element that takes one of the following attributes:

ref: A reference to the password in the request, such as request.header.password

value: The encrypted password itself

SearchQuery

If you want to authenticate using a DN attribute other than username, such as email, configure the LDAP policy to get a DN attribute from the request (such as username), which is used to identify the user in LDAP, retrieve the email, and authenticate the user.

By identifying the user with metadata in the request or response, you can use this element to retrieve additional DN attributes for the user from LDAP. For example, if the request contains the user email, and your LDAP defines a “mail” attribute for storing user email addresses, you’d use the following setting:

<SearchQuery>mail={request.header.mail}</SearchQuery>

This query searches LDAP for an email matching the email in the request, and the policy can now retrieve additional DN attributes for that user with the Attributes element.

Attributes

Use one or more <Attribute> elements to identify the DN metadata you want to retrieve for the user. At least one attribute is required.

For example, after the SearchQuery identifies the user, the policy can now retrieve DN attributes for the user such as address, phone number, and the user’s title, as shown in the following example.

Usage notes

Apigee Edge on-premises lets you leverage an LDAP provider in API calls. With the LDAP Policy, applications can authenticate credentials against users stored in LDAP, and you can retrieve distinguished names (DNs) from LDAP—the metadata, or attributes, associated with each user, such as email, address, and phone number. The returned DN is stored in a variable for further use by the API proxy.

The LDAP Policy provides:

Authentication: User credentials supplied in the request are validated against credentials in the LDAP provider. The LDAP policy gives you a lot of flexibility with authentication, letting you use any DN value along with the password, even if that DN value you want isn't in the request. For example, say you need to use email / password for authentication. The following options are possible:

If the email is in the request, you can simply use that with the password for LDAP authentication.

If the email isn't in the request, but another DN attribute is (such as phone number), you can use the phone number to get the corresponding email from LDAP, then use email / password to authenticate.

Distinguished name (DN) search: In addition to authentication, you can also use the LDAP Policy to identify a user attribute in the request, such as email, and perform a query that retrieves other DN attributes from LDAP for that user. The retrieved DN is stored in a variable.

Create an LDAP resource

The LDAP policy leverages an LDAP resource that you create in Apigee Edge. An LDAP resource provides the connection information to your LDAP repository.

To create and manage LDAP resources, use the following API and payload:

API

Create (POST) an LDAP resource or list (GET) all LDAP resources:

/v1/organizations/{org_name}/environments/{environment}/ldapresources

Get details for (GET), Update (POST), and Delete (DELETE) an LDAP resource:

If you use a custom LDAP provider

Apigee Edge on-premises provides an LDAP provider that is already configured to interact with the LDAP Policy. However, if you are using a custom LDAP provider, you must enable the provider to support the LDAP Policy. To do this:

The flexible format of this variable—the “index” in particular—accounts for multiple attributes, as well as attributes with multiple values. Index is a number that starts at 1. If no index number is provided, the default index number is 1.

If the policy returns address, phone, and email, you can retrieve the first attribute and value using these variables:

ldap.<policyName>.search.result.attribute.address

ldap.<policyName>.search.result.attribute.phone

ldap.<policyName>.search.result.attribute.email

If you wanted to retrieve the third address attribute in the search results, you’d use this:

ldap.<policyName>.search.result[3].attribute.
address

If an attribute had multiple values (for example, if a user has multiple email addresses), you’d retrieve the second email address from the results like this: