If you store user information within LDAP directories in your network infrastructure, you can configure the email gateway to query your LDAP server for the following purposes:

• Acceptance Queries. You can use your existing LDAP infrastructure to define how the recipient email address of incoming messages (on a public listener) should be handled. For more information, see Using Acceptance Queries For Recipient Validation.
• Routing (Aliasing). You can configure the email gateway to route messages to the appropriate address and/or mail host based upon the information available in LDAP directories on your network. For more information, see Using Routing Queries to Send Mail to Multiple Target Addresses.
• Certificate Authentication. You can create a query that checks the validity of a client certificate in order to authenticate an SMTP session between the user’s mail client and the email gateway. For more information, see Checking the Validity of a Client Certificate.
• Masquerading. You can masquerade Envelope Senders (for outgoing mail) and message headers (for incoming mail, such as To:, Reply To:, From: or CC:). For more information about masquerading, see Using Masquerading Queries to Rewrite the Envelope Sender.
• Group Queries. You can configure the email gateway to perform actions on messages based on the groups in the LDAP directory. You do this by associating a group query with a message filter. You can perform any message action available for message filters on messages that match the defined LDAP group. For more information, see Using Group LDAP Queries to Determine if a Recipient is a Group Member.
• Domain-based Queries. You can create domain-based queries to allow the email gateway to perform different queries for different domains on a single listener. When the email gateway runs the domain-based queries, it determines the query to use based on the domain, and it queries the LDAP server associated with that domain.
• Chain Queries. You can create a chain query to enable the email gateway to perform a series of queries in sequence. When you configure a chain query, the email gateway runs each query in sequence until the LDAP appliance returns a positive result. For chained routing queries, the email gateway re-runs the same configured chain query in sequence for each rewritten email address.
• Directory Harvest Prevention. You can configure the email gateway to combat directory harvest attacks using your LDAP directories. You can configure directory harvest prevention during the SMTP conversation or within the work queue. If the recipient is not found in the LDAP directory, you can configure the system to perform a delayed bounce or drop the message entirely. Consequently, spammers are not able to differentiate between valid and invalid email addresses. See Using LDAP For Directory Harvest Attack Prevention.
• SMTP Authentication. AsyncOS provides support for SMTP authentication. SMTP Auth is a mechanism for authenticating clients connected to an SMTP server. You can use this functionality to enable users at your organization to send mail using your mail servers even if they are connecting remotely (e.g. from home or while traveling). For more information, see Configuring AsyncOS for SMTP Authentication.
• External Authentication. You can configure your email gateway to use your LDAP directory to authenticate users logging in to the email gateway. For more information, see Configuring External LDAP Authentication for Users.
• Spam Quarantine End-User Authentication. You can configure your email gateway to validate users when they log in to the end-user quarantine. For more information, see Authenticating End-Users of the Spam Quarantine.
• Spam Quarantine Alias Consolidation. If you use email notifications for spam, this query consolidates the end-user aliases so that end-users do not receive quarantine notices for each aliased email address. For more information, see Spam Quarantine Alias Consolidation Queries.

When you work with LDAP directories, the email gateway can be used in conjunction with an LDAP directory server to accept recipients, route messages, and/or masquerade headers. LDAP group queries can also be used in conjunction with message filters to create rules for handling messages as they are received by the email gateway.

The following figure demonstrates how the email gateway works with LDAP:

1. The sending MTA sends a message to the public listener “A” via SMTP.
2. The email gateway queries the LDAP server defined via the System Administration > LDAP page (or by the global ldapconfig command).
3. Data is received from the LDAP directory, and, depending on the queries defined on the System Administration > LDAP page (or in the ldapconfig command) that are used by the listener:
   • the message is routed to the new recipient address, or dropped or bounced
   • the message is routed to the appropriate mailhost for the new recipient
   • From:, To:, and CC: message headers are re-written based upon the query
   • further actions as defined by rcpt-to-group or mail-from-group message filter rules (used in conjunction with configured group queries).

Note	You can configure your email gateway to connect to multiple LDAP servers. When you do this, you can configure the LDAP profile settings for load-balancing or failover. For more information about working with multiple LDAP servers, see Configuring AsyncOS To Work With Multiple LDAP Servers.

Use the Test Server(s) button on the Add/Edit LDAP Server Profile page (or the test subcommand of the ldapconfig command in the CLI) to test the connection to the LDAP server. AsyncOS displays a message stating whether the connection to the server port succeeded or failed. If you configured multiple LDAP servers, AsyncOS tests each server and displays individual results.

