Introduction

The AppDynamics Controller can authenticate users against external Lightweight Directory Access Protocol (LDAP) servers. The Controller integrates with servers that use LDAP version 3 protocol.

To configure LDAP authentication in the Controller, you need to configure connection settings to the LDAP server and the queries that return user or group data. By mapping LDAP groups to roles, you can provision permissions in the AppDynamics Controller based on LDAP groups.

Preparing the LDAP directory for AppDynamics integration

To use an LDAP authentication provider, your AppDynamics Controller needs to be able to connect to the external LDAP server. A good practice is to create a user account in LDAP specifically for the Controller to use to authenticate itself to the server and run the queries. The Controller user only needs to have search privileges in LDAP.

While you can map existing LDAP group definitions to roles in AppDynamics, your existing groups may not correspond directly to roles in AppDynamics. The easiest way to map LDAP groups to Controller roles is to create a group in LDAP for each role you want mapped in AppDynamics. This gives you a manageable, 1-to-1 correspondence between your LDAP groups and AppDynamics roles.

For example, a possible LDAP group scheme for mapping in AppDynamics would be:

AppDynamics-AppA-ReadOnly
AppDynamics-AppA-Admins
AppDynamics-AppA-DashboardViewers
AppDynamics-AppB-ReadOnly
AppDynamics-AppB-Admins
AppDynamics-AppB-DashboardViewers

The sample group names imply having custom roles in AppDynamics targeted to specific applications, AppA and AppB.

Naming the groups with a common prefix, as the "AppDynamics-" prefix in our sample, allows you to use a relatively simple LDAP group filter. A group filter for the sample groups could be:

(&(objectClass=group)(cn=AppDynamics-*))

Using paged results for large result sets

LDAP servers are sometimes configured to limit the number of entries it can return in a query response. If the results of your user or group query exceed that limit, AppDynamics reports a max_results_exceeded error.

To avoid this error, first try to refine your query filter to produce a smaller result set. Of course, the results still need to include the users who will need to access the AppDynamics UI. See To Configure the Query to Find Users and To Configure the Query to Find Groups.

If your LDAP server supports it, you can also enable paged results in the Controller LDAP configuration. With paged results, the LDAP server divides the result set into separately transmitted blocks.

The paged results feature applies to the behind-the-scenes interaction between the AppDynamics Controller and the backend LDAP server. It does not affect the UI view of the data.

LDAP Authentication with a SaaS AppDynamics Controller

Depending on your organization's security policies, it may not be possible to use LDAP authentication with the SaaS AppDynamics Controller, since doing so requires opening your firewall to permit Controller access to your corporate LDAP server.

However, if you do want to enable LDAP authentication with SaaS AppDynamics Controller, you will need to permit access through the firewall for the IP range of 69.27.44.0/24, the IP address range assigned to AppDynamics SaaS Controllers. The firewall rule should permit incoming LDAP requests from the Controller at the LDAP port you configure.

What Happens if the LDAP Server Becomes Unavailable

If you have configured the controller to use LDAP for authentication and the LDAP server becomes unavailable for any reason, AppDynamics falls back to local user authentication. Given this possibility, you should provision local user accounts in AppDynamics for users who need to access AppDynamics in the event that the LDAP server becomes unavailable.

What Happens if a User is Not Found in the LDAP Directory

In this case the authentication failure is logged as a warning. The user, whether it is a regular controller user or a REST client user, may still be authenticated through local authentication.

Before Starting

To perform LDAP configuration you must have:

An LDAP server. There is a one-to-one correspondence between an AppDynamics account and an LDAP server.
An account on an AppDynamics SaaS or on-premise Controller
Account administrator privileges on the AppDynamics Controller, as described in Administrative Users.
Network connectivity between your LDAP server and the Controller. If using a SaaS Controller, the LDAP server may not be accessible to the Controller without enabling access through your network firewall. See LDAP Authentication with a SaaS AppDynamics Controller.

Configuring LDAP Authentication

At a high level, the steps for setting up LDAP authentication include:

Configure the connection to the LDAP server.
Configure and test the LDAP query that returns users to be provisioned in the AppDynamics Controller.
Configure the LDAP query that returns the LDAP groups to be mapped to AppDynamics roles.
Map the users or groups to roles in AppDynamics.

To Configure the Connection to the LDAP Server

As an administrator or account owner in the Controller UI, click Settings -> Administration.
Click the Authentication Provider tab.
Select LDAP. The LDAP configuration settings appear.
If your user or group query will return more entries than permitted by the LDAP server and the server support paged results, configure paged results as follows:
- Enable Paging: Check this option to have the Controller request paged results from the server when submitting user or group queries.
- Page Size: Enter the number of entries per round-trip from the AppDynamics Controller to the LDAP server. The default is 500.
The page size should be the total number of entries to be returned divided by the number of round trips between the LDAP server and the Controller that are tolerable. For example, if you expect to receive 1200 results in a query and you can tolerate a maximum of two round trips, set the page size to 600 (1200 /2).
See Using paged results for large result sets for more information.
In the Connection String section of the LDAP configuration screen, enter the information AppDynamics uses to connect to the LDAP server:
- Host: Address of the LDAP server. Required.
- Port: Port that the LDAP server listens on. Default is 636 for an SSL connection and 389 if not using SSL. Required.
- Use SSL: Enabled by default to use a secure connection to the LDAP server. Clear if not using SSL.
- Enable Referrals: Enabled by default to support LDAP referrals. A referral is when an LDAP server forwards an LDAP client request to another LDAP server. Each referral event is referred to as a hop.
- Maximum Referral Hops: The maximum number of referrals that AppDynamics will follow in a sequence of referrals. Default is 5.
- Bind DN: Distinguished Name of the user on the LDAP Server on whose behalf the AppDynamics application searches. Required.
- Password: Password of the user on the LDAP server. Required. Your settings should look something like this:
Click Test Connection to ensure that the connection string works properly.
When the connection test is successful, click Save.

