How to setup Single Sign-On (SSO)

SSO allows users to seamlessly login with their existing account provided by your website/app without having to create an additional account on ClearFlask.

There are two ways how your users can log in and it's best to complete both of them for best experience:

#1 Log in by link

(Optional, but, recommended)

Your user visits your website/app and now they want to provide you feedback on ClearFlask.
Your server will generate a JWT using a secret key found here and pass it along to the user.
The user will click a link to ClearFlask with the JWT embedded as a parameter: https://<your_subdomain>.clearflask.com/?token=<jwt_token>
User is seamlessly logged in automatically and can post on ClearFlask

Example: Our own feedback page works the same way, head over to the dashboard and hover over the "Feedback" link in the menu. Notice the link contains a JWT token that will automatically log you in when you click it.

#2 Log in with redirect:

Your user visits ClearFlask directly to provide you with feedback.
When user performs an action that requires an account, a prompt will be shown to log in.
An option to use SSO will be shown upon which a popup will open with your website's log-in page.
After signing in, the popup redirects back to ClearFlask to complete the sign-in and continue with the user action.

Example: Our own feedback page works the same way, if you visit our feedback account page, sign out if you're already signed in and click the account icon at the top right corner. You will be asked to sign-in as an "Existing customer" which will open up a sign-in popup.

Generating JWT Tokens

Depending on your server architecture, a library may already exist for JWTs that can be found here that implements the JWT specification.

The supported claims you should be setting are:

guid (String, required)
email (String, optional)
name (String, optional)

If you do not provide an email, user will not receive notifications. If you do not provide a name, an auto-generated name will be given.

In addition, you should be also setting:

expiry (optional)
issuedAt (optional)

The issuedAt date is important for invalidating all tokens prior to a certain date in some cases.

The JWT should use HS256 with GZIP and DEFLATE.

Java example:

Jwts.builder()
    .setIssuedAt(now)
    .setExpiration(expiration)
    .addClaims(ImmutableMap.of(
            "guid", account.getClearFlaskGuid(),
            "email", account.getEmail(),
            "name", account.getName()))
    .signWith(new SecretKeySpec(
            config.secretKey().getBytes(Charsets.UTF_8),
            SignatureAlgorithm.HS256.getJcaName()))
    .compressWith(new GzipCompressionCodec())
    .compact();

Creating a custom sign-in page for redirect

Either create a custom sign-in page or re-use your existing sign-in page that will detect a callback url from ClearFlask. Type in the sign-in page url in your dashboard. Remember that <return_uri> will be replaced by the callback url.

Once a user opens up the sign-in page, first let them sign-in if they're not already. At this point, your server should have generated a JWT and returned it back to the client.

Once the user is signed in, read and verify the callback url domain is either <your_app>.clearflask.com or a custom domain you have setup with us.

Now you can safely redirect back to the callback url with the jwt appended at the end like so:

<return_uri>?token=<jwt_token>

Need help?

Feel free to reach out to us for additional help.

😞 1

😃 1

ClearFlask