TOPdesk SAML application setup
Introduction
This manual shows how to setup SSO to TOPdesk using the SAML protocol. The configuration takes place in HelloID and in the TOPdesk admin center.
Requirements:
HelloID environment
TOPdesk online environment (on-premises version 6 or above is also possible)
Create or Import a Certificate
If there is no certificate yet, a certificate must be imported or created. This can be done in the HelloID Administrator Portal under Settings > Certificates. For this tutorial, we will use a self-signed certificate. Learn more about certificates here.
Application Setup
Add the TOPdesk Application
Create a new application in HelloID by navigating to Applications > Applications. Open the Application Catalog and search for "TOPdesk". Find the SAML template, and click Add. Learn more about managing applications here.
General tab
On the General tab, fill the default login URL with the TOPdesk environment URL. Optionally, you may also add a description. Click Next.
Single Sign-on tab
On the Single Sign-On tab, perform the following steps:
Provide a value in the Name ID format field. We recommend putting "username" in this field.
For the Issuer field, provide your HelloID environment URL.
Note: https://tools4ever.helloid.com will not work! This is just an example.
Make sure to change this from the default to your customer specific HelloID environment.
For the E ndpoint URL fill in the full TOPdesk environment URL followed by "/tas/secure/login/verify" for the operator login or "/tas/public/login/verify" for the Self-Service login.
Note: https://tools4ever.topdesk.net will not work! This is just an example.
Make sure to change this from the default to your customer specific TOPdesk environment.
Select or deselect the Sign Assertion, depending on the TOPdesk environment settings.
By default TOPdesk requires a signed assertion, so the default and recommended setting is having this selected.
Note: Chances are the configuration won't work when this is deselected.
Select or deselect the Sign Response, depending on the TOPdesk environment settings. The default and recommended setting is having this deselected.
Note: Chances are the configuration won't work when this is selected.
Select or deselect the Use DS Prefix, depending on the TOPdesk environment settings. The default and recommended setting is having this deselected.
Note: Chances are the configuration won't work when this is selected.
Select or deselect the Exclude Audience Restriction, depending on the TOPdesk environment settings. The default and recommended setting is having this selected.
Note: Chances are the configuration won't work when this is deselected.
In the X509 Certificate dropdown, select the certificate that you created or imported previously.
Click Next.
Credential tab
On the Credential tab, select the NameID to send in the SAML assertion to TOPdesk.
The value of this has to match the TAS login name (username) in TOPdesk. Click Next.
Self service tab
On the Self Service tab, choose whether to automatically create a Self Service product, which makes the application requestable. This is optional. Click Next.
On the Finish tab, click Save to add the application to HelloID.
Application metadata
After saving the TOPdesk application, click its Edit link on the applications overview. This will bring you to its properties page.
You now have two options to obtain the application metadata.
Static metadata (download)
You can simply click Download metadata at the right top of the screen and save the file to your local computer for later use in TOPdesk. By uploading this file, the data will be static in TOPdesk. To have TOPdesk dynamically read the data continuously please follow the option below.
Dynamic Metadata (URL)
You can copy the link address (something along the lines of https://enyoi.helloid.com/metadata/download?ApplicationGUID=e6e741f5-a469-4849-93f7-fe2e259a339f) and replace 'download' with 'index' to view the metadata.
The configuration of the HelloID application is finished.
TOPdesk Configuration
In order to make the connection, we need to set up the configuration in TOPdesk aswell. Go to the TOPdesk portal as an administrator and click the Menu tile and click Settings .
Select the Functional Settings > Login Settings > General. Depending if you wish set up SSO for the public or operator login, click Add configuration at the Public or Secure section.
In the SAML configuration assistant, perform the following steps:
Depending on your choice regarding the applcation metadat, provide the metadata in one of two ways. Either Upload as file or Link via URL.
At Entity ID select the HelloID environment URL (this will match the issuer you specified at the HelloID setup).
For user name attribute fill in 'username'
As Logout URL use the full URL of your HelloID environment followed by '/authentication/signoff'
Make sure to select Host TOPdesk metadata
Deselect Assertions will be encrypted
For the Certificate and Private Key you can either upload a private key and certificate you own. But you can also select Generate key pair, this is recommended since this makes it a lot easier.
The Display name is customizable at any time and can be completely custom. Recommended is something like 'Login with HelloID'
Optionally, add Aliases, when entering the same as the TOPdesk endpoint, users will be immediately directed to the HelloID login, instead of having to click the button 'Login with HelloID'.
Click Save and the TOPdesk SAML configuration is finished.
Do not forget to enable the SAML Single Sign On for the section (Operator or Self-Service) you have configured.
