Adding an LDAP connection

Overview

AppsAnywhere links to your user directory for all it's user management and authentication. Once you link AppsAnywhere to your directory you will be able to select Users, Groups or Machines to which you want to link applications and once your have provisioned applications to them, they will be able to log into AppsAnywhere. In this article, we will discover how to create a new connection to Active Directory via LDAP.

Before you begin

Create a service user

AppsAnywhere will need a user account that it can use to connect to your directory. This account is used to query available users, groups and machines in your directory and authenticate users when they are logging in. This service account only needs to be a standard user account but must have access to query all relevant parts of the directory.

Create a new user in your directory that will solely be used by AppsAnywhere (e.g. s2hub_service_user)
Give the user a strong password and make a note, you'll need this in the next section

Any changes to the password for the service account will result in AppsAnywhere no longer being able to communicate with your directory service and a loss of service for your users. We strongly recommend you set the password for this account to never expire. If you want to enforce a password change policy, arrange for this to be done manually at times when you are able to simultaneously update the password used by AppsAnywhere. See Editing an LDAP connection.

Creating the connection

You are now ready to set up the connection between AppsAnywhere an your directory.

Navigate to the Add LDAP Connection page:

Log into AppsAnywhere as an admin user
Click on Return to Admin to access the AppsAnywhere admin portal
Select the environments menu on the top right of the page, go to LDAP Connections
Click on the Add button on the top right of the page

Enter the details of your LDAP connection:

Form Field Name	Explanation	Expected Value	Example
Type	The type of directory you are connecting to	Select one from Active Directory or OpenLDAP	Active Directory
Name	A friendly name for the connection	You can call the connection anything you want	Campus Directory
Priority	If you have more than one connection available to your users, you can add a priority to dictate where it appears in the list that is presented to the user when they log in	1, 2, 3, 4....	1
Host	The fully qualified hostname to which the LDAP connection will be made	Ideally, this would be the top level, load-balanced address of your directory	uni.edu
Port	The port number to make the LDAP connection over	This usually depends on what type of security you are using (see below). The default, unsecured port is 389	636
Encryption Type	The type of encryption (if any) to be used when initiating the connection	You should aim to use the best type of encryption available (TLS)	SSL
Domain Name	The full domain name of your directory	The name of your top level domain	uni.edu
Short Domain Name	The shortened name for your domain	This is usually the same as above but without the .edu or .ac.uk If you are unsure, type %userdomain% in command prompt on a machine connected to that domain to get the short name.	uni
Domain Aliases (UPN Suffixes)	Additional UPN suffixes that have been configured for users in your directory Ensures that users with different UPN suffixes can be correctly associated with this LDAP connection during login	This setting is optional, but allows you to list any additional UPN suffixes that AppsAnywhere can expect to see when users authenticate The UPN suffix is the portion following the @ symbol in the user's UPN	staff.uni.edu;student.uni.edu
Username Format	The format to be used for the username, currently either sAMAccountName or User Principal Name	The value which best represents your use case, whether users will be matched by their sAMAccountName or UPN. The default value is sAMAccountName.	sAMAccountName
Username	The username of the service that AppsAnywhere will use to connect to your directory	You only need to enter the basic username, no domain prefixes or suffixes are required, unless you have set "Bind Requires DN" (see below), in which case you should add the full DN for the service user	s2hub_service
Password	The password for the service account referenced above	You should aim to make this as complex as possible and ideally, it shouldn't be changed, unless you are ready to update the AppsAnywhere connection details	d%f6SJ2*0kSwp2J1Bm$d
Base DN	The highest level of your directory tree you wish to connect to	This is usually made up of your domain name to represent the top level of your domain	dc=uni,dc=edu

Passwords must not contain < or > characters, otherwise the LDAP connection will fail.

The following settings are also available, but only usually relevant to OpenLDAP connections or more advanced scenarios.