To allow the email gateway to run LDAP queries when you receive or send messages, you must enable the LDAP query on the appropriate listener.

AsyncOS includes a configuration option to provide support for Microsoft Exchange 5.5. If you use a later version of Microsoft Exchange, you do not need to enable this option. When configuring an LDAP server, you can elect to enable Microsoft Exchange 5.5 support by answering “y” when prompted in the ldapconfig -> edit -> server -> compatibility subcommand (this is only available via the CLI):

mail3.example.com> ldapconfig

Current LDAP server configurations:

1. PublicLDAP: (ldapexample.com:389)


Choose the operation you want to perform:

- NEW - Create a new server configuration.

- EDIT - Modify a server configuration.

- DELETE - Remove a server configuration.


[]> edit

Enter the name or number of the server configuration you wish to edit.

[]> 1

Name: PublicLDAP

Hostname: ldapexample.com Port 389

Authentication Type: anonymous

Base: dc=ldapexample,dc=com

Choose the operation you want to perform:

- SERVER - Change the server for the query.

- LDAPACCEPT - Configure whether a recipient address should be accepted or
bounced/dropped.

- LDAPROUTING - Configure message routing.

- MASQUERADE - Configure domain masquerading.

- LDAPGROUP - Configure whether a sender or recipient is in a specified group.

- SMTPAUTH - Configure SMTP authentication.

[]> server

Name: PublicLDAP

Hostname: ldapexample.com Port 389

Authentication Type: anonymous

Base: dc=ldapexample,dc=com


Microsoft Exchange 5.5 Compatibility Mode: Disabled

Choose the operation you want to perform:

- NAME - Change the name of this configuration.

- HOSTNAME - Change the hostname used for this query.

- PORT - Configure the port.

- AUTHTYPE - Choose the authentication type.

- BASE - Configure the query base.

- COMPATIBILITY - Set LDAP protocol compatibility options.

[]> compatibility
Would you like to enable Microsoft Exchange 5.5 LDAP compatibility mode? (This is not
recommended for versions of Microsoft Exchange later than 5.5, or other LDAP servers.)


[N]> y

Do you want to configure advanced LDAP compatibility settings? (Typically not required)

[N]>

Name: PublicLDAP

Hostname: ldapexample.com Port 389

Authentication Type: anonymous

Base: dc=ldapexample,dc=com

Microsoft Exchange 5.5 Compatibility Mode: Enabled (attribute "objectClass")

Choose the operation you want to perform:

- NAME - Change the name of this configuration.

- HOSTNAME - Change the hostname used for this query.

- PORT - Configure the port.

- AUTHTYPE - Choose the authentication type.

- BASE - Configure the query base.

- COMPATIBILITY - Set LDAP protocol compatibility options.

[]>

• Acceptance queries. For more information, see Using Acceptance Queries For Recipient Validation.
• Routing queries. For more information, see Using Routing Queries to Send Mail to Multiple Target Addresses.
• Certificate Authentication queries. For more information, see Checking the Validity of a Client Certificate.
• Masquerading queries. For more information, see Using Masquerading Queries to Rewrite the Envelope Sender.
• Group queries. For more information, see Using Group LDAP Queries to Determine if a Recipient is a Group Member.
• Domain-based queries. For more information, see Using Domain-based Queries to Route to a Particular Domain.
• Chain queries. For more information, see Using Chain Queries to Perform a Series of LDAP Queries.

You can also configure queries for the following purposes:

• Directory harvest prevention. For more information, see Understanding LDAP Queries.
• SMTP authentication. For more information, see Configuring AsyncOS for SMTP Authentication.
• External authentication. For more information, Configuring External LDAP Authentication for Users.
• Spam quarantine end-user authentication query. For more information, see Authenticating End-Users of the Spam Quarantine.
• Spam quarantine alias consolidation query. For more information, see Spam Quarantine Alias Consolidation Queries.

The search queries you specify are available to all listeners you configure on the system.

The root level of the directory is called the base. The name of the base is the DN (distinguishing name). The base DN format for Active Directory (and the standard as per RFC 2247) has the DNS domain translated into domain components (dc=). For example, example.com's base DN would be: dc=example, dc=com. Note that each portion of the DNS name is represented in order. This may or may not reflect the LDAP settings for your configuration.

