Configuring the JWT SSO
  • 24 Jun 2022
  • 4 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, and 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

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 would do.

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_New_Screenshot-Accessing_JWT_SSO

  1. Log in to the Document360 portal
  2. Go to Settings → Users & Security → Enterprise SSO → 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 would be available now

2. JWT configuration

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

3_New_Screenshot-JWT_configuration_page

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


Was this article helpful?