The Active Directory Authentication app enables you to log in users and/or agents with credentials from Active Directory.

You can optionally enable Auto Sync of data, so that Deskpro accounts are created and regularly updated with the latest information from Active Directory. This is a one-way process, from Active Directory to Deskpro. If you need to update account information, you should do it in Active Directory.

If you select this option, data will automatically be pulled from Active Directory daily at 1am. You can also sync manually at any time.

Creating agents from AD

By default, if you install Active Directory authentication for agents, DeskPRO allows existing agents to log in with their Active Directory credentials. Agents are matched using their email address.

You can optionally enable Auto Agent, which will automatically create an agent account for agents who don’t exist. Otherwise, you must create a Deskpro account with the same email address as the record in Active Directory, before the agent can log in using

You can also enable Auto Sync, which will create an agent account for every record under the Base DN you specify.

Installing AD

To set up Active Directory Authentication for users, go to Admin > CRM > Auth & SSO; to install it for agents, go to Admin > Agents > Auth & SSO. If you want to use Active Directory for both users and agents, you should install it in both places.

Accounts created from this app will enable users/agents to log in with their username, username in backslash format (e.g. DOMAIN\user1) or email address.

1. Click + Add and click the Active Directory Authentication app.

2. Check Yes, enable Active Directory Authentication.

3. Select Enable Auto Sync if required.

1. In Server, enter the Active Directory server name and port.

   You must ensure that your Active Directory is accessible to your Deskpro server and not blocked by a firewall etc.

   Optionally, select the encryption method to use.

   The default port if you are not using connection encryption or are using TLS is 389. If you are using SSL encryption, the default is 636.

   On some configurations, you may need to specify port 3268 to search the Global Catalog.

2. In Base DN, enter the DN to search from for users. All Active Directory user objects below this node will become users/agents in Deskpro.

1. In Service Account enter the username and password for an account to initially bind to the AD directory. The service account must have sufficient permission to run filter queries against the directory.

2. In Domain Name, enter the fully-qualified domain name for users in this directory.

   Optionally, enter a short NetBIOS style domain name. This is required if you want to support usernames in backslash form e.g. DOMAIN\user1.

3. In most cases, you should not use Disable LDAP Paging. If paging is not enabled or working on your AD server, you may find that you get 0 records when you try to sync, even when there are user objects under the Base DN. In that case, try disabling paging.

4. In most cases, the default LDAP Size Limit of 1000 will work. If your Active Directory has a lower LDAP Size Limit than 1000, enter it here.

5. Optionally use the Filter option if you want only some of the user records within Active Directory to be valid users/agents in DeskPRO. See  Filtering a usersource for details of how this works.

6. (Agent authentication only) Choose whether to enable the  Auto agent option. If you are using Auto Sync, you will wabt to enable this, but make sure you are not syncing from an Active Directory with too many user records. Select a permission group to grant to agents who are created from Active Directory.

7. (User authentication only) Set the  Grant usergroup option. This controls the usergroup granted to users who are created from Active Directory.

8. Click Test Settings and enter the username/email and password of a user who is under the Base DN.

9. If the test is successful, click Save Settings. If it fails, read any error messages, check the settings and try again. You may need to consult the documentation for your version of Active Directory, or speak to your server administrator.

You will now see a Start Sync button below the list of authentication sources. Click it to import the users/agents into Deskpro.

Increasing sync speed

In versions of Deskpro On-Premise before #410, there was an issue where syncing multiple AD sources could take a very long time, so be sure to update your helpdesk.

If you are on On-Premise #411 or higher and find that syncing is taking a long time, you can increase the speed of the process by increasing the PHP memory limit.

Edit your php.ini file to increase the value for memory_limit to “256M”.

Filtering user records

If you only want to use a subset of the user records in your Active Directory, use the new  Filtering a usersource feature.

Note that you can install multiple versions of the Active Directory app if you want to authenticate different groups of users with different permissions.

Additional user data

Your usersource may have additional user data beyond the user’s email address and password: for example, employee numbers, location information, etc.

You can set up Deskpro to copy this data into a custom user field so it is available in your helpdesk when you view each user’s profile.

1. Make sure the authentication app for the desired usersource is installed in Deskpro and working correctly.

2. If you have an On-Premise helpdesk on DeskPRO build #430 or earlier, open config.php in the Deskpro install folder.

   Edit this line:

   $DP_CONFIG['debug']['enable_usersource_log'] = false;

   to say

   $DP_CONFIG['debug']['enable_usersource_log'] = true;

   This step is not required on later Deskpro versions.

3. Go to Admin > CRM > Auth & SSO (or Admin > Agents > Auth & SSO) and select the app.

4. Click the Test Settings button. Enter some login credentials for a user in the external usersource which you know are valid.

5. You will see a results page.

   Click Show user data.

   You will see an encoded list of values that are returned from the usersource.

   Make a note of the field name for the value you want to copy into your helpdesk (ignoring any square brackets around it).

   Here’s a sample excerpt from an Active Directory app:

   

   In this case, if you wanted to import the highlighted value, you would use telephonenumber as the field name.

6. Go to Admin > CRM > Fields > User. Click Add button and choose the “User Auth Data” field type.

   Fill in the title and description.

   In Field Name, enter the name of the field as returned from your usersource in step 4.

   

   You can optionally choose to make the field specific to a particular authentication app.

   Click Save.

7. Repeat for any other data fields you require.

If you edited the $DP_CONFIG['debug']['enable_usersource_log'] value in step 2, change it back to falseonce you are finished.

Working with data collections

If your usersource returns collections of data (e.g., arrays of nested data), you can access sub-elements of a collection by using “dot notation”. For example, given this collection of values:

[example] => Array(
    [inner] => Array(
        [value1] => Hello
        [value2] => World
    )
)
 copy

You can gain access to the “World” value by using the field name “example.inner.value2”.

If you omit the last part of a collection name, DeskPRO will automatically concatenate all values together as a single string.