Gfi Max Mp Ldap Guide

LDAP Integration – Active Directory


2 | www.gfi.com/maxmp

Overview Organizations can provide GFI MAX MailProtection™/MailEdge™ with a list of valid email addresses/users via several different methods. One approach that automates this process is via an LDAP query from GFI MAX Mail to an organization’s Active Directory server.

When this is configured for a given domain or organization, GFI MAX Mail automatically connects to the organization’s Active Directory server at periodic intervals, and requests a list of the email addresses for that company’s domain(s). This ensures that GFI MAX Mail is automatically kept in sync with any changes to the email addresses in use at the organization.

The setup of the LDAP synchronization is a one-time process with a few steps, which are detailed below:

1. Setup of a user for GFI MAX Mail within the organization’s Active Directory

2. Reconfiguration of the organization’s firewall to allow an inbound LDAP request from GFI MAX Mail

3. (Optional) Installation of a secure certificate on the organization’s Active Directory server

4. Configuration of LDAP information at the GFI MAX Mail LDAP synchronization setup page

User Setup A new user should be set up for GFI MAX Mail in the organization’s Active Directory. This user can and should have minimal rights (i.e. it does not need any access to files, printers, etc.) – it simply needs to be able to login, and should have an email address, e.g., [email protected] or [email protected].

Firewall Configuration A port on the organization’s firewall should be opened to allow inbound LDAP traffic from GFI MAX Mail’s networks to the organization’s Active Directory server. For standard LDAP, the port is 389. If you are using LDAPS (Secure LDAP; see below), it is port 636. The GFI MAX Mail networks that must be allowed are:

174.36.154.0 / 255.255.255.0 207.154.50.0 / 255.255.255.0 208.43.37.0 / 255.255.255.0 208.70.88.0 / 255.255.255.0 208.70.89.0 / 255.255.255.0 208.70.90.0 / 255.255.255.0 208.70.91.0 / 255.255.255.0

http://www.gfi.com/maxmp�



Optional – Configuration of Secure LDAP (LDAPS) Organizations can optionally use an encrypted version of LDAP, LDAPS, by installing a certificate and configuring their Active Directory server to use that certificate. The process is similar to that of installing an SSL certificate for a web site.

To enable LDAPS, a certificate needs to be installed on the Active Directory server. The certificate can be issued by a Certificate Authority such as Verisign, or it can be a self-signed certificate generated by the organization. It is important to note that the server common name in the certificate must *exactly* match the fully qualified name of the server where it will be installed – e.g., alfred.example.com.

Since there are numerous ways to generate a certificate – including either the use of internal software or the use of a third-party Certificate Authority) – that process is not detailed here. (GFI will allow a self signed certificate.) Please contact the GFI support team if you are unsure how to request / procure a certificate.

To install the certificate on the Active Directory server:

1. From the “Start” button, select “Run” and type “mmc” and hit Enter. An applet will appear.

2. In the applet, select “File” “Add/Remove Snap-in“ “Add (Standalone Tab) “ “Certificates“ “Add“. When prompted for “The snap-in will always manage certificates for“, select “Computer Account“ and hit “Next“.

3. Select “Local Computer“ if this is the computer that will be receiving the LDAP requests (i.e. is the Active Directory server); otherwise, select the appropriate computer.

4. Click “Close”, and “Ok”

5. Expand the tree under “Certificates” and select “Personal”

6. Right click on the “Personal” folder and select “All tasks” “Import”

7. Follow the wizard, accepting the defaults.

Once the certificate has been successfully imported, LDAPS will be enabled.

Provisioning of GFI MAX Mail Finally, the following information should be entered into the GFI MAX Mail LDAP tool, which can be found while logged in to our interface with an administrative username by navigating to Management > Users/User Management > Synchronization (LDAP, etc). Use the selector tool to target the specific domain or organization for which you are setting up the synchronization, and select “LDAP Synchronization” from the drop-down menu.




LDAP CONNECTION SETTINGS

Host (IP Address or Name) – In this field, you will enter the external hostname or external IP address of the LDAP server. This will often be the same hostname or IP address as the mail server itself; however, in the case of an organization with separate physical servers for their Active Directory server and their Exchange server, this should be the address of the Active Directory server.

Port – The port within the domain’s network which has been opened for the purposes of our LDAP connection. The default port for standard LDAP is 389, and the default port for LDAPS (Secure LDAP) is 636.

Use SSL To Connect? – Check this if you wish us to use secure LDAP. You will need to install a security certificate within the LDAP server’s network to utilize this option (see “Configuration of Secure LDAP” for details).

LDAP LOGIN/QUERY SETTINGS

