Setting up JWT SSO

Plans supporting single sign on (SSO)

Professional
Business
Enterprise






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

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

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

Picture1.png

Steps in the JWT authentication flow

  1. When the end-user tries to access the knowledge base configured with JWT, the Document360 knowledge base will redirect the end-user to the login URL that the team account has configured in Document360 JWT settings.

    Assuming that the configured login URL resides inside the customer application, which will require authentication.

  2. By calling the login endpoint in the customer application, it will invoke the login logic, which will send a request with:

    • User details

    • Client ID and client secret to the identity server code generation URL to get the authentication code

      This process is done through the backchannel.

  3. The code generation URL will accept the POST requests with the JSON payload shown below:

    The client ID and secret must be sent as a basic authorization header.

Follow this link to find out how the header needs to be formed for basic authentication.

JSON payload

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

NOTE

Ensure correct JSON syntax to avoid configuration errors.

  1. The identity server will generate the code based on the user details, client ID, and client secret and return the generated code to the customer application.

    This is done via the backchannel.

  2. Once the customer application receives the auth code from the identity server,

    • The customer app will append the code to the callback URL found in the JWT settings and redirect the user to the callback URL with the code.

    • For example: HTTPS://{project_name}.document360.io/jwt/authorize?code={code}

  3. Once the knowledge base receives the authentication code in the query parameter, it will send the code to the identity server via backchannel for the ID token and access token.

  4. Once the knowledge base has received the ID token, it will create a session on behalf of the user mentioned in the earlier user details.

    • By default, this session will be valid for 15 minutes. Once the session cookie expires, the end-user will be redirected to the login URL (hosted within the customer application) to get a new code, and the flow will repeat.

    • The session renewal will be seamless since the user is already authenticated to the customer application

Token validity

The minimum value that can be set is 5 minutes, and the maximum value that can be set is 1440 minutes (1 day).

cURL

To test the JWT configuration, you can use the cURL command with the following specifications. The HTTP version should be specified (HTTP2 over TLS and version of SSL to TLS 1.2. Without this, the cURL would fail.

NOTE

Unlike other IdP options available (Okta, Azure AD, etc.), the user does not need a separate reader account on Document360. An account on the client application is sufficient.

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.

NOTE

Currently, Document360 provides an either-or functionality for the SSO standards. Once the IdP is configured using an SSO standard (SAML, OpenID, or JWT) for a project, the user cannot create another simultaneous session.

For Ex. If a project is configured in the OpenID standard with Okta as IdP, the SAML and the JWT options would be disabled.


SSO configuration

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.

image.png

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 will be available now.


JWT configuration

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 it into the appropriate fields in the client application

image.png

  • 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.

image.png


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 URL: 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.


Troubleshooting

If you encounter issues during the JWT SSO setup, refer to the following common error and its solution:

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.


FAQs

Can I use a single JWT login to support multiple instances of my application on the same Document360 Knowledge base site?

No, currently, Document360 supports a single JWT login configuration per project.

  • A common JWT login cannot be shared across multiple instances of your application for the same Document360 knowledge base.

  • Each project can only authenticate one JWT application instance at a time.

If a configured JWT user logs out of the client application, does that mean they would also be logged out of Document360?

No, the session on Document360 is independent after the initial Single Sign-On. Users can continue using Document360 until the token validity expires, even after logging out of the client application.

Example: If the token validity is set to 1 day, the Document360 session will remain active until the token expires. Once it does, the user will be logged out.

What are the minimum and the maximum token validity bands?

The minimum value that can be set is 5 minutes, and the maximum value that can be set is 1440 minutes (1 day).

Can I provide a value that exceeds the allowed token validity band?

No, if a value outside the range is provided, the system will automatically assign the nearest allowed value:

  • 5 minutes for values below the minimum.

  • 1440 minutes for values above the maximum.

What is the difference between JWT and SSO?

You can view a comparison between JWT (JSON Web Token) and SSO (Single Sign-On) in the table below:

Aspect

JWT

SSO

Authentication

Tokens generated per session/user request.

Centralized authentication across apps.

Token Expiry

Tokens typically expire after a set period.

No token, session handled by identity provider.

Security

Requires secure token storage.

More secure, centralized credential storage.

Usage

Used for stateless, single-use authentication.

Used for multiple applications with single login.

Integration

Easier to implement in custom apps.

Requires integration with an identity provider.

Can readers log in with OpenID or SAML if JWT is configured for the project?

No, readers cannot log in with OpenID or SAML if JWT is configured for the project. Document360 allows only one SSO standard (JWT, OpenID, or SAML) to be active per project at a time.

What features are not supported when JWT is configured for the project?

The following functions are not supported when JWT is configured for the project:

  1. Advanced Settings: Auto-register SSO and skip the Document360 common sign-in page.

  2. Readers: Self-registration.