Setting up Single Sign-On (SSO)

With the help of Single Sign-On your users can authenticate to your systems and get logged in to your Helprace portal automatically.

Single Sign-On can be used in conjunction with other authentications mechanisms, such as social authentication (via Facebook, Twitter, and Google) and native Helprace login.

Helprace Single Sign-On is based on JWT (JSON Web Token).

 

JWT code examples

JWT implementation is straight forward and there are plenty of libraries for any stack. We provide code examples here:

https://github.com/Helprace/helprace-jwt-sso-examples

If you implement JWT in any other stack, we would be happy to feature it there as well. Please comment on this article to let us know what you have implemented.

The Single Sign-On authentication process

Once you enable Single Sign-On, a new button with a lock icon appears on the login screen.

If you disable the native Helprace login, social login options and anonymous access (found on Settings > SECURITY > Authentication page), users will be redirected to the SSO remote login URL and logged in immediately when they come to your Helprace portal.

When users clicks this button, they are routed to a remote login URL, which is a login page in your system (external to your Helprace portal).

Here are the Single Sign-On (SSO) authentication process instructions (when SSO is the only authentication option):

  1. An unauthenticated user navigates to your Helprace portal page (e.g. https://mycompany.helprace.com).
  2. The user is redirected to the Single Sign-On script in your system.
  3. A script on your side authenticates the customer using your proprietary login process.
  4. Your script builds a JWT request that contains the relevant user data.
  5. You redirect the customer to the Helprace endpoint at https://auth.helprace.com/jwt/mycompany?jwt= with the JWT payload.
  6. Helprace decodes the user details 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 Helprace and your systems, so you can keep your authentication scripts safely behind your corporate firewall.

Configuring your JWT implementation

To perform SSO for a user, you need to send several required attributes to Helprace as a base64-encoded hash. In addition to the required attributes you can specify additional user details. These details will be updated in the Helprace user profile.

Specify HS256 as the encryption algorithm in the header of your JWT payload (it is often used by default).

{
  "typ":"JWT",
  "alg":"HS256"
}

Redirect the user with the JWT payload to the following Helprace endpoint:

https://auth.helprace.com/jwt/acme?jwt={payload}

Note to use the 'https' protocol and replace 'acme' with your Helprace subdomain (domain alias is not allowed here).

Here is the list of supported attributes.

Attribute Required Description
jti ✔ JSON Web Token ID. A unique token ID. Used to prevent token replay attacks.
iat ✔ Issued At. Identifies the time at which the token was issued. Used to determine the age of the JWT to ensure that a given token used shortly after it's been issued. This value must be a number of seconds passed since the beginning of the UNIX epoch. Helprace allows up to two minutes clock skew, so make sure to configure NNTP or similar on your servers.
email ✔ Email of the user being signed in. Could be any email assigned to the user, primary or not. Used to uniquely identify user in Helprace.
external_id   If user email is a subject to change and your users are uniquely identified by a different ID, send it as the external ID. external_id must be unique for each user.
name   Full name of the user.
organization   The name of the user's organization. 
organization_url   The user's organization URL.
job_title   User's job title.
avatar   URL of the user's profile photo. Must be accessible from the internet.
role   The user's role. Can be one of the following: "user", "agent", "admin", "owner". Default is "user". If the user's role is different than it is in your Helprace account, the role is changed in your Helprace account.

If a user's email has been changed and they log in via SSO with the same external_id, the new email will be added to the user's account. The previous email will also be preserved.

Enabling JWT Single Sign-On in your Helprace

In order to start using JWT Single Sign-On you need to enable it in your Helprace admin panel.

  1. Go the Settings > SECURITY > Authentication page.
  2. Check the "Single Sign-On (SSO)" option.
  3. Enter the Remote Login URL. This is where your user will be redirected when they attempt to login to your Helprace via SSO.
  4. Enter the Remote Logout URL. This is where Helprace will return your users to after they log out.
  5. Copy the Key to your SSO script.

The return_to URL for login

Typically, users would expect to return to a page they were on previously while logged in via Single Sign-On. There are two possible cases to this depending on where they start the session:

User lands on a Helprace portal page

In this case users are redirected to your Single Sign-On script (set in Remote Login URL) and then back to Helprace. Helprace returns users to the page they were on before logging in. This happens automatically and doesn't require any setup on your part. If a user creates a knowledge base article and clicks "publish" while being unauthenticated, the post will be published immediately after the user gets back on Helprace after successful SSO authentication.

User lands on a page of your website or application

You can authenticate a user through redirecting them to Helprace and back to your app. Another options is to make use of so-called "Silent Authentication" by passing the URL with JWT payload to the src parameter of <iframe> or <img> tag and thus authenticating the user on the background.

Redirection

Your SSO script redirects users to your Helprace portal with JWT payload and return_to URL, which is normally the page within your website/application that users were on before they have been redirected to Helprace. Helprace will redirect users to the return_to URL after successful authentication.

This can be enabled by adding return_to GET parameter to the URL with the JWT payload:

https://auth.helprace.com/jwt/acme?jwt={payload}&return_to=https://acme.com/page-to-show-after-login

Where "https://acme.com/page-to-show-after-login" is the URL you would like to return the user to.

Silent authentication

Iframe

Display a 1×1px <iframe> on your SSO script page. Use the same URL with payload in "src" parameter of the image. There is no need to provide return_to in this case.

<iframe src="https://auth.helprace.com/jwt/acme?jwt={payload}" width="1" height="1" style="border: none;"></iframe>

Pixel

Display a 1×1px <image> on your SSO script page. Use the same URL with payload in "src" parameter of the image. There is no need to provide return_to in this case.

<img src="https://auth.helprace.com/jwt/acme?jwt={payload}" width="1" height="1" />

Authentication via an image is supported in Firefox, Safari and Chrome browsers, but not supported in IE and EDGE.

The return_to URL for logout

Just like with the login option, users would expect to land on the same page they were on before logging out. It might also be a specific page set by you. There are four possible cases to this depending on where user logs out first and if the Remote Logout URL setting is present:

User clicks Logout while being on a Helprace portal page

If Remote Logout URL is set

The user will be redirected to that URL after logging out from Helprace. It will also send a return_to parameter with the URL of the page the user were on before they clicked Logout:

https://acme.com/logout?return_to=https://acme.helprace.com/i4-some-kb-article-for-example

This allows you to configure your website or application to redirect the user back to that Helprace page.

If Remote Logout URL is NOT set

The user will be logged out from Helprace and stay on the Helprace page he were on before clicking Logout. 

User clicks Logout in your website or application

To log user out from Helprace as well, your website or application needs to redirect the user to the Helprace logout page:

https://acme.helprace.com/auth/logout

You can tell Helprace to redirect user back to your site or application after it logs him out. For that you need to pass return_to URL to Helprace:

https://acme.helprace.com/auth/logout?return_to=https://acme.com/page-to-show-after-login

What happens next depends on the Remote Logout URL setting.

If Remote Logout URL is set

After logging the user out, Helprace will redirect the user to the Remote Logout URL and pass your return_to URL as a parameter. E.g.:

https://acme.com/logout?return_to=https://acme.com/page-to-show-after-login

Your website or application needs to redirect the user to the return_to URL that it receives from Helprace.

If Remote Logout URL is NOT set

After logging the user out, Helprace will redirect the user to the return_to URL. E.g.:

https://acme.com/some_page

SSO log and troubleshooting

SSO requests and server responses are displayed on the Settings > LOGS > Single Sign-On (SSO) Log page

Preventing repetitive authorization requests

When implementing SSO on your end, please make sure to prevent unnecessary repetitive authorization requests to Helprace.

For example, when you redirect user with JWT payload to Helprace and they are successfully authenticated, you should keep a record of this in your app. Check that record next time before sending user to Helprace for authentication. If the record says that the user is already logged in, do not redirect them to Helprace.

This record should be reset when user navigates to the Remote Logout URL page.

Authentication settings

You can find multiple authentication options on the Settings > SECURITY > Authentication page. Different combinations of these settings allow you to create your own custom login setup.

SSO for all agents and users

Disable all options, with the exception of "Single Sign-On (SSO)". When an unauthenticated user or agent opens your Helprace page they will be immediately logged in via SSO.

By leaving "Anonymous Access" turned on, users and agents would need to click the Login button to authenticate. However, they can browse the user portal anonymously without logging in.

SSO for customers and native Helprace logins for agents

Same settings as with the previous scenario. Agents can login via direct login URL with their native Helprace username and password.

http://account.helprace.com/backup-login

"account" must be replaced with your account name.

SSO for agents and native Helprace login or social authentication for users

Turn on "Single Sign-On (SSO)" option and at least one of the following two options: "Helprace Login", "Social authentication".

"Anonymous Access" could be turned on or off according to your preferences.

Your customers can login using their Helprace passwords or via social login.

Manual user control

Disable "Allow new users registration", "Social Authentication" and "Single Sign-On (SSO)" options. Invite or import users with desired permissions manually from the admin panel "People" page.

You may want to disable "Anonymous Access" which blocks your user portal to users you didn't invite beforehand.

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

2 replies

Newest Oldest
M

I'm getting 403 error:

403 Forbidden/Provided email is already assigned to another user. Multiple users must not share the same email address.

Please help!

Comment

This could happen if you assign different external_id when the same user with the same email logs in. For example, when user logs in via SSO the first time, you sent these details to Helprace:

"email" => "user@example.com",
"external_id" => "1"

If this user logs in via SSO once again and you send the same email address, but a different external_id, there would be an error:

"email" => "user@example.com",
"external_id" => "2"

By providing a different external_id you're telling Helprace that it is a different user. On the other hand two users cannot share the same email address within your account. Thus you're getting the error.

Please note that external_id is not required by Helprace. Normally Helprace uses email as a unique user ID. You may only need to provide external_id, if you're using a different unique user identifier in your system. Btw, external_id may be any string, it doesn't have to be a number.

To sum up, you can solve this in one of the two ways:

  • If you do not need the external_id, you can simply remove it from your SSO script and the problem will be solved.
  • If you need external_id for user identification in your system, you have to provide the same external_id each time the same user logs in (but different external_id for a different user).

Is there any way to NOT rewrite user data?

For example user login first time with SSO and change his avatar or other information. We want to keep his data and not rewrite it.

Also want to notice that integration was very easy, thank you.

May be it is good idea to add information that jti can be just uuid or something random, cause it not so obvious if using other language than php.

Comment

Mostly it affect agents, cause it rewrite their "job_title" by ingame one.

I use this field to show rank of our customer, to quickly understand knowledge of our app. But it must not affect agents, or people who change something manually, i think.

If you do not wish to rewrite an optional attribute, such as "job_title", do not include it in your SSO payload. For instance, if you wish to prevent rewriting the "job_title" for agents, you just need to check the user role in your SSO script and omit the "job_title" attribute if user_role="agent".

Reply