BindDN (LDAP Username) – Enter the Active Directory user you wish us to use to log in to the LDAP server. This will generally be in the format of the user localpart (in the above bindDN example, “ldapuser”) or the user localpart @ the internal domain name (“[email protected]”, as shown above).




Password – The active directory password for the bindDN user.

Synchronization Interval – Adjust this to determine the frequency with which you would like our system to automatically check the Active Directory for user changes. The default interval is every 24 hours. (Note that regardless of the interval you choose, you may add or remove accounts within the control panel manually at any time; those changes will either be affirmed or overwritten with the next synchronization.)

BaseDN – The container or organizational unit you wish us to examine when querying the LDAP server. In the above example, it is assumed that the users are within the container (CN) named “Container” in the organizational unit (OU) named “Organizational Unit”, within the root internal domain of example.local. See “Determining Your BaseDN” for more details.

Type of LDAP Server – Choose between Active Directory (default), Open LDAP, or other, based upon the variety of directory server which we will be querying.

OVERRIDE EXISTING RECORDS

Allow Updates? – This optional feature allows the ability to configure user attributes within your directory server that will define the spam handling and filtering aggressiveness settings for that user. (See “Advanced LDAP Query Settings” for more information.) This setting is enabled by default; however, if no special attributes are introduced within the domain’s Active Directory and/or defined under the query’s attributes, this option will have no effect.

Allow Deactivations? – Checking this box causes our system to automatically remove any existing GFI MAX Mail email addresses in the event that those addresses are no longer seen in the domain’s Active Directory. This is unchecked by default, meaning that deleting an address from the domain’s directory will NOT result in our system removing that address from GFI MAX Mail.




(OPTIONAL) ADVANCED LDAP QUERY SETTINGS

NOTE: Manually adjusting these settings is only recommended for advanced LDAP users. Unless you have very specific LDAP requirements, using the “Prepopulate the filter and attribute settings below based on my LDAP server type” option will provide the necessary filter and attributes (as shown above) for a standard LDAP synchronization. If you need assistance with these advanced settings, please contact the GFI MAX Mail support team.

Filter – This defines a query specifying what types of users/addresses our system should look for within the Active Directory. Each filter parameter should begin and end with parentheses. A brief explanation of some of the more common commands:

» (objectClass=<AD user type>) – This tells our query which types of user accounts to look for within the domain’s Active Directory. The examples from the screenshot above tell us that the query is looking for any user, person, group, or public folder accounts. Any of these segments can be removed to cause our system to ignore those addresses when querying the domain’s directory.

» (mail=*) – This parameter instructs the query to look for any users which have a defined SMTP account. As shown, this parameter doesn’t look for accounts at any specific domain name, but rather any mail-enabled user. You can further define this parameter by including the name of




a specific domain, which will cause our system to only look for users with addresses at that domain. The format for those filter entries would be (mail=*@<external domain name>).

» Using the query defined in the screenshots as an example, if it were necessary to configure the query to only find users with addresses at example.com and its partner domain sibling.com, this parameter would appear as follows:

- (mail=*@example.com)(mail=*@sibling.com)

» ! – The exclamation point is used to modify a filter parameter to be exclusive rather than inclusive. It can be placed before the opening parenthesis of any parameter in order to instruct the query to ignore any users which fall into that category. For example, if one wanted to configure a query to find users with mail enabled at any domain EXCEPT sibling.com, the filter should include the following:

- (mail=*)!(mail=*@sibling.com)

» (extensionAttribute<number>=<custom attribute>) – This parameter can be used to specify that the LDAP query should look for users with specific custom Active Directory attributes. Each attribute is numbered within the Active Directory, so the filter parameter should include that number, as well as the attribute keyword itself. See your server documentation for more information about adding attributes within Active Directory.

» For example, if a domain’s directory had several users which did not receive external email, one might use attributes to cause our system to search only for users with active, external email accounts. This could be achieved by adding the word “external” as the “1” attribute within the Active Directory to any user which should be added to our system, and including this parameter in the LDAP filter:

- (extensionAttribute1=external)

» Alternately, you could have the LDAP query ignore the internal users rather than look only for active, external users (a slightly different method to achieve similar results). To implement this, one could add the “1” attribute of “internal” to any user which should NOT be checked by our query, and then implement this parameter within the domain’s LDAP filter:

- !(extensionAttribute1=internal)




(OPTIONAL) Attribute Information Attribute – This is the name of the attribute in the LDAP tree where information can be found. These attributes will vary for different LDAP implementations (OpenLDAP, etc.). Custom attributes could potentially be added to the LDAP tree and used to define the threshold and/or handling, although setting these properties via LDAP is not common.

