Test your JWT configuration

Prev Next

Once you have implemented the JWT SSO logic in your backend, test the integration before going live. These tests check that Document360 accepts your Client ID and secret token and returns a one-time sign-in code, and then finish the sign-in in a browser.

Test using cURL
Run a command-line request to verify your client credentials and payload are accepted by Document360.
Jump to cURL →

Test using Postman
Send a manual POST request in Postman to confirm a one-time authorization code is generated successfully.
Jump to Postman →


Before you begin

  • A JWT configuration in Document360. See Configure JWT in Document360.
  • From the configuration's Authentication tab: the Client ID, the Code generation URL and the Callback URL.
  • The primary or secondary secret token you copied when you created the configuration.
  • cURL or Postman installed on your computer.

Test using cURL

To test the JWT configuration with cURL, run this command with the Code generation URL from your JWT configuration:

curl -X POST "<Code generation URL from your JWT configuration>" \
  -u "<Client ID>:<Secret token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john.doe",
    "firstName": "John",
    "lastName": "Doe",
    "emailId": "john.doe@example.com",
    "tokenValidity": 60
  }'

-u builds the Basic authentication header for you, so you don't need to Base64-encode anything. Add readerGroupIds only with real reader group IDs, and add providerName when the project has 2 or more JWT configurations.

NOTE
  • If your project has 2 or more JWT configurations, add providerName to the payload, set to the configuration's Domain name (Settings > Users & Permissions > Enterprise SSO > Edit icon > Server settings). Test each configuration with its own Domain name. For more information, see Re-authenticating readers with multiple JWT configurations.
  • Readers do not need a separate account on Document360. An account on the client application is sufficient to access the knowledge base.

Expected result

If the Client ID and secret token are correct, the response is:

{ "success": true, "code": "<one-time code>" }

If either is wrong, the response is HTTP 401 with {"success": false, "error": "validation failed"}.

To finish the test, open this address in a browser within 5 minutes, using the Callback URL from your configuration and the code you received:

https://<your KB domain>/jwt/authorize?code=<one-time code>

The knowledge base should open with you signed in. Each code works once; request a new one for every attempt.


Test using Postman

You can test your JWT SSO configuration using Postman by manually sending a request to the Code generation URL. This lets you verify that your client credentials and payload are accepted and that a one-time authorization code is generated successfully.

  1. Open Postman and create a new request. Set the method to POST. In the URL field, paste the Code generation URL from the Authentication tab of your JWT configuration. It ends in /jwt/generateCode, and its host depends on your region.

  2. Go to the Authorization tab.

  3. Set the Type to Basic Auth.

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

  5. In the Password field, enter the primary or secondary secret token.

  6. Go to the Body tab.

  7. Select the raw option and set the format to JSON.

  8. Enter the JSON payload:

    {
      "username": "john.doe",
      "firstName": "John",
      "lastName": "Doe",
      "emailId": "john.doe@example.com",
      "tokenValidity": 60
    }
    

    Add readerGroupIds only with real reader group IDs. If your project has 2 or more JWT configurations, add providerName, set to the configuration's Domain name.

  9. Click Send to submit the request.

The response and the browser step to finish the test are the same as for cURL. See Expected result.


Best practices

  • Use your real Client ID and secret token. They are the only values Document360 checks. Names and emails in the payload can be test values.
  • Use real reader group IDs, or leave the field out. Unknown IDs still produce a code, but the reader is refused access on the site.
  • Match providerName to the correct JWT configuration. If your project has 2 or more JWT configurations, test with the Domain name of each configuration to confirm that readers return to the correct Login URL when their session expires.
  • Use the code within 5 minutes. Each code works once.
  • Test the whole flow, not just the code request. Open the knowledge base in a private window, get sent to your Login URL, sign in, and check that you land on the article you opened.
  • Test session expiry. Set tokenValidity to 5, wait for the session to end, and check that you return to the knowledge base without signing in again.
  • Copy every URL from the configuration. Hosts differ by region, and a custom domain changes the Callback URL.

Troubleshooting

What you see Cause Fix
401 {"success":false,"error":"validation failed"} Wrong Client ID or secret token, or the token was regenerated Copy the Client ID again; use a current secret token
"Sorry, you're not authorized to access this documentation. Invalid authentication code." The code is older than 5 minutes, was already used, or belongs to another project Request a new code and redirect straight away
The reader is sent to the login page with a sign-in loop error Your Login URL sends readers back to the knowledge base without going through /jwt/authorize?code= Redirect to the Callback URL with a fresh code
The reader signs in but is refused access to articles readerGroupIds contains IDs that don't exist in the project Use real IDs from Reader groups, or leave the field out

When the test passes and readers can sign in, you can hide the Document360 email and password login. See Deactivating Document360 login page.