Agent SSO via JWT Setup Details

Last Updated -

See also: 

Setting up Agent SSO via JWT

  1. First, make sure you’re subscribed to the Business Plan.
  2. You will find the SSO via JWT configuration screen under Admin > Settings > Single Sign On as displayed in (Figure 1):
Figure 1: Single Sign On, Authentication Options
 
  1. Select the option JWT SSO. This will expand this area for configuration (Figure 2):
 ​Figure 2: JWT SSO Configuration
 
 
  1. Enter your Authentication Service Name, the Remote login URL and the Remote logout URL for your identity provider.
  2. It is recommended to “Also allow Desk Authentication” when you’re first getting configured so that if you misconfigured, you won’t lock yourself out. Once you’re comfortable with your integration, you may want to disable this option to further enhance security.
  3. Click “Save”
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
 

Agent Authentication Experience

Once you’ve configured JWT 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).


Presentation of JSON Web Token for Authentication

There are three required attributes that your identity provider will present in the JWT payload for agent authentication at Desk. The JWT payload is delivered via HTTP POST to the /auth/jwt endpoint.

Attribute Required? Description
exp Yes The Expiration Time Claim represents the expiration time on or after which the JWT will not be accepted for processing. Its value must be a number containing a NumericDate value (defined below). Desk.com uses a 30 second expiry window that starts when the token is presented for authentication.
aud Yes The Audience Claim is your Desk.com site name, most often represented as a subdomain of desk.com. For instance, if your site lived at “yourcompany.desk.com”, the aud claim would be “yourcompany”. If your site uses custom CNAMEs, you will still need to pass the original desk.com subdomain value as the audience claim.
email Yes The Agent’s email address.

 

NumericDate

A JSON numeric value representing the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date/time, ignoring leap seconds. This is equivalent to the IEEE Std 1003.1, 2013 Edition [POSIX.1] definition "Seconds Since the Epoch", in which each day is accounted for by exactly 86400 seconds, other than that non-integer values can be represented. See RFC 3339 [RFC3339] for details regarding date/times in general and UTC in particular.
 

return_to parameter

When Desk redirects an Agent to your identity provider for authentication, it will include a named attribute “return_to” with a URL value in the redirection query parameters. Enable your identity provider to pass the “return_to” named parameter back to the /auth/jwt endpoint when the token is POSTed for authentication.

If your “Remote login URL” is “https://alohaadventures.desk.com/auth/login” the agent will be redirected to the login URL with the return_to parameter appended to the login URL, for example: https://alohaadventures.desk.com/auth/login?return_to=https://alohaadventures.desk.com/web/agent


Sample JWT Payload

The following code is a ruby programming language example using the JWT gem. Given is the secret from the JWT SSO settings in the Desk Admin panel at /admin/settings/security and the example Desk site’s name of “yourcompany”.


The payload is then POSTed back to /auth/jwt as in this form based example:
 


Related Articles