Admin Guide

Okta setup


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

Note

If you’re using Deskpro On-Premise, you should ensure that SSL is set up on your helpdesk before installing Okta.

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.

    ../_images/okta-addapp.png

  3. You will be asked to enter some parameters. You may want to edit the Application label to show if you will be using this app to log in agents or users.

    Enter http://example.com for the requested URLs.

    ../_images/okta-addapp2.png

    Click Next.

    4. On the next screen, you can select which people can log on to your helpdesk through Okta. The Username you select must be their primary email in Deskpro. (If you don’t already have your users/agents added to Okta, you can come back and add them later.)

    ../_images/okta-usernames.png

  4. Click Done.

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

    ../_images/okta-setup-button.png

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

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

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

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

Note

The Test Settings function uses a pop-up. You may need to enable pop-ups for your helpdesk to see it or disable you pop-up blocker.

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/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 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 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:

    ../_images/okta-values.png

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

    ../_images/auth-user-auth-data.png

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

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.

Comments (0)

Add a comment

Add a comment

You need to log in before you can submit a comment.

Need a password reminder?