Setting up JWT SSO

What is a JWT?

A JSON Web Token (JWT) is an encrypted token format that securely transfers data, such as credentials (authentication and authorization), between two applications. JWT is specifically used to authenticate reader logins in Document360. Click here to read about JWT.

Enterprise SSO using JWT in Document360

Document360 supports JWT (JSON Web Token) as one of its SSO (Single Sign-On) methods, primarily used for authenticating reader logins. JWT provides a secure way to transfer authentication and authorization data between your application and the Document360 knowledge base.

Document360 uses an approach similar to PKCE (Proof Key for Code Exchange, a secure OAuth method) to generate the JWT token.

Choosing the right SSO method: JWT vs SAML vs OpenID

Document360 supports three SSO options for reader authentication: JWT, SAML, and OpenID Connect. Choosing the right method depends on how you manage users, what infrastructure you already have, and how much control you need over the login process.

The table below compares JWT against the other options:

How JWT authentication works

The high-level diagram below shows how to achieve JWT authentication flow in Document360.

The steps below explain the complete JWT authentication flow in Document360 for developers setting up reader SSO using their own login system.

Key terminology

1. User accesses the private knowledge base

   • When a user tries to access your knowledge base site, Document360 detects that JWT SSO is enabled and redirects the user to the Sign in URL configured in JWT settings.

2. User logs in to your application

   • If the user is not already authenticated, your login page handles their authentication.

3. Your backend requests a one-time auth code

   • After the user logs in, your backend sends a POST request to the Code generation URL configured in Document360 with the following:

     • User identity (e.g., name, email)

     • Optional readerGroupIds

     • tokenValidity in minutes

   • This request must be authorized using HTTP Basic Auth with your Client ID and Client Secret.

Example Authorization Header

Authorization: Basic Base64Encode(clientId:clientSecret)

JSON Payload Example

{
  "username": "firstname + lastname",
  "firstName": "firstname",
  "lastName": "lastname",
  "emailId": "user email",
  "readerGroupIds": ["Obtain from Reader groups overview page in the Document360 portal (Optional)"],
  "tokenValidity": 15 //minutes
}

NOTE

Ensure correct JSON syntax to avoid configuration errors.

4. Document360 Identity server returns an auth code

   • If the request is valid, Document360’s identity server generates a single-use authorization code and sends it back to your app (backend).

5. Your app redirects the user back to Document360

   • Your backend appends the code to the Callback URL and redirects the user to it.

   • For example: https://yourproject.document360.io/jwt/authorize?code=xyz

NOTE

The authentication code is a one-time use code and cannot be reused.

6. Document360 validates the code

   • Once it receives the code, Document360 sends it to the identity server via backchannel to exchange it for a JWT token.

7. Reader session is created

   • Document360 extracts user information and access rules (based on readerGroupIds) from the token.

   • A session is created for the reader, granting them access to allowed categories, languages, or versions.

Token validity and session behavior

• You can define the session duration using the tokenValidity field in the payload (min: 5 minutes, max: 1440).

• Once the token expires:

  • The reader is redirected back to your Sign in URL.

  • If the user is still authenticated in your app, a new code is generated, and the session is re-established seamlessly.

Developer checklist

• Configure Sign in URL, Callback URL, and Code generation URL in JWT settings.

• Generate and securely store your Client Secret (shown only once).

• Set up backend logic to call the Code generation URL with Basic Auth.

• Validate and sign the JWT securely in your backend.

• Use HTTPS for all endpoints.

• Test session behavior, expiration, and auto-renewal.

• Monitor for 401 errors due to expired codes or token issues.

Testing JWT configuration using cURL

After enabling the JWT login, the reader can use the client application to log in as a reader account on the Document360 knowledge base site.

Configuring JWT in Document360

Creating a JWT

To create a JSON Web Token (JWT),

1. Log in to the Document360 portal.

2. Go to Settings ()> Users & security > JWT.

3. Create a JWT (Client secret) from here by clicking on the Create JWT button.

4. Copy the generated client secret by clicking on the copy icon and clicking on Close.

NOTE

The same generated Client secret will not be available when you revisit this section. If required, the client's secret must be regenerated.

The JWT configuration page with all the data is now available.

JWT configuration page overview

After a JWT is created, the JWT configuration page will be visible.

• Set up your application: Copy the Client ID, Callback URL, Code generation URL, Client secret, and paste them into the appropriate fields in the client application

• JWT status: Turn the JWT SSO login for readers on or off using this toggle. If the toggle is set to off, readers will not be able to log in to the knowledge base site using their client app credentials.

• Delete JWT: Click the Delete button to remove the configured JWT. You cannot undo this action.

• JWT basic configuration: Paste the login URL obtained from the client's application.

  • Readers will land on the dedicated logout page for JWT SSO readers if a custom logout link is not provided.

Redirection to other pages instead of the home page

By default, after logging in, users are redirected to the Home page of your knowledge base.

• If your Home page is unpublished, users will be redirected to the /docs page.

• To redirect users to a different page in your knowledge base (other than the Home or /docs pages), configure the redirection during JWT setup using the following code.

URL pattern

https://<Knowledge base URL>/jwt/authorize?code=<code>&redirectUrl=<redirect path>

Parameters

• <Knowledge base URL>: The main URL of your knowledge base site.

• <Code>: The client ID.

• <redirect path>: The new URL where you want users to land after login.

Example

https://example.document360.io/jwt/authorize?code=FOTaS_SW6dLGytQXvrG_rRFGhyPvrDDrgxJAZzYvJcY&redirectUrl=/docs/5-basic-things-to-get-started

NOTE

• Document360 will send the Redirection URL as redirectPath to the login endpoint. When the login endpoint redirects back to the knowledge base with the authentication code, it should return the Redirection URL as a redirectUrl parameter.

• In KB Site 2.0, redirection is handled using cookies instead of the redirectUrl parameter. If your JWT implementation is based on query string redirection (using the redirectUrl parameter), please note that the cookie-based approach does not support this parameter. You may need to update your implementation or contact support for further clarification.

Troubleshooting

If you encounter issues during the JWT SSO setup, refer to the following common errors and their solutions:

401-unauthorized error when testing JWT in Postman

Error: 401 Unauthorized error

If you encounter a 401 Unauthorized error while testing JWT (JSON Web Token) using Postman, this typically occurs because the authorization settings are not configured correctly.

Steps to resolve:

To resolve this error,

1. In Postman, open the request you are testing.

2. Navigate to the Authorization tab.

3. Set the authorization type to Basic Auth.

4. In the Username field, enter the Client ID.

5. In the Password field, enter the Client Secret.

6. Go to the Body tab.

7. Select the raw option from the dropdown and ensure the format is set to JSON.

8. Add the required JSON payload for the API request.

9. Click Send to execute the request.

Check the response for the expected results. If the request is successful, you should receive an auth code or token in the response.