To Configure the Query to Find Users

Navigate to the LDAP configuration page if it is not already open. See To Configure the Connection to the LDAP Server.
In the Users Query section of the LDAP configuration screen, enter the information to use to find LDAP users:
Base DN: Location in the LDAP tree to begin recursively searching for users. Required.
Filter: Optional LDAP search string that filters the items matched from the base DN. See RFC2254 for information about LDAP search filters.
Login Attribute: The LDAP field that corresponds to the username users will enter when logging in to the AppDynamics UI. The default is "uid". For Active Directory, this would typically be “sAMAccountName".
Display Name Attribute: The LDAP field to be used as the user's display name.
Group Membership Attribute: Optional user group membership field. Recommended for faster retrieval.
Email Attribute: Optional user email address.
To test the configuration, click Test Query.
This launches a screen displaying the first few users returned by the query.
Click Save.

To Configure the Query to Find Groups

Optionally, you can map LDAP groups to user roles in the AppDynamics Controller. To do this, you need to set up the LDAP query that returns the LDAP groups to map, as follows.

Navigate to the LDAP configuration page if it is not already open. See To Configure the Connection to the LDAP Server.
In the Groups Query section of the LDAP configuration screen, enter the information to use to find LDAP groups:
- Base DN: Location in the LDAP tree to begin recursively searching for groups. Required.
- Enable Nested Groups: Option to include nested LDAP groups to a depth of 10.
- Filter: Optional LDAP search string that filters the items matched from the base DN. See RFC2254 for information about LDAP search filters.
- Name Attribute: The LDAP field that contains the name of the group. Default is "cn". Required.
- Description Attribute: The LDAP field that contains a description of the group. Optional.
- User Membership Attribute: Identifies members of the groups. Optional.
- Referenced User Attribute: Optional child attribute of the User Membership Attribute. Disabled if the parent is empty. Identifies property of the user that the user membership attribute contains.
To test the configuration, click Test Query.
A screen appears that displays the first few groups returned by the query.
When the query test is successful, click Save.

You can now assign permissions in the AppDynamics Controller to users or groups.

To Assign AppDynamics Permissions to an LDAP User

In the Security Configuration window, click the Users tab.
If LDAP is enabled and correctly configured, the AppDynamics Controller fetches the user names from the LDAP server.
Select the name of the user to whom you want to assign permissions.
In the Roles panel, check the roles that you want to assign to this user. You can assign multiple roles to a user.
Click Save.

To Assign AppDynamics Permissions to an LDAP Group

LDAP Group configuration is optional.

In the Security Configuration window, click the Groups tab.
If LDAP is enabled and correctly configured, AppDynamics fetches the group names of users in LDAP.
Select the name of the group to which you want to assign permissions.
In the Roles panel, check the roles that you want to assign to this group. You can assign multiple roles to a group.
Click Save.

Configuring the LDAP Cache Synchronization Frequency

The Controller keeps information about LDAP users and groups in a local cache. It regularly connects to the LDAP server to synchronize its cache with the LDAP server.

The Controller caches information about users and group membership. It does not cache user passwords. Accordingly, the Controller authenticates the user credentials against the LDAP server at the start of every user session.

If a user account is removed from LDAP, the change is reflected immediately; that is, the user will not be able to log in to the Controller UI from that point. However, if the user has an existing session in the Controller UI, that session continues until the user logs out or the session expires.

If the user's access to the Controller is based on group membership and the user is removed from the group but maintains an account in the LDAP server, the user will be able to log in to the Controller until the next time synchronization with the LDAP server occurs. By the default synchronization frequency setting, this ability to access the Controller UI could continue for up to an hour.

You can modify the default synchronization frequency of one hour as described in the following procedures.

To Configure the LDAP Synchronization Frequency

Stop the Controller application server:
- On Linux, run:
```
./controller.sh stop-appserver
```
- On Windows, run this command from an elevated command prompt (which you can open by right-clicking on the Command Prompt icon in the Windows Start menu and choosing Run as administrator):
```
controller.bat stop-appserver
```
Open the <Controller-Installation-Directory>/appserver/glassfish/domains/domain1/config/domain.xml file for editing.
In the <jvm-options> element, add a system property named appdynamics.ldap.sync.frequency with the desired synchronization frequency in milliseconds.
For example, to have the Controller synchronize to the LDAP server every 15 minutes (900000 milliseconds), add:
```
<jvm-options>-Dappdynamics.ldap.sync.frequency=900000</jvm-options>
```
The default is 3600000 milliseconds (1 hour).
Save the file.
Restart the Controller app server:
- On Linux, run:
```
./controller.sh start-appserver
```
- On Windows, run the following in an elevated command prompt:
```
controller.bat start-appserver
```

Learn More

Configure Authentication Using LDAP