Okta authentication enables your agents and/or users to sign in to your helpdesk with an Okta account.

The setup process involves installing a Deskpro app within Okta. You can then select which of the Okta users you manage can log in with Deskpro.

To enable Okta authentication:

1. Log in to the Okta website. Go to the Admin area.

2. Go the Applications tab and click Add Application. Find the Deskpro application and click Add.

1. You will be asked for an Application label, this should be a unique name for the application so you know which Deskpro Instance the Okta application is linked with. You can also choose if the app icon should be visable to users or not (this can be changed at a later date if needed).

Click done to add the app to Okta.

1. The app will by default open on the Assignments tab. Here you can add users/groups by searching or using Okta's filters from your exsiting user/group pool. If you currently do not have an acccount to assign this can be added later.

1. Go to the Sign On tab within the Deskpro app in Okta. Click the View SAML Setup Instructions button and the instructions for how to set up Deskpro in Okta will open in a new tab/window.

1. Within your Deskpro Horizon Admin area, if you are setting up Okta for agents you go to Agents > Auth & SSO. If setting up for users, you add this in CRM > User Auth & SSO.

When you add the application it will ask for a number of fields, the content of which will be found in the Setup SSO tab that was opened from within Okta.

1. Once this has been filled in click save in the app. You will then need to go back into the app's configuration settings to get the SAML Details that will need adding to the Okta configuration.

1. In the Okta app, go to the Sign On tab and click Edit. This will give input boxes for the infomation we have just got from the Deskpro config.

Then click save.

1. (Agent authentication only) Set the Auto Agent option. This controls which permissions are granted to agents who log in through Okta and don’t have an existing Deskpro account.

2. (User authentication only) Set the  Grant Usergroup option. This controls the usergroup granted to users who log in through Okta.

3. Click Save Settings then Test Settings.

Make sure the Okta account that you’re currently logged into is added to the Deskpro app within Okta before you use the Test Settings button.

If you want to set up Okta for both agents and users, you should repeat these steps, installing a new copy of the Deskpro app within Okta, and entering the settings from that app on Deskpro.

Use a different Application label settings for the two apps to avoid confusion.

Bear in mind that the Application label is shown to users/agents when they log in through Okta, so you should choose a label that will make sense to them.

Managing Okta users

Now that you’ve linked Okta to your helpdesk, you can grant Deskpro login rights via Okta.

In Okta, create accounts in the People tab, then go to Applications, click on the relevant Deskpro app, then use Assign Application to add the person to that app.

Agents you add via Okta will be added to the permission group specified in the Auto Agent settings.

You must grant agent access to the admin and reports interfaces from within Deskpro.

Additional user data

An external usersource (such as Active Directory or Okta) 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.phpin 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 CRM > User Auth & SSO (or 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 log.

   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.

   Here’s some example data:

   

   In this case, if you wanted to import the user’s display name, you would use displayName.0 as the field name.

6. Go to CRM > Fields > User Fields. 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 false once 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.