What is Multipass?

Multipass authentication is a single sign on authentication strategy to allow you to share your user authentication with your Desk.com site. This allows a seamless experience for your users without forcing them to create a separate account on your Desk.com site.

How does it work?

In order to authenticate your users on your Desk.com portal, you pass an encrypted multipass JSON hash with the user's information to your Desk.com site. When the multipass token is received, an associated customer record on your Desk.com site is created or updated and logged in with the information you provided.

What's in a Multipass?

A multipass hash is an AES encrypted JSON hash with the following attributes:

Key Required? Value
uid Yes Unique string of the user. This is the unique identifier of the user in your system, such as their guid or auto incremented id.
expires Yes Multipass expiration date in ISO 8601 format. This is for security purposes to expire the hash after a given period of time.
to No Absolute URL to redirect the user after successful login. If this is not supplied, users are either redirected to the original page they were viewing/attempting to view on your portal, or they are redirected to your portal's home.
customer_email Yes Customer's email address
customer_name Yes Customer's name
customer_custom_key No The custom customer field identified by key

Using Multipass

Enable It

  • Log in to the Desk.com Administrator and go to “Support Center” on the “Channels” tab.
  • Select “Private Access” and select “Multipass” from “Authentication Method”
  • Click “Update”

Setting a remote Login URL

Once Multipass is enabled, you'll need to set a remote login url in your advanced settings to send users to your application's login page. An example login url on your application would be “http://yoursite.com/login”. Once that login URL is set, all users on your Desk.com portal that need to be authenticated due to requiring authentication will be redirected to that location. Your application should then verify the users credentials, build the Multipass hash for that user, and sign them in on your Desk.com portal.

Setting a remote Logout URL (Optional)

If you would like your users to additionally be logged out of your site when they log out of your Desk.com portal, you can choose to set a Logout URL. An example logout url for your site would be “http://yoursite.com/multipass/logout”. Once that logout URL is set, all users on your Desk.com portal will be redirected to that URL to let you log out the user from your system. Once you log the user out, you could choose to redirect them back to your Desk.com portal for a seamless experience.

Requiring Authentication

You can choose when to require that a user needs to be logged in. If you would like guests to have access to everything, leave the setting at the default (Nothing). If you would like to require login for posting a question, sending an email, or starting a chat, choose “Interactions.” To require login to access anything on your portal, select “Everything.” When requiring authentication, users will be redirected to your remote login url if they are not signed in on your Desk.com portal.

Building the Multipass token

When your users are sent to your application by visiting your Multipass Login URL, you will need to verify them by logging them in on your application, build their Multipass hash, and redirect them back to your Desk.com portal with the following steps:

  • Choose your expiration date, such as a few minutes from now.
  • Build your JSON hash
1
2
3
4
5
6
7
{
  "uid": "19238333",
  "expires": "2011-12-29T10:25:28-08:00",
  "customer_email": "john@example.com",
  "customer_name": "John",
  "customer_custom_level": "vip"
}
  • Encrypt the hash using AES128-cbc encryption with your site key as the password and your api key as the salt. Use a block size of 16 bytes and make sure to pad the hash using this block size. You can see this in detail on our PHP code example
  • Base64 encode the result
  • Convert to a URL safe string by performing the following
    • Remove any newlines
    • Remove trailing equal (=) characters
    • Change any plus (+) characters to dashes (-)
    • Change any slashes (/) characters to underscores (_)

Signing the Multipass token

In order for us to ensure that the multipass token we receive is indeed coming from you and the data has not been tampered with, you will need to pass us an HMAC-SHA1 signature of your multipass token using your multipass api key. To build this signature, perform the following:

  • Build a SHA1 HMAC using your multipass api key and your finished multipass token.
  • Base64 encode the resulting HMAC.

Performing the Single Sign On

Send the user to the multipass callback url with their url encoded multipass token and HMAC signature:

1
http://yoursite.desk.com/customer/authentication/multipass/callback?multipass=MULTIPASS&signature=SIGNATURE

Portal Templates

Updating Portal Templates

NOTE: Your portal templates may already contain the necessary code. The following examples are guidelines to use if you have an older template that needs to be updated.

To expose your remote login link and display your currently logged in user, you will need to add code similar to the following in the layout section of your Portal template.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{% if site.portal_authentication_enabled_config %}
  <div id='customer-account'>
    {% if current_user and current_user.is_guest == false %}
      <span>
        Welcome, {{ current_user.customer.name }}
      </span>
      {% unless site.portal_always_require_authentication_config %}
        <a href='{{ site.authentication_logout_url }}'>Logout</a>
      {% endunless %}
    {% else %}
      <span>
        Welcome, Guest
      </span>
      <a href='{{ site.authentication_login_url }}'>Login</a>
    {% endif %}
  </div>
{% endif %}

To hide the guest email and name fields when a user is logged in, wrap them with a conditional like the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{% if current_user.is_guest %}
  <div class='input-block'>
    <span class='label'>
      Your name <span>(required)</span>
    </span>
    <div>
      <input value='{{ interaction.name }}' id='interaction_name' maxlength='100' name='interaction[name]' type='text' />
    </div>
  </div>
  <div class='input-block'>
    <span class='label'>
      Your email address <span>(required)</span>
    </span>
    <div>
      <input value='{{ interaction.email }}' id='interaction_email' maxlength='100' name='interaction[email]' type='text' />
    </div>
  </div>
{% endif %}