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 to Applications and click Browse App Catalog. Find the Deskpro application and click Add.

1. You will be asked to add the Application Label. You may want to edit this to show if you will be using this app to log in Agents or Users. Then click Next.

2. On the next screen, you can select which people can log on to your helpdesk through Okta. Click Assign > Assign to people to add the relevant Users or Agents. Search the User(s) you want to add and click assign. Then click Save and go back. And then click done.

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

1. Follow the set up instructions which you opened in step 6 above. Note that if you are setting up Okta for agents, you should go to Agents > Auth & SSO, not CRM > Auth & SSO.

2. (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.

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

4. 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. See  Okta setup below.

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 different Application Label settings for the two apps to avoid confusion.

Bear in mind that the Application Label is shown to Users and 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. Go to CRM > Auth & SSO (or Agents > Auth & SSO) and select the app.

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

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

1. Go to 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.

1. Repeat for any other data fields you require.

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