JWT single sign-on

Protect your Onset Page with JWT SSO.

JWT Single sign-on is a mechanism that allows you to authenticate users in your systems and subsequently tell Onset that the user has been authenticated.

This article describes how to enable JWT single sign-on configurations that can be used to authenticate your users.

How JWT SSO works

Once you enable SSO, sign-in requests are routed to a sign-in page external to Onset.

Steps of the JWT SSO authentication process:

1. An unauthenticated user navigates to your Onset Page. Example: - https://yoursubdomain.onset.io/ - https://releases.example.com/

2. The Onset recognizes that SSO is enabled and the user is not authenticated.

3. Onset redirects the visitor to your provided URL. Example: https://mycompany.com/onset/sso.

4. A page on the remote server authenticates the user using your organization's proprietary sign-in process.

5. The authentication system creates/signs a JWT token with the secret generated in your Onset Admin Panel.

6. The authentication system redirects the user to the following Onset endpoint with the JWT token in the URL: - https://yoursubdomain.onset.io/api/jwt?token=GENERATED_JWT_TOKEN - https://releases.example.com/api/jtw?token=GENERATED_JWT_TOKEN

7. Onset validates the signed JWT token 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; there is no direct connection between Onset and your systems.

Requirements for enabling JWT SSO

As you can see from the steps above, for JWT SSO to work correctly, you must implement steps 4-6. To avoid downtime, we suggest you have all requirements before enabling the JWT SSO protection.

• Login URL - The remote login URL where unauthenticated visitors should be redirected when they attempt to access your Onset page.

• Signed JWT Token - Your authentication properly mints JWT tokens and redirects the authenticated user to appropriate /api/jwt endpoint.

• Propogate Redirects (nice to have) - Your authentication server appends the redirect_uri URL with the JWT token when redirecting the user back to Onset.

Redirect URL

When Onset redirects a visitor to your remote login page, it appends a redirect_uri URL parameter. The parameter contains the URL that Onset will send the user after your system has authenticated them.

Whether you pass in the redirect_uri parameter or not is optional, but we recommend it for the best user experience.