Agent SSO via SAML 2.0 Setup Details

Last Updated -

See also: 

Setting up SAML at your Identity Provider

There are many SAML Identity Providers available for Single Sign-On such as Bitium, Okta, or even Salesforce, to name a few. Each has their own admin panels and work flows to configure them as your Identity Provider for Desk agent authentication. That said, there a number of common attributes and values that the identity provider and Desk need to coordinate between each other to facilitate proper use of the SAML protocol. The following is a list of attributes to set and/or record as you configure your identity provider.

These are attributes at the identity provider that are set based on your Desk site.

  • SAML Assertion Consumer Service (ACS) endpoint - Out of the box, your SAML ACS endpoint will be https://yoursite.desk.com/auth/saml/acs. Similarly, if you have a custom CNAME set up, the endpoint would be https://YOURCNAME/auth/saml/acs.
  • Service Provider Entity ID - In the SAML protocol the “Service Provider Entity ID” is your application defined unique identifier that is the intended audience of the SAML assertion being presented to Desk during agent authentication. This setting can be referred to as “Entity Id”, “EntityID”, “Audience URI”, “SP Entity ID”. The value set here is the unique site name of your Desk site. For example if your site is “mysite.desk.com” then your Service Provider Entity ID value would simply be “mysite”. The unique site name is the correct value to use even if your site has its own CNAME.
  • Users mirrored in each system - A user that exists at the identity provider must have a corresponding agent within the Desk site with each having the same email address. The email address is the foreign key that Desk uses to join the authentication subject to an agent.
  • Name ID Format - Username format shared between the identity provider and Desk. Desk uses an email based name format as has been previously described. Identity providers can list Name ID Format values in a number of manners, these are the most common:
    • Unspecified / "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
    • EmailAddress / "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
    • x509SubjectName / "urn:oasis:names:tc:SAML:1.1:nameid-format:x509SubjectName"
    • Persistent / "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
    • Transient / "urn:oasis:names:tc:SAML:2.0:nameid-format:transient"
  • Subject / Username - The SAML assertion returned to Desk has a subject present that represents the user that has been authenticated. The subject needs to be the email address of the agent in the Desk site. Depending how your identity provider is set up this value might be listed as email address, username, or other value. Other subject values your identity provider might present are “Federation ID”, “User ID”, “Custom”, or “Persistent ID”. The subject / username corresponds to the name id format value.
  • Authentication Request Compression - When Desk sends a SAML Authentication Request to the identity provider at the start of the agent login the request is compressed. Some identity providers programmatically detect if the request is compressed and others have this as a setting that is toggled between uncompressed or compressed. If exposed declare that the Desk application's authentication request is given compressed.
These are attributes you will need to record from your Identity Provider when setting up SAML for Desk:
 
  • SHA-1 fingerprint - The SHA-1 fingerprint is the text fingerprint of the identity provider’s X.509 certificate. If the identity provider does not display the fingerprint for their certificate then the X.509 certificate needs to be downloaded as a file or its text is copy and pasted into a file. See “Create a fingerprint for X.509 certificate” in the Appendix.
  • X.509 certificate - “Security certificate”, “signing certificate”, only needed if the SHA-1 fingerprint is not given, see SHA-1 fingerprint above.

Setting up Agent SSO via SAML

  1. First, make sure you’re subscribed to the Business Plan.
  2. You will find the SSO via SAML configuration screen under Admin > Settings > Single Sign On (Figure 1):
Figure 1: Single Sign On, Authentication Options
 
  1. Select the option SAML SSO. This will expand this area for configuration (Figure 2):

Figure 2: SAML SSO Configuration​

Authentication Service Name - In conjunction with “Also allow Desk Authentication” this is the text linked to the identity provider’s login listed at the bottom of the Desk’s native login form. See how the example Authentication Service Name “Aloha Adventures” is displayed in Figure 4 below. 

Remote login URL - The Single Sign-On URL provided by the identity provider.

Remote logout URL (optional) - The logout URL provided by the identity provider. The logout URL is optional. When an agent logs out at Desk their session is terminated with the Desk even if the identity provider does not provide a logout URL on their side.

Certificate fingerprint - The SHA-1 fingerprint of the identity provider’s security certificate (X.509 certificate). The identity provider signs the authentication assertion given to Desk once the agent has logged in at the identity provider. Desk uses the fingerprint to verify that the signed assertion was created by the identity provider. Some identity provider’s display the fingerprint of their X.509 fingerprint to make it easy to copy and paste into your configuration. See “Create a fingerprint for X.509 certificate” in the Appendix if your identity provider only displays the text of the X.509 they use to sign assertions given to Desk.

Also allow Desk Authentication - It is recommended to “Also allow Desk Authentication” during the initial configuration so that if the SAML settings are misconfigured agents won’t be locked out of Desk. Once the integration has been settled, and logins via the SAML identity provider have been proven, the dual authentication types can be disabled. Disabling the dual authentication types improves security and reduces confusion about the login path when login is done seamlessly through the identity provider.

NOTE: If your Desk site has a custom CNAME configuration, you will see an alert (Figure 3) that will ask you to reach out to our support team before proceeding. If you see this message, please send us an email to support@desk.com before continuing.

Figure 3: Custom CNAME Condition
 
  1. Fill out the information and click "Save" to save your configuration.


Agent Authentication Experience

Once you’ve configured SAML SSO, if you checked, “Also allow Desk Authentication”, your login form will have the option “Login with X” where X is your Authentication Service Name. In Figure 4, the Authentication Service Name is “Aloha Adventures.”
 
Figure 4: Login with Authentication Service

Clicking “Login with X” will redirect the user to your specified Authentication Service for authentication. If you disable, “Also allow Desk Authentication”, this login form will automatically redirect the user to your Authentication Service (you will not see the Desk login form).
 

SAML Authentication Request

At the protocol level when you initiate a SAML based login, Desk will send a standard SAML authentication request to your identity provider. The authentication request will include an Issuer attribute with the value of your Desk site name like the example below. When the identity provider accepts the request you will begin the login sequence implemented at the identity provider. The format of the authentication request is automatically generated based on your Desk account, there aren't any configuration options pertaining to it in the security panel.


Appendix


Create a fingerprint for X.509 certificate

If your identity provider doesn’t present a fingerprint for its X.509 certificate you will need to generate the fingerprint on your own. This example is done at the command line using the “openssl” OpenSSL command line tool. This assumes that you have either downloaded the certificate into a file named “cert.txt” or you have created the “cert.txt” file and copied and pasted the certificate text displayed at the identity provider into the “cert.txt” file.

openssl x509 -sha1 -fingerprint -in cert.txt

The fingerprint is in the output of the openssl command. In the example below the hex based numbers delimited by colons is the fingerprint text that we need to copy, e.g. 67:EF:34:FF:82:82:65:E9:A8:19:32:E1:7D:CF:D9:99:5F:42:A1:F5    

openssl x509 -sha1 -fingerprint -in cert.txt
SHA1 Fingerprint=67:EF:34:FF:82:82:65:E9:A8:19:32:E1:7D:CF:D9:99:5F:42:A1:F5
-----BEGIN CERTIFICATE-----
MpDCCAoy...
...
...BN+XXsgs
-----END CERTIFICATE-----