Regular Expression – A regular expression used to selectively capture parts of the value associated with an attribute. The syntax follows the Java implementation of regular expressions, but is similar to other programming languages such as Perl, Python, Ruby, etc. Information on Java regular expression syntax is documented at: http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html

Formatter – Defines a pattern used to format the data extracted from the capturing groups in the regular expression. Data from captured groups is merged into the expression, replacing “{n}” tags, whereby ‘n’ is the number of the captured group (i.e., {0} for the first captured group). Generally, captured groups start at 0 and are assigned from left to right, but rules for complex circumstances are defined in: http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html.

For example, if the “mail” address had an email address formatted for a local domain, [email protected], and it needed to be formatted for the example.com domain, the regular expression would be “([^@]+)@example.local” and the formatter would be “{0}@example.com”.

Mail – The primary email address. Within Active Directory, this setting will always be “mail”.

Alias – This is an alias address. Within Active Directory, this setting will always be “proxyAddresses”. This parameter will typically include the primary address, in SMTP format and potentially other formats stored within Active Directory. The regular expression shown in the example selects only addresses in standard SMTP format.

Login – If LDAP-based authentication is in use, this is the login name to be presented to the Active Directory server when a user attempts to login at the control panel. Within Active Directory, this setting will always be “sAMAccountName” as the attribute.

Threshold – This is the score at which a message is considered spam. Possible values for a given node are: VERYHIGH, HIGH, MEDIUM, LOW, VERYLOW, or UNFILTERED. This would require a custom attribute within the Active Directory tree.

Handling – This is the desired to be taken with detected spam messages. Options are DELIVER or QUARANTINE. This would require a custom attribute within the Active Directory tree.

Once you have completed all necessary fields, click “Preview and Save Changes”.


http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html�

http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html�



PREVIEW LDAP SYNCHRONIZATION

Here, you will have the opportunity to review the data collected from the Active Directory by a test synchronization performed using the parameters you have specified. If there is a problem with those parameters, this is also where the pertinent error will be displayed – see “Common Errors” later in this document for more information.

Email Addresses – This column displays the primary SMTP address of each directory entry our system detected.

Aliases – Alternate SMTP addresses for your directory entries are displayed here.

BindDN (not shown) – This section should reflect the SAMAccountName (login name) for each valid user.

If you are satisfied with these results, click “Save Configuration” to save these settings for later automated synchronization, and you are done! If you wish to save your parameters and run a live query to pull down new users, click “Synchronize and Save”, and continue (as described below in this document). To make changes to the parameters prior to saving, click “Cancel”.




CONFIRM FIELDS IN USER LIST

By default, this screen will show some/all of the email addresses, aliases, and user bindDNs detected by our query. Depending on your query’s attributes, it is also possible that this will display handling or aggressiveness options. You can use the drop-down menus above each column to define how our system treats the included information.

Click “Next” to continue.




USERS DETECTED

Here, you will receive a count of the total number of users detected by the LDAP query as well as the number of addresses that already existed in the control panel for the domain. You will also have the opportunity to configure our system to use any handling or aggressiveness information gleaned from the LDAP synchronization to adjust the configuration of those already present users, or if it should only use those settings for newly-detected users. This only applies if you have configured your query’s attributes to look for handling or aggressiveness information as part of the synchronization; most administrators will want to leave this on the default of “Retain the existing settings that were already in the system”.




USERS NOT DETECTED

This page will confirm the number of accounts and aliases we will be adding to the domain’s user list. In the event that you want to remove any existing accounts in the control panel that are not included in the new LDAP synchronization, you can instruct our system to do this. However, by default, the synchronization will only add new users without deleting any.

Click “Next” to continue.

CONFIRM AND PROCESS NEW USER LIST This final page offers an overview of the changes which will be applied when you click the “Save Changes” button. This will also be the last opportunity to adjust the LDAP configuration before you apply the updated user list.

Click “Save Changes”, and you should be done!

Any questions regarding the LDAP configuration can be directed to the GFI MAX Mail support team.




COMMON ERRORS The following are the errors which may be generated if incorrect LDAP details have been entered. If you are receiving an error when attempting to preview changes, browse through the list below and apply the solution indicated for your error.

Problem: Unable to contact the LDAP server Possible Errors:

» java.net.SocketTimeoutException: connect timed out.

» java.net.ConnectException: Connection refused.

» java.net.UnknownHostException:

Solution: Verify that you have entered the correct hostname or IP for your LDAP server in the GFI MAX Mail configuration page. Also ensure that that your network firewall has been configured correctly and the GFI MAX Mail IP address pool has access to the LDAP server. You should also confirm that the hostname you are using resolves correctly to the public IP address of your LDAP server.