Form Field Name	Explanation	Expected Value	Example
User unique ID attribute	The name of the attribute to retrieve the unique object ID from, defaulting to ‘entryUUID’.	The attribute your OpenLDAP connection uses to retrieve the unique object ID	entryUUID
Bind Requires DN?	Indicates whether or not an attempt to authenticate a user against the directory must include the DN under which they are being authenticated Remember to set the username value to the service user's full DN if you set this value to "Yes"	It is expected that this will be "Yes" for OpenLDAP connections and "No" for connections to Active Directory	No
Enable Paging?	Whether or not to page results from your directory	It is expected that paging will be available on most directories and should be used where available to improve performance of search	Yes
Max Results	The number of results to return from each query to your directory	This depends on the performance you are getting when using our LDAP browser. If queries are taking longer then you should lower this value to return less records at a time	1000
Account Filter Format	The LDAP search filter used to search for accounts.	This string is a printf()-style expression that must contain one ‘%s’ to accommodate the username. The default value is ‘(&(objectClass=user)(sAMAccountName=%s))’, unless bindRequiresDn is set to TRUE, in which case the default is ‘(&(objectClass=posixAccount)(uid=%s))’. This also may change based on the Username Format field used above. If the UPN value is used, then the format may look like ‘(&(objectClass=user)(userPrincipalName=%s))’	accountFilterFormat = ‘(&(objectClass=user)(sAMAccountName=%s))’.
User Classes	The directory classes or "tags" that indicate user objects	The two default classes in Active Directory are "person" and "user" but these can vary in OpenLDAP-compatible directories Value is a semi-colon separated list of attributes	person;user
Group Classes	The directory classes or "tags" that indicate group objects	The default class in Active Directory is "group" but this can vary in OpenLDAP-compatible directories Value is a semi-colon separated list of attributes	group
Machine Classes	The directory classes or "tags" that indicate machine objects	The default class in Active Directory is "computer" but this can vary in OpenLDAP-compatible directories Value is a semi-colon separated list of attributes	computer
Search Attributes	The attributes to search when searching the directory	The attribute in your directory that includes your user's username and/or friendly name Value is a semi-colon separated list of attributes	cn
Wildcard Search Attributes	Which of the attributes specified in "Search Attributes" should be used in wildcard searches.	A subset of the "Search Attributes" specified above. Value is a semi-colon separated list of attributes	cn

Test the connection

A separate “Test connection” button is available next to the “Save” button on the form, which can be used to help you determine whether working details have been entered or not. The details in the form will not be saved when this button is used, allowing you to make sure the entered details are correct before committing to anything.

The “Test connection” button next to the “Save” button

More information about this connection test can be found on the Status dashboard page, and in the Troubleshooting section on this page right here.

Save the connection

Once you have entered all of the relevant details of the connection, hit the Save button.

AppsAnywhere will attempt the same connection test when you save the connection details, and (if successful) the details will be saved.

You will then be sent back to the Viewing LDAP Connections page, where you should see your new connection and the following message.

Troubleshooting

If AppsAnywhere is unable to successfully connect to your directory, you will see an error message like the one below

Use the following table to identify the error message and make changes to the details you have entered to rectify the problem.

Error Message	Suggested Action
The LDAP service is not reachable	Check the hostname you entered is correct and reachable from the AppsAnywhere server Check the port you entered is correct
Server is unavailable: there was an error initialising SSL/TLS	Check the encryption type specified is correct for your directory security settings Add the certificate for your directory to the OpenLDAP configuration file (contact the AppsAnywhere team for assistance)
Invalid bind credentials have been given	Check the username and password you entered for the service account are correct Check the port number and encryption type are correctly set
An invalid base DN has been given: incorrect syntax	Check the value of your Base DN matches the true value in your directory
Administration limit has been exceeded	Check the rate limit setting against the service account in your directory
An unexpected LDAP error has occurred	Make sure you entered a username and password for the connection If you are editing a connection, check that you re-entered the service user password If "Bind Requires DN" is ticked, try un-ticking it Ensure you don't have another connection with the same short domain name

If you continue to struggle, contact a member of the AppsAnywhere support team.