Skip to main content
Skip table of contents

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. 

  1. Create a new user in your directory that will solely be used by AppsAnywhere (e.g. s2hub_service_user)

  2. 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:
  1. Log into AppsAnywhere as an admin user

  2. Click on Return to Admin to access the AppsAnywhere admin portal

  3. Select the environments menu on the top right of the page, go to LDAP Connections

  4. 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. 


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.