If you use Active Directory Federated Services (ADFS), then you are able to use these services as a SAML authentication method to access Deskpro.

The guide below should walk you through the process of configuring both Deskpro and ADFS.

Retreiving the Token Signing certificate

Before we start, we will need the public copy of the Token Signing Key which ADFS uses to verify the user's credentials. To do this, you will need to access your ADFS server.

Finding the certificate

Open Start > AD FS Management, then within this program, navigate to AD FS > Service > Certificates in the left-hand tree menu.

This should show a list of different types of certificates. In this instance, we need the Token-signing certificate for your ADFS server:

Double click on the certificate to open it.

Exporting the certificate

From this window, click the Details tab, then Copy to file...

This should open the Certificate Export Wizard. We need the certificate in Base-64 encoding, so select Base-64 encoded X.509 (.CER) and click Next

Then, enter a path to export the certificate, and make sure it ends in .cer, before clicking Finish to complete the export

Viewing the exported certificate

This should create a new file in the location specified, which you can open in Notepad to see the certificate in Base-64 format

Configuring Deskpro

At this point, we need to configure Deskpro, as there will be some information provided after the app has been installed which is required to complete the ADFS configuration.

Installing the SAML App

To install the SAML App, first go to either Admin > Agents > Auth & SSO to enable ADFS SAML for Agents, or go to Admin > CRM > Auth & SSO to enable ADFS SAML for Users.

At the top left-hand corner of your screen, you should see a list of existing authentication methods. To add a new one, click + Add

Then, from the options available, select SAML Authentication

Configuring the SAML App

To configure the SAML app, you need to build 2 URLs using your ADFS server's address:

https://<adfs_url>/adfs/ls - This is used for the SSO: Single Sign On URL field.
https://<adfs_url>/FederationMetadata/2007-06/FederationMetadata.xml - This is used for the Metadata: Issuer XML metadata URL field.

You will also need the Token Signing certificate exported earlier to place in the x509 Certificate field.

In addition, you MUST also select urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified for the Name ID Format field, as this is a requirement for ADFS.

At this point, you can click the Install App -> button to install the application.

Once the app has installed, this should generate the SAML details, which are required for configuring ADFS.

Configuring ADFS

Now the application has been installed on Deskpro, we are able to configure ADFS to recognise Deskpro and allow users to authenticate to it.

Adding the Relying Party Trust

Open Start > AD FS Management again, and on tree menu, navigate to AD FS > Trust Relationships > Relying Party Trusts. Once in that folder, right click on the folder in the tree view and select Add Relying Party Trust...

This should open the wizard to walk you through the process. Click Next to continue

As we do not have a Federation metadata address, or a Federation metadata file, we will need to Enter data about the relying party manually, then click Next to continue.

The next page just requires a name for the relying party, and if you would like to add any notes to help identify the relying party, you can do so here.

As we will be using SAML 2.0 for the integration, select AD FS Profile.

Skip the next option, as we have already imported the Token Signing Certificate earlier.

As we are using the SAML 2.0 protocol, check Enable support for the SAML 2.0 WebSSO protocol, then in the Relying party SAML 2.0 SSO service URL field, enter your Consumer Service URL (ACS) from your Deskpro's SAML Details created earlier.

For the Relying party trust identifier, enter the Metadata URL (Entity ID) from your Deskpro's SAML Details created earlier. Click Add to add it to the list of identifiers.

If you wish to configure multi-factor authentication, you can do so at this point.

If you would also like to restrict which users have access to Deskpro through this integration, you would do so here.

You can then review the settings above to ensure they are all correct, then click Next.

Finally, ensure you have checked Open the Edit Claim Rules dialog for this relying party trust when the wizard closes, and Close the wizard.

Mapping the attributes

We now need to map the users' attributes, so ADFS knows what data is required by Deskpro, and what type of information it is. If you checked the box in the previous window, you should now see the Edit Claim Rules window. We now need to Add Rule... to map the attributes.

For the Claim rule template, select Send LDAP Attributes as Claims

Enter a Claim rule name so you know what the claim rule is for, then select Active Directory from your Attribute store list.

As a minimum, Deskpro requires the following attributes mapping:

Additional fields can be added and mapped to custom user fields if required.

Testing your ADFS integration

It should now be time to test your integration to confirm everything is working correctly. To do so, click the Test Settings button at the bottom of your SAML Authentication window in Deskpro.

This will open a Popup window showing your ADFS login. From there, sign in with a valid user, and you should receive a report whether your login was successful or failed.

If successful, you can now activate your integration by checking the Enabled field and saving.