If your directory contains multiple domains you may find it inconvenient to enter a single BASE for your queries. In this case, when configuring the LDAP server settings, set the base to NONE. This will, however, make your searches inefficient.

Spaces are allowed in LDAP paths, and they do not need to be quoted. The CN and DC syntax is not case-sensitive.

Cn=First Last,oU=user,dc=domain,DC=COM

The variable names you enter for queries are case-sensitive and must match your LDAP implementation in order to work correctly. For example, entering mailLocalAddress at a prompt performs a different query than entering maillocaladdress.

You can use instruct AsyncOS to use SSL when communicating with the LDAP server. If you configure your LDAP server profile to use SSL:

• AsyncOS will use the LDAPS certificate configured via certconfig in the CLI (see Creating a Self-Signed Certificate).

  You may have to configure your LDAP server to support using the LDAPS certificate.

• If an LDAPS certificate has not been configured, AsyncOS will use the demo certificate.

There is no recursion limit for LDAP routing queries; the routing is completely data driven. However, AsyncOS does check for circular reference data to prevent the routing from looping infinitely.

You may need to configure your LDAP directory server to allow for anonymous queries. (That is, clients can bind to the server anonymously and perform queries.) For specific instructions on configuring Active Directory to allow anonymous queries, see the “Microsoft Knowledge Base Article - 320528” at the following URL:

http://support.microsoft.com/default.aspx?scid=kb%3Ben-us%3B320528
 

Alternately, you can configure one “user” dedicated solely for the purposes of authenticating and performing queries instead of opening up your LDAP directory server for anonymous queries from any client.

A summary of the steps is included here, specifically:

• How to set up Microsoft Exchange 2000 server to allow “anonymous” authentication.
• How to set up Microsoft Exchange 2000 server to allow “anonymous bind.”
• How to set up AsyncOS to retrieve LDAP data from a Microsoft Exchange 2000 server using both “anonymous bind” and “anonymous” authentication.

Specific permissions must be made to a Microsoft Exchange 2000 server in order to allow “anonymous” or “anonymous bind” authentication for the purpose of querying user email addresses. This can be very useful when an LDAP query is used to determine the validity of an income email message to the SMTP gateway.

Use the Test Query button on the Add/Edit LDAP Server Profile page (or the test sub command in the CLI) of each query type to test the query to the LDAP server you configured. In addition to displaying the result, AsyncOS also displays the details on each stage of the query connection test. You can test each of the query types.

The ldaptest command is available as a batch command, for example:

ldaptest LDAP.ldapaccept foo@ironport.com

If you entered multiple hosts in the Host Name field of the LDAP server attributes, the email gateway tests the query on each LDAP server.

Note

The variable names you enter for queries are case-sensitive and must match your LDAP implementation in order to work correctly. For example, entering mailLocalAddress at a prompt performs a different query than entering maillocaladdress. Cisco Systems strongly recommends using the test subcommand of the ldapconfig command to test all queries you construct and ensure the proper results are returned.

If the LDAP server is unreachable by the email gateway, one of the following errors will be shown:

• Error: LDAP authentication failed: <LDAP Error "invalidCredentials" [0x31]>
• Error: Server unreachable: unable to connect
• Error: Server unreachable: DNS lookup failure

Note that a server may be unreachable because the wrong port was entered in the server configuration, or the port is not opened in the firewall. LDAP servers typically communicate over port 3268 or 389. Active Directory uses port 3268 to access the global catalog used in multi-server environments (See the “Firewall Information” appendix for more information.) In AsyncOS 4.0, the ability to communicate to the LDAP server via SSL (usually over port 636) was added. For more information, see Secure LDAP (SSL).

A server may also be unreachable because the hostname you entered cannot be resolved.

You can use the Test Server(s) on the Add/Edit LDAP Server Profile page (or the test subcommand of the ldapconfig command in the CLI) to test the connection to the LDAP server. For more information, see Testing LDAP Servers.

If the LDAP server is unreachable:

• If LDAP Accept or Masquerading or Routing is enabled on the work queue, mail will remain within the work queue.
• If LDAP Accept is not enabled but other queries (group policy checks, etc.) are used in filters, the filters evaluate to false.

The following table shows sample acceptance queries.

You can also validate on the username (Left Hand Side). This is useful if your directory does not contain all the domains you accept mail for. Set the Accept query to (uid={u}).

Note that there is a potential complication with LDAPACCEPT and Lotus Notes. If Notes LDAP contains a person with attributes like these:

mail=juser@example.com


cn=Joe User