Problem: Incorrect Port Possible Errors:

» java.net.SocketTimeoutException: connect timed out.

Solution: Ensure you have entered the correct port and configured your network firewall to allow connections from the GFI MAX Mail IP addresses to your LDAP server on the required port.

Problem: SSL enabled Possible Errors:

» Able to connect, but unable to query:

» javax.naming.CommunicationException:

» simple bind failed: ldaphost.yourdomain.com:389 [Root exception is javax.net.ssl.SSLHandshakeException: Remote host closed connection during handshake].

Solution: Your LDAP server most likely does not support SSL. Disable the SSL option in the GFI MAX Mail configuration.




Problem: Bad LDAP Username Possible Errors:

» Able to connect, but unable to query: javax.naming.AuthenticationException: [LDAP: error code 49 – 80090308: LdapErr: DSID-0C090334, comment: AcceptSecurityContext error, data 525, vece

Solution: Verify the username provided in the configuration is correct. If the problem persists, enter the username in the following format: [email protected]

Problem: LDAP Username Internal Issues Possible Errors:

» Disabled: Able to connect, but unable to query: javax.naming.AuthenticationException: [LDAP: error code 49 - 80090308: LdapErr: DSID-0C090334, comment: AcceptSecurityContext error, data 533, vece

» Expired: Able to connect, but unable to query: javax.naming.AuthenticationException: [LDAP: error code 49 - 80090308: LdapErr: DSID-0C090334, comment: AcceptSecurityContext error, data 701, vece

» Logon not permitted : Able to connect, but unable to query: javax.naming.AuthenticationException: [LDAP: error code 49 - 80090308: LdapErr: DSID-0C090334, comment: AcceptSecurityContext error, data 530, vece

Solution: The user provided in the configuration does not have the required permissions to perform the LDAP query. Ensure a valid account with the appropriate permissions is provided from the LDAP server to execute the query.

Problem: Bad LDAP Password Possible Errors:

» Able to connect, but unable to query: javax.naming.AuthenticationException: [LDAP: error code 49 - 80090308: LdapErr: DSID-0C090334, comment: AcceptSecurityContext error, data 52e, vece

Solution: The password provided is incorrect. Enter the correct password.




Problem: Incorrect BaseDN Possible Errors:

» Able to connect, but unable to query: javax.naming.CommunicationException: Yourdomain.com:389 [Root exception is java.net.UnknownHostException: Yourdomain.com].

Solution: The BaseDN entered in the configuration is invalid. The following BaseDN are the lowest level DN which should be available for your domain. Entering the following BaseDN should resolve the issue:

Note: The example below is based upon the domain 'yourdomain.com'. This would need to be replaced by your correct domain:

» DC=yourdomain,DC=com (or net, org, etc)

» DC=yourdomain,DC=local

If you do not know your BaseDN, here’s a step-by-step guide to determining Your BaseDN.

Most organizations follow a similar convention for their BaseDN, which is determined when the organization sets up its Active Directory. For a company with the domain of example.com, the BaseDN is typically cn=Users,dc=example,dc=com

In the event that your organization does not follow this convention, and you do not know your BaseDN, following are instructions on how to determine the BaseDN.

1. If adsiedit.msc is not installed, install it from the Windows CD, from support\tools\supptools.msi. You must be an administrator to do this.

2. Click Start then Run, type adsiedit.msc and hit Enter

3. You should see the ADSI Edit window, with three trees: Domain, Configuration, and Schema. Expand the Domain tree.

4. You should see a folder under Domain, which will be named something like “DC=example,DC=com”. This is the BaseDN.

You can also use this tool to determine the username, referred to in LDAP lingo as the BindDN, for the user you set up to log in to your Active Directory server.

1. Expand the “DC=example,DC=com” tree. You should see a “CN=Users” entry. Expand that tree, and find the user that you have created for GFI MAX Mail for the synchronization.




2. Note that if you have separated users into different “folders”, such as “accounting”, “sales”, etc, then you will have entries such as “CN=sales” in addition to the CN=Users. If you want to synchronize only users within a particular folder, we can use that as the BaseDN (e.g, “CN=sales,DC=example,DC=com”).

3. Right click on the user, and click properties. The properties for this user will come up. Select the “attribute editor” tab, and scroll down until you find the attribute “distinguishedName”. Copy down the *entire* value (such as CN=GFI MAX Mail,DN=Users,DC=example,DC=com”) *exactly* as shown in this window. This is the BindDN.

© 2010. GFI Software. All rights reserved. All product and company names herein may be trademarks of their respective owners.


Documents

Gfi Max Mp Ldap Guide