Enterprise Single Sign-On with SAML and JWT

Mojo Helpdesk supports both Secure Assertion Markup Language (SAML) and JSON Web Tokens (JWT) for Enterprise Single Sign-On (SSO). These mechanisms allow users to authenticate using their organization’s identity provider, enabling a seamless and secure login experience with one set of credentials.

Supported identity providers include Active Directory, LDAP, Google, Office 365, and any SAML/JWT-compliant provider.

Once SSO is switched on and verified, you choose who has to use it (Who has to use it):

  • Everyone who signs in to this help desk: single sign-on becomes the only login method.
  • Help desk staff only: agents and above must sign in with single sign-on. Contacts keep the other sign-in methods you have enabled (password, Google or Microsoft), so customers outside your directory can still see their tickets. Admins keep a password fallback in case the identity provider is misconfigured. The login page shows a Sign in with single sign on button above the other methods.

SSO can be configured in Account Administration > Account > Security

The account Security page, with the Enterprise single sign on section outlined and its SAML and JWT options shown.

Turning SSO on

  1. Switch on Enable enterprise single sign on.
  2. Choose SAML or JWT and fill in its fields (see below).
  3. Click how to verify? and follow the steps in an incognito window. The method is marked verified after a successful sign-in.

While the switch is off, SAML and JWT sign-in are refused with the message "Single sign on is turned off for this helpdesk." The SAML metadata stays available while the switch is off, so you can set up your identity provider first.

Configuring SAML

SAML needs to be configured both in Mojo Helpdesk and in the Identity Provider (IdP).

On the Mojo Helpdesk's side, admins must specify two fields:

  • Remote Login URL - This is the URL to where the user will be redirected to when trying to login into Mojo Helpdesk. This URL should be the SAML entry point of the Identity Provider.
  • Certificate Fingerprint - This is the SHA1 fingerprint of the SAML certificate from your SAML server. Refer to this article for support on finding the SHA1 fingerprint.

On the Identity Provider side, admins have to specify the following fields:

  • Access Consumer Service (ACS) URL (Reply URL) - https://your-helpdesk-domain/saml/consume
  • Entity ID - your-helpdesk-domain (without the 'https')
  • Name ID* (if applicable) - should be selected to be the user's email address.

Below are the user attributes recognized by Mojo Helpdesk:

  • email
  • first_name
  • last_name

Configuring JWT

Mojo Helpdesk also supports authentication using JSON Web Tokens (JWT). JWT authentication requires configuration both in Mojo Helpdesk and on the Identity Provider. On the IdP side, custom code must be implemented to handle login requests from Mojo, authenticate the user, generate a token with user data, and return the token to Mojo.

Two fields must be configured in Mojo for JWT.

  • Remote Login URL – The URL where users are redirected when attempting to log in to Mojo Helpdesk. This should be the integration entry point of the Identity Provider.
  • Shared Secret – A string used to encode and decode the JWT token. The same secret must be configured on both Mojo Helpdesk and the Identity Provider.

The Identity Provider needs to be configured as follows:

  • The URL to which to send the generated token - https://your-helpdesk-domain/jwt/consume?token=XXX (XXX is the generated token)
  • Include the following attributes in the JWT payload:
    • iat - required. The time the token was generated, expressed as the number of seconds since UNIX epoch. This ensures tokens are used shortly after generation. Mojo treats tokens as expired if they are more than 2 minutes old. Time synchronization services such as NTP should be enabled on servers.
    • email - required. Email of the user being signed in, used to uniquely identify the user in Mojo.
    • first_name - optional
    • last_name - optional