Configuring the JWT SSO
  • 28 Jan 2023
  • 5 Minutes to read
  • Contributors
  • Dark
    Light
  • PDF

Configuring the JWT SSO

  • Dark
    Light
  • PDF

What is a JWT?

A JSON Web Token (JWT) is an encrypted token format used to securely transfer 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.

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

    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

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 *()*
}
  1. 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

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

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

The HTTP version should be specified (HTTP2 over TLS and version of SSL to TLS 1.2.
Without this, the cURL would fail.

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 the JWT login is enabled, the reader can use the client application to log in as a reader account on the Document360 knowledge base site.

Currently, Document360 provides an either-or functionality for the SSO standards. Once the IdP is configured using an SSO standard (SAML or OpenID or JWT) for a project, the user would not be able to 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

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

2_New_Screenshot-Create_a_JWT_in_portal_generated_token

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

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

The configuration page and field arrangement on the client application differs in each 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 have not published 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

Document360 will send Redirection URL as RedirectPath to the Login endpoint. Once the Login endpoint redirects to Knowledge base site with auth code, it should return the Redirection URL as RedirectUrl parameter.


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 would be able to 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 less than or exceeding 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 →



Was this article helpful?