JSON Web Token (JWT) is a protocol that allows an authenticated user in your platform to visit your JWT secured private LaunchNotes page seamlessly without having to provide separate sign-in credentials.

This mechanism allows you to utilize your existing authentication method(s). All you have to do is provide the user a link to your private LaunchNotes page with an encrypted JWT authentication token that we then decrypt and provision the user with a 24-hour session to interact with your private LaunchNotes page.

This article contains the following sections:

You can enable JWT from within your LaunchNotes project on the Admin navbar under Settings > Security > Select JWT. For instructions on how to do this, please visit this quick article on setting up JWT here.

Once this is enabled, access requests to view your private LaunchNotes page will require an active session or a valid JWT passed as a query parameter named authToken to your private LaunchNotes page url. If a request is not authenticated, then it will be redirected to a custom LaunchNotes page with instructions that you provide for the user to re-authenticate or will auto-redirect them straight to your authentication page.

Below are the following steps of the JWT authentication process for an unauthenticated user (i.e. user whose session has expired):

This section is for the team at your company responsible for your authentication system. It provides details about setting up and configuring LaunchNotes' JWT integration.

In order to generate an encrypted JWT authentication token to authenticate your users when visiting your private LaunchNotes page, we provide a shared secret key, a list of required claims that need to be included in your JWT, an example JWT, and a way to test a sample JWT that you have generated.

To setup your JWT authentication settings, head to the Authentication page, which can be found under Settings > Security > Authentication. Please note that you must be a LaunchNotes Admin in order to access this page.

We accept JWTs encrypted using the HS256 algorithm and signed by the secret key that we provide you.

In order to provide your users with a link to your private LaunchNotes page and successfully authenticate them with an authentication token, we recommend that you:

Here are two examples:

Ruby:

require "jwt" payload = { "sub": "[email protected]",    "aud": "pro_12345",    "iat": 1633643621,    "exp": 1633726421 } secret_key = "#{your_secret_key}" JWT.encode(payload, secret_key, "HS256")

JavaScript:

var jwt = require('jsonwebtoken'); const payload = { sub: "[email protected]", aud: "pro_12345", iat: 1633643621,    exp: 1633726421 }; const secretKey = ${yourSecretKey}; const token = jwt.sign(payload, secretKey, { algorithm: 'HS256', expiresIn: '10m' });

When your subscribers' JWT sessions expire, they'll be redirected to a landing page that will guide them to quickly re-authenticate and then gain access to your private page. Similarly, if someone without permission attempted to access your private page, they'd be shown this same landing page, and would not be able to progress further until they're able to authenticate themselves.

To customize the copy and instructions for your private LaunchNotes unauthenticated landing page, head to Settings > Security > Unauthorized behavior.

By toggling on auto-redirect you can skip the unauthenticated landing page by automatically sending the user to an authentication endpoint based on the url you provide to sign in with their credentials. Upon successfully logging in, a user will gain access to the private LaunchNotes page they were trying to access.

There are several options to re-authenticate a user and redirect them back to your private LaunchNotes page. Below are two examples, the first of which likely requires additional developer time to setup, but the most seamless integration with your existing authentication system. The second is the easiest to setup.

Option 1 - No session, user is redirected to their authentication service, then back to LaunchNotes

Option 2: Existing user session in customer platform can click a link to Private Page that generates a JWT with the User’s info

This process generates the JWT via JavaScript running on the page when a user clicks a link within the authenticated portion of their application. It will direct the user to follow a few steps to re-authenticate via your platform and then find the secured link to your private LaunchNotes page within your platform. Upon clicking the link the JWT token will be passed with them to give them access to the private LaunchNotes page.

Alternative / Lightest lift option (no auto-redirect)

You can use our hosted unauthorized page when a User doesn’t have an active session to instruct them on how to find the link to the Private Page secured with a JWT in the customer platform.