SAML is an open standard for authentication and authorization. Using SAML, a service provider (like Deskpro) can check if a user is authorized with an identity provider or IdP.

SAML is provided by many third-party products, or your organization may have its own SAML IdP. Deskpro is compatible with SAML 2.0.

To set up SAML, you will need to install and configure the SAML authentication app in Deskpro, and enter settings for Deskpro into your IdP.

SAML settings in Deskpro

1. Go to Agents > Auth & SSO or CRM > Auth & SSO, depending on whether you want to set up SAML for agents or users.

2. Click + Add then click on the SAML app.

3. Find and enter the following URLs that should be provided by the IdP:

   Single Sign-On Service URL (this may also be called SAML Login URL or SSO URL): this is the URL where DeskPRO will redirect the user/agent for authentication.

   Single Logout Service URL - (this may also be called SAM Logout URL or SLO URL): this is used to log users/agents out.

   Some IdPs provide XML metadata describing their service. You can find the URLs in the <md:SingleSignOnService and <md:SingleLogout Service> fields. You can also enter a URL for the XML metadata and DeskPRO will attempt to extract the URLs.

4. Enter x509 certificate details: this is used by Deskpro to verify the IdP’s identity. The IdP may provide the full x509 Certificate or the x509 Certificate Fingerprint (SHA1 fingerprint) - you only have to enter one of these.

5. Set the SSO Method and optional Login Button Text - see  Understanding SSO options for details.

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

7. (User authentication only) Set the  Auto agent option. This controls the usergroup granted to users who log in through SAML.

8. Click Save Settings.

SAML IdP settings

You will need to enter settings from the Deskpro SAML app into the SAML identity provider.

The exact settings required will vary, but you are likely to need to provide:

Assertion Consumer Service URL (also referred to as ACS or Post Back URL or Recipient or Destination): this is the URL where Deskpro receives the authorization from the IdP. This is displayed after you install the Deskpro SAML app as above.

Single Logout Service URL (this may also be called SLO or SLS URL): this is used to log users/agents out. This is displayed after you install the Deskpro SAML app as above.

Metadata URL (also referred to as Entity ID or Audience Restriction): this is a URL that uniquely identifies your helpdesk as a service provider and provides information about it. This is displayed after you install the Deskpro SAML app as above.

SAML IdP attributes

When the IdP responds to Deskpro, it must return the user attributes in the following format:

By default, your IdP may not use these field names, resulting in users/agents being created with no name or email information.

This will result in agents being created with names like ID-2:

Most IdPs provide a way to configure the attributes. Set the IdP to return the exact field names above.

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:

   

   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.

   

   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.