Configuring JWT settings for single sign-on (SSO)

For partners subscribed to Basic with SSO 2021, Select with SSO 2021, and Enterprise plans.

This article will show you how to achieve SSO with JWT (JSON Web Tokens). Once this is done, user login 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).

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 login 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 log 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 log in using your IT Glue API secret key ("SSO Key"). The SSO Key can be found in IT Glue in Account.

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.

Configuring single sign-on

  1. Log in to IT Glue and click Account from the top navigation bar.
  2. Click Settings in the sidebar.
    Account_Settings___IT_Glue_copy.png
  3. Click on the Authentication tab and then turn on the Enable JWT SSO toggle switch to ON. Once this is turned on, a form will appear. Enable_JWT_SSO_Details.png
  4. Complete the fields. Click the Generate button to create the SSO key. This automatically saves the key to your account.

    IMPORTANT  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 login experience for all users on your account.
    To  allow users to log in only with their SSO provider, enable Enforce SSO Login option.

  5. Click Save.

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

Common Questions

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

If your SSO provider's service is unavailable, you can still login using your IT Glue username and password at app.itglue.com.

If your SSO is not working, confirm your provider's service is available. Send us an email for assistance.

How do we disable SSO for a user?

To disable a user account, an Administrator or a Manager will need to navigate to the Account > Users page in IT Glue. We don’t currently support disabling user accounts through the SSO server.