Configuring the 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 used only for the Readers' login.

Read about JWT →

Enterprise SSO using JWT

Document360 uses an approach similar to PKCE (Proof Key for Code Exchange) in OAuth to generate the JWT Token.

The high-level diagram below shows how you can achieve JWT login flow in Document360.

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

   The assumption here is 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 auth code

   This communication is done through the backchannel.

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

   The client id and secret need to be sent as a basic authorization header.

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

{
"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 *()*
}

5. The Identity server will generate the code based on the user details, client id, and client secret and returns the generated code to the customer application

   This is done via the backchannel

6. 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}

7. Once the Knowledge base receives the auth code in the query parameter, it will send the code to the identity server via backchannel for the ID token and access token

8. 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 redirect to the login URL (hosted within the customer application) to get a new code, and the flow will repeat.

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

Unlike the other IdP options available (Okta, Azure AD, etc.), the user is not required to have a separate reader account on Document360. The account on the client application is enough.

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.

SSO Configuration

1. Creating a 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

5. The JWT configuration page with all the data will be available now

2. JWT configuration

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

a. JWT status - Enable or disable the JWT SSO login for readers using this switch. If the switch is set to off, the readers will not be able to log in to the knowledge base site with their client app credentials

b. Delete - Click on the delete button to remove the configured JWT

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

d. JWT basic configuration - Paste the login URL. You can obtain this from the client's application

e. Logout URL (Optional)- The Logout landing page option can be configured on the JWT setup page. Add the custom page link in the Logout URL(optional)

The reader will land on the new logout page dedicated to the JWT SSO readers if the custom logout link is not provided.

Redirection to other pages instead of the home page

When you configure the JWT post-login, the users are redirected to the Home page of your docs website. If you are yet to publish your Document360 Home page, the users will be redirected to the /docs page.

In scenarios where you want your users to land on an entirely different page in the knowledge base other than the Home or the /docs page, add the code below while you configure your JWT.

URL pattern

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

Parameter	Description
Knowledge base URL	The main URL of your Knowledge base site
Code	Client ID
Redirect URL	The new URL you want your users to land on post-login

For example,

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

FAQ

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

The session on Document360 is independent after the initial Single Sign-On. The user could use Document360 even after logging out of the client application for the specified amount of token validity.

For example. If the token validity is set as 1 day, the Document360 session will be active till the token validity. Once the token expires, they will be logged out.

2. What are the minimum and the maximum token validity band?

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

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

Though you provide the value at the configuration time, the value nearest to the minimum or maximum value is assigned as token validity (5 minutes or 1440 minutes).

Read about JWT →