uid=juser


cn=123456


location=New Jersey

Lotus accepts email for this person for various different forms of email addresses, other than what is specified, such as “Joe_User@example.com” — which do not exist in the LDAP directory. So AsyncOS may not be able to find all of the valid user email addresses for that user.

One possible solution is to try to publish the other forms of addresses. Please contact your Lotus Notes administrator for more details.

(mailLocalAddress={a})

(mail={a})
(mailForwardingAddress={a})
(mailEquivalentAddress={a})
(mailRoutingAddress={a})
(otherMailbox={a})
(rfc822Mailbox={a})

a. Active Directory implementations can have multiple entries for the proxyAddresses attribute, but because AD formats this attribute value as smtp:user@domain.com, that data cannot be used for LDAP routing/alias expansion. Each target address must be in a separate attribute:value pair. Microsoft Exchange environments that are aware of each other within the infrastructure can usually route mail between each other without involving a route back to the originating MTA.

Related Topics

• Routing: MAILHOST and MAILROUTINGADDRESS

In some user environments, an LDAP directory server schema may store a “friendly name” in addition to a mail routing address or a local mail address. AsyncOS allows you to masquerade Envelope Senders (for outgoing mail) and message headers (for incoming mail, such as To:, Reply To:, From: or CC:) with this “friendly address” — even if the friendly address contains special characters that are not normally permitted in a valid email address (for example, quotation marks, spaces, and commas).

When using masquerading of headers via an LDAP query, you now have the option to configure whether to replace the entire friendly email string with the results from the LDAP server. Note that even with this behavior enabled, only the user@domain portion will be used for the Envelope Sender (the friendly name is illegal).

As with the normal LDAP masquerading, if empty results (zero length or entire white space) are returned from the LDAP query, no masquerading occurs.

To enable this feature, answer “y” to the following question when configuring an LDAP-based masquerading query for a listener (LDAP page or ldapconfig command):

Do you want the results of the returned attribute to replace the entire
friendly portion of the original recipient? [N]

For example, consider the following example LDAP entry:

If this feature is enabled, an LDAP query of (mailRoutingAddress={a}) and a masquerading attribute of (mailLocalAddress) would result in the following substitutions:

You can prevent DHAs by entering only domains in the Recipient Access Table (RAT), and performing the LDAP acceptance validation in the SMTP conversation.

To drop messages during the SMTP conversation, configure an LDAP server profile for LDAP acceptance. Then, configure the listener to perform an LDAP accept query during the SMTP conversation.

Once you configure LDAP acceptance queries for the listener, you must configure DHAP settings in the mail flow policy associated with the listener.

In the mail flow policy associated with the listener, configure the following Directory Harvest Attack Prevention settings:

• Max. Invalid Recipients Per hour. The maximum number of invalid recipients per hour this listener will receive from a remote host. This threshold represents the total number of RAT rejections combined with the total number of messages to invalid LDAP recipients dropped in the SMTP conversation or bounced in the work queue. For example, you configure the threshold as five, and the counter detects two RAT rejections and three dropped messages to invalid LDAP recipients. At this point, the email gateway determines that the threshold is reached, and the connection is dropped. By default, the maximum number of recipients per hour for a public listener is 25. For a private listener, the maximum number of recipients per hour is unlimited by default. Setting it to “Unlimited” means that DHAP is not enabled for that mail flow policy.
• Drop Connection if DHAP Threshold is reached within an SMTP conversation. Configure the email gateway to drop the connection if the Directory Harvest Attack Prevention threshold is reached.
• Max. Recipients Per Hour Code. Specify the code to use when dropping connections. The default code is 550.
• Max. Recipients Per Hour Text. Specify the text to use for dropped connections. The default text is “Too many invalid recipients.”

If the threshold is reached, the Envelope Sender of the message does not receive a bounce message when a recipient is invalid.

You can prevent most DHAs by entering only domains in the Recipient Access Table (RAT), and performing the LDAP acceptance validation within the work queue. This technique prevents the malicious senders from knowing if the recipient is valid during the SMTP conversation. (When acceptance queries are configured, the system accepts the message and performs the LDAP acceptance validation within the work queue.) However, the Envelope Sender of the message will still receive a bounce message if a recipient is not valid.

If you are going to authenticate with an LDAP server, select the SMTPAUTH query type on the Add or Edit LDAP Server Profile pages (or in the ldapconfig command) to create an SMTP Authentication query. For each LDAP server you configure, you can configure a SMTPAUTH query to be used as an SMTP Authentication profile.

There are two kinds of SMTP authentication queries: LDAP bind and passphrase as attribute. When you use passphrase as attribute, the email gateway will fetch the passphrase field in the LDAP directory. The passphrase may be stored in plain text, encrypted, or hashed. When you use LDAP bind, the email gateway attempts to log into the LDAP server using the credentials supplied by the client.

In the following example, the System Administration > LDAP page is used to edit the LDAP configuration named “PublicLDAP” to include an SMTPAUTH query. The query string ( uid={u} ) is constructed to match against userPassword attribute.

When an SMTPAUTH profile has been configured, you can specify that the listener uses that query for SMTP authentication.

The email gatewaysupports the use of client certificates to authenticate SMTP sessions between the email gateway and users’ mail clients.

When creating an SMTP authentication profile, you select the Certificate Authentication LDAP query to use for verifying the certificate. You can also specify whether the email gateway falls back to the SMTP AUTH command to authenticate the user if a client certificate isn’t available.

If your organization uses client certificates to authenticate users, you have the option of using the SMTP Authentication query to check whether a user who doesn’t have a client certificate can send mail as long as their record specifies that it’s allowed.

The following events will be logged in the mail logs when the SMTP Authentication mechanism (either LDAP-based, SMTP forwarding server based, or SMTP outgoing) is configured on the email gateway:

• [Informational] Successful SMTP Authentication attempts — including the user authenticated and the mechanism used. (No plaintext passphrases will be logged.)
• [Informational] Unsuccessful SMTP Authentication attempts — including the user authenticated and the mechanism used.
• [Warning] Inability to connect to the authentication server — including the server name and the mechanism.
• [Warning] A time-out event when the forwarding server (talking to an upstream, injecting email gateway) times out while waiting for an authentication request.

This section shows sample settings for an Active Directory server and the end-user authentication query. This example uses passphrase authentication for the Active Directory server, the mail and proxyAddresses email attributes, and the default query string for end-user authentication for Active Directory servers.

This section shows sample settings for an OpenLDAP server and the end-user authentication query. This example uses anonymous authentication for the OpenLDAP server, the mail and mailLocalAddress email attributes, and the default query string for end-user authentication for OpenLDAP servers.

This section shows sample settings for an Active Directory server and the alias consolidation query. This example uses anonymous authentication for the Active Directory server, a query string for alias consolidation for Active Directory servers, and the mail email attribute.

(
|(mail={a})(mail=smtp:{a})
)

Note	This example is for representational purposes only. Queries and OU or tree settings may vary depending on the environment and configuration.

This section shows sample settings for an OpenLDAP server and the alias consolidation query. This example uses anonymous authentication for the OpenLDAP server, a query string for alias consolidation for OpenLDAP servers, and the mail email attribute.

Note	This example is for representational purposes only. Queries and OU or tree settings may vary depending on the environment and configuration.

To ensure that LDAP queries are resolved, you can configure your LDAP profile for failover. If the connection to the LDAP server fails, or the query returns certain error codes (for example, Unavailable or Busy), the email gateway attempts to query the next LDAP server specified in the list.

The email gateway attempts to connect to the first server in the list of LDAP servers for a specified period of time. If the email gateway cannot connect to the first LDAP server in the list, or the query returns certain error codes (for example, Unavailable or Busy), the email gateway attempts to connect to the next LDAP server in the list. By default, the email gateway always attempts to connect to the first server in the list, and it attempts to connect to each subsequent server in the order they are listed. To ensure that the email gateway connects to your primary LDAP server by default, ensure that you enter it as the first server in your list of LDAP servers.

If the email gateway connects to a second or subsequent LDAP server, it remains connected to that server until it reaches a timeout period. After it reaches the timeout, it attempts to reconnect to the first server in the list.

Note	Only attempts to query a specified LDAP server fail over. Attempts to query referral or continuation servers associated with the specified LDAP server do not fail over.

To distribute LDAP connections among a group of LDAP servers, you can configure your LDAP profile for load balancing.

When you configure your LDAP profile for load balancing, the email gateway distributes connections among the LDAP servers listed. If a connection fails or times out, the email gateway determines which LDAP servers are available and reconnects to available servers. The email gateway determines the number of simultaneous connections to establish based on the maximum number of connections you configure.

If one of the listed LDAP servers does not respond, the email gateway distributes the connection load among the remaining LDAP servers.