Categories

Categories

Enable single sign-on (SSO) with JWT

 
Ivan Penchev
Last Updated: 2 months ago

Single sign-on (SSO) with JWT is currently available with our Enterprise plan only.

Requirements for enabling JWT SSO

You will most probably need somebody from your development team to help you set this up. To set JWT SSO up you will be required to provide a remote login URL where your users will be redirected and prompted to log in whenever they try to access your help center.

How single sign-on with JWT works?

An optional is the remote logout URL where we will send your users whenever they want to logout of your help center.

All traffic between HelpCenter.io and your system should be over HTTPS and not HTTP so please also confirm that with your dev team.

Enabling JWT SSO

You will have to contact us to enable JWT SSO for your account.

After you have it enabled, JWT SSO for your account you have to go through the process of configuring it.

To configure JWT-based SSO for your help center, first, make sure that it is with a visibility "Private". If your help center is private, navigate to the "Settings" page in your dashboard if you are not there already, find the Security widget and enable the "Enable JWT SSO" toggle (it should be green). This would make another form appear with the JWT settings for your help center.

The JWT configuration form consists of 3 fields - login URL, shared secret, and logout URL. The login URL and the shared secret are required while the logout URL is optional and you need to fill it in if you'd like to allow authenticated users of your help center to also be able to logout from your system via the "Logout" button in HelpCenter.io.

Login URL is the place in your system where we are going to send (redirect) non-authenticated help center visitors. The login URL in your system should handle the authentication of your user via email and password for example or by some other means and then generate a JWT with the required payload information and redirect the user back to your help center at /sso/jwt?jwt={jwt-payload}. You will use the shared secret from the next field to sign the payload via the HS256 algorithm.

The shared secret could be either automatically generated by clicking on the "Generate" button or you could bring your own shared secret key and simply place it into the shared secret input field.

If you'd like to provide a logout URL where your users will be sent after they log out of HelpCenter.io, you can do so in the last input of the JWT configuration form.

When you are done configuring the JWT, simply click on the "Apply JWT Settings" button and you are ready to continue with the implementation in your system.

JWT SSO is available for viewers, for editors, or for everybody trying to access your help center. You will have to provide a user role with the JWT whenever you send an authenticated user to your help center. Read below to find what kind of information you need to provide us with the JWT payload.

Implementing JWT SSO in your system

In your system, you will have to implement a special URL (the login URL you've placed in the JWT configuration) to handle all redirects from your help center, make sure the user is authenticated, generate JWT with at least the required fields of the payload listed below and send your user back to your help center at the /sso/jwt URL with the encrypted JWT payload available in the jwt query param. So the URL where you should send your authenticated users back would look like this:

https://help.mycompany.com/sso/jwt?jwt={jwt-payload}

The JWT payload you generate supports the following attributes:

  • iss - the issuer of the token, usually you would place your domain name here; used for security purposes;

  • iat - issued at - this is the timestamp when your JWT has been issued;

  • jti - unique id of the token, it would be provided as a key parameter in the login URL; used to prevent token replay attacks;

  • email - the email of the user that is being authenticated;

  • name - the name of the user;

  • external_id - if the user has some other identifier in your system and the email is subject to change, you can provide some other means of identification;

  • lang - default language of your user;

  • avatar_url - an image URL to use as an avatar of your authenticated user;

  • role - one of viewer, editor, admin. If no role is specified, viewer will be used by default;

All of the bolded fields (iss, iat, jti, email, name) are required so make sure you include them with your token.

After you have the payload, you need to encrypt it using the HS256 algorithm and the shared secret that we talked about and you are ready to send back the user to your help center to also get authenticated there. Just do a redirect to the abovementioned URL where you will substitute help.mycompany.com with the address of your help center and {jwt-payload} with the actual JWT that you've just generated.

From there on, if everything is alright with JWT, the /sso/jwt route will automatically handle the authentication of your user with the help center.

The supported encryption algorithm by helpcenter.io for the JWT is HS256.

Your technical implementation will depend on the programming language your system is written in but there are JWT libraries available for all major languages and frameworks so you don't need to worry much about the actual token generation. Here's an example code snippet for PHP with Firebase's JWT library:

 

Was this article helpful?