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.
💡 For a deeper dive into JWT, you can read up more on this here: https://jwt.io/introduction
This article contains the following sections:
How JWT for LaunchNotes works
You can enable JWT from within your LaunchNotes project under Settings > Security on the Admin navbar. 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 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.
Below are the following steps of the JWT authentication process for an unauthenticated user (i.e. user whose session has expired):
An unauthenticated user navigates to your private LaunchNotes page URL (e.g. updates.yourcompany.com) for example, from a page bookmark or announcement email.
The user is redirected to your custom landing page with copy and instructions.
The user is instructed to follow these instructions and click a button to a redirect url that you provide to re-authenticate through your authentication system. (For options on how to setup this re-authentication flow, see the technical implementation below).
Your user is redirected to your private LaunchNotes page URL with an encrypted JWT authentication token appended appended as a query param.
Your user is provisioned a 24 hour session after being authenticated based on the user data you pass to LaunchNotes via the JWT authentication token.
Technical implementation
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.
Authentication
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 Authorization 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.
From Auth0: Hash-based Message Authentication Code (HMAC) is an algorithm that combines a certain payload with a secret using a cryptographic hash function like SHA-256. The result is a code that can be used to verify a message only if both the generating and verifying parties know the secret. In other words, HMACs allow messages to be verified through shared secrets.
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:
Add a link to your private LaunchNotes page within your platform. ie: https://updates.yourcompany.com
Intercept this link click either with JavaScript or an intermediary page and generate your JWT authentication token "just-in-time" and append it to the intended URL as an "authToken" query parameter. ie: https://updates.yourcompany.com?authToken={{generatedToken}}
LaunchNotes will decrypt your authentication token and provide the authenticated user with a 24 hour session.
Required JWT claims
Attribute | Description |
sub | The email address of your user visiting your Private page |
aud | The ID of your Private LaunchNotes page. This is found in the URL of your LaunchNotes admin and will start with "pro_[xyz123]" |
iat | Time of issuance (seconds since epoch) |
exp | Time when the JWT will expire (e.g. 3 minutes from now - seconds since epoch) |
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'
});
Re-authentication when a user's session expires
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 > Customize Page.
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.
Authenticating the user and immediately redirecting to the original url.
You provide a redirect url from the unauthenticated landing page to an authentication endpoint that allows the user to sign in with their credentials.
When a user clicks the button with the provided redirect url, they are sent there with a query param of the original url. An example of the full request would be: https://yourcompany.com/auth/jwt?originalUrl=https://updates.yourcompany.com/announcements/1
Upon successful authentication, your authentication endpoint generates the JWT authentication token and appends it to the original url passed with the query parameter named authToken. eg: updates.yourcompany.com/announcements/1?authToken={{JWT token}}
Directing 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.
Instruct the user to your generic authentication page for them to sign in and be redirected to your default home page.
Instruct them on how to navigate from the home page to find the JWT secured link to your private LaunchNotes page.
Notification Security
You are able to select how your notifications are sent to your private page subscribers via Slack and email by being able to control whether or not you'd like the content of your notifications shown in the notification, or rather have your subscribers access your page to view for additional security.
You're also able to select whether you'd like to auto-subscribe new users to your private page on their first visit. This can help with user adoption and engagement on your updates, especially when introducing your new page. Your users are able to create or change their subscription preferences at any time by visiting your private page.
