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.
Because SAML is a complicated standard, the way it is implemented can vary. Be prepared to experiment with the settings of the IdP and the Deskpro SAML app. We cannot guarantee that Deskpro will work with a particular identity provider.
If you’re using Deskpro On-Premise, you should ensure that SSL is set up on your helpdesk before using SAML authentication.
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
Go to Agents > Auth & SSO or CRM > Auth & SSO, depending on whether you want to set up SAML for agents or users.
Click + Add then click on the SAML app.
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:SingleLogout Service>fields. You can also enter a URL for the XML metadata and DeskPRO will attempt to extract the URLs.
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.
Set the SSO Method and optional Login Button Text - see Understanding SSO options for details.
(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.
(User authentication only) Set the Auto agent option. This controls the usergroup granted to users who log in through SAML.
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:
|user or agent email|
|name||user or agent full name|
|first_name||user or agent first name|
|last_name||user or agent last name|
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.
Make sure the authentication app for the desired usersource is installed in Deskpro and working correctly.
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;
$DP_CONFIG['debug']['enable_usersource_log'] = true;
This step is not required on later Deskpro versions.
Go to Admin > CRM > Auth & SSO (or Admin > Agents > Auth & SSO) and select the app.
Click the Test Settings button. Enter some login credentials for a user in the external usersource which you know are valid.
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.
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.
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.