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).
How it works
Here are the authentication process steps through a JWT based SSO service:
- An unauthenticated user navigates to your subdomain (mycompany.itglue.com).
- IT Glue recognizes that JWT is configured and that the user is not authenticated.
- The user is redirected to the remote login URL configured for the SSO settings, for example, https://mycompany.com/itglue/sso.
- A script on your side authenticates the user using your proprietary login process.
- Your script builds a JWT request that contains the relevant user data.
- You redirect the customer to the IT Glue endpoint at https://mycompany.itglue.com/access/jwt with the JWT payload.
- 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.
- 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 into 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 the Account area.
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.
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.
JSON Web Token ID. The JTI is constructed using the IAT and a unique token identifier that prevents replay attacks.
This is how users in the partner application are matched with IT Glue.
A header to identify the standard and algorithm for encryption.
Example JWT payload:
The JWT payload must be sent to your IT Glue subdomain using the https protocol. Example:
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:
- A user visits https://mycompany.itglue.com/1/configurations/12345.
- IT Glue recognizes that the user is not authenticated.
- IT Glue redirects the user to:
This is a scrollable box.
Configuring single sign-on
- From Account > Settings, click the Authentication tab.
- Use the on/off button to turn on JWT SSO.
- Enter the appropriate values in the fields provided.
- 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 login experience for all users on your account.
- 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.
Screenshot: JWT SSO fields under Account > Settings
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 log in, authentication will fail. Send us an email for assistance.
Alternatively, in the event that SSO is unavailable, you can still login using your IT Glue username and password at app.itglue.com.
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.