Configuring JWT settings for single sign-on (SSO)

For partners subscribed to Enterprise plans.

This article will show you how to achieve SSO with JWT (JSON Web Tokens). Once this is done, user sign-in requests are routed to a login page that is external to IT Glue.

For those who prefer a SAML SSO process, IT Glue also provides this capability (see the SAML article).

How it works

Here are the authentication process steps through a JWT based SSO service:

  1. An unauthenticated user navigates to your subdomain (mycompany.itglue.com).
  2. IT Glue recognizes that JWT is configured and that the user is not authenticated.
  3. The user is redirected to the remote login URL configured for the SSO settings, for example, https://mycompany.com/itglue/sso.
  4. A script on your side authenticates the user using your proprietary sign-in process.
  5. Your script builds a JWT request that contains the relevant user data.
  6. You redirect the customer to the IT Glue endpoint at https://mycompany.itglue.com/access/jwt with the JWT payload.
  7. IT Glue parses the user detail from the JWT payload and then grants the user a session.

As you can see, this process relies on browser redirects and passing signed messages using JWT. The redirects happen entirely in the browser and there is no direct connection between IT Glue and your systems, so you can keep your authentication scripts safely behind your corporate firewall. 

Prerequisites

  • Administrator level access to IT Glue.
  • A hosted or custom SSO solution that supports JWT.
  • All of your users under your account in IT Glue will need an account in your JWT application, with exactly the same email. We don’t create user accounts under SSO.
  • Make sure each and every user has SSO credentials because once SSO is configured, they will not be able to use their IT Glue credentials to sign in to your subdomain (mycompany.itglue.com).

     Before creating your own JWT solution:

  • This an advanced feature that should only be implemented by those with access to development resources.
  • Your application must construct the JWT payload and sign it using your IT Glue API secret key ("SSO Key"). The SSO Key can be found in IT Glue in the Account area.

Instructions

Building the JWT payload

To perform SSO for a user, you need to send several required user attributes to IT Glue as a base64-encoded hash (hash table, dictionary). This requires an email address to uniquely identify the user. Other attributes verify the tokens authenticity.

Required attributes:

  iat

Issued At Time. All issued tokens are used immediately after issuance. This time must be within a small margin the same as IT Glue’s server time. The value is the number of seconds elapsed since UNIX epoch.

  jti

JSON Web Token ID. The JTI is constructed using the IAT and a unique token identifier that prevents replay attacks.

  email

This is how users in the partner application are matched with IT Glue. 

  {typ, alg}

A header to identify the standard and algorithm for encryption. 

Example JWT payload:

[
     {"iat" => 12345678901,
      "Jti" => "12345678901/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "Email" => "someone@example.com"},
     {"typ" => "JWT", "alg" => "HS256"}
]

 

The JWT payload must be sent to your IT Glue subdomain using the https protocol. Example:

  https://mycompany.itglue.com/access/jwt?jwt={payload} 

Redirecting the user to a specific page

When IT Glue redirects a user to your login script, it will also pass a return_to parameter in the URL. This parameter contains the page that IT Glue will return the user to after the authentication succeeds. For example:

  1. A user visits https://mycompany.itglue.com/1/configurations/12345.
  2. IT Glue recognizes that the user is not authenticated.
  3. IT Glue redirects the user to:
    https://mycompany.com/itglue/sso?return_to=https://mycompany.itglue.com/1/configurations/12345

Example integration:

# Using JWT from Ruby is straightforward. The below
  # example expects you to have `jwt` in your Gemfile, 
  # you can read more about that gem at
  # https://github.com/progrium/ruby-jwt
  require 'securerandom' unless defined?(SecureRandom)

  class ItglueSessionController < ApplicationController
    # Configuration
    ITGLUE_SHARED_SECRET = ENV["ITGLUE_SHARED_SECRET"]
    ITGLUE_SUBDOMAIN = "youraccount"

    def create user_signed_in? ? sign_into_itglue(current_user) :   
      redirect_to(new_user_session_path(return_to: params[:return_to]))
    end

    private

    def sign_into_itglue(user)
      iat = Time.now.to_i
      jti = "#{iat}/#{SecureRandom.hex(18)}"

      payload = JWT.encode({
        # Seconds since epoch, determine when this token is stale
        :iat => iat,
        # Unique token id, helps prevent replay attacks 
        :jti => jti,
        :email => user.email
      }, ITGLUE_SHARED_SECRET)

      redirect_to itglue_sso_url(payload)
    end

    def itglue_sso_url(payload)
      url = "http://#{ITGLUE_SUBDOMAIN}.itglue.com/access/jwt?jwt=#{payload}"
      url << "&return_to=#{URI.encode(params[:return_to], URI::PATTERN::RESERVED)}" if params[:return_to].present?
      url
    end
  end

This is a scrollable box.

Important. It's highly recommended that before you begin these next instructions, you sign in to your IT Glue account twice - once in a regular browser window and once in a incognito/private window (or just sign in to two separate browsers). That way, if something doesn't work and you get locked out of your account in one window, you are still signed in to your account in the other window.

Configuring single sign-on

  1. From Account > Settings, click the Authentication tab.
  2. Use the on/off button to turn on JWT SSO.
  3. Enter the appropriate values in the fields provided.
  4. Click Generate to create the SSO key. This automatically saves the key to your account.
    Warning. You’ll want to generate the SSO key from IT Glue, save it to a safe place, then work on the integration before saving the Account > Settings page with JWT SSO enabled. If you turn on SSO prematurely, it will break the sign-in experience for all users on your account.
  5. Click Save.

Once you make this change, users will be required to sign in with SSO when visiting your account subdomain (mycompany.itglue.com) if they're not already authenticated. 

Screenshot: JWT SSO fields under Account > Settings

Configuring_JWT_SSO.png

Common Questions

When the SSO server is unavailable, how do we access our accounts?

If the SSO server you specified is unavailable for any reason while you're trying to sign in, authentication will fail. Send us an email for assistance.

How do we disable SSO for a user?

If a member has left your team, and you’d like to disable their user account, an Admin or Manager will need to delete their account from the Account > Users page in IT Glue. We don't currently support disabling user accounts through the SSO server.

Was this article helpful?
0 out of 0 found this helpful