Managing JWT configurations

Prev Next

After you set up and test a JWT configuration, you can turn it on or off, delete it, regenerate its secret tokens, control which login buttons readers see and track every change in the audit log. Use this article to keep reader sign-in through your application working as your setup changes, without locking readers out of the knowledge base site.


When to manage a JWT configuration

  • You need to pause sign-in through one configuration without losing its settings.
  • You no longer use a configuration and want to remove it.
  • A secret token was exposed, lost or is due for rotation.
  • You run several JWT configurations, or JWT alongside SAML or OpenID SSO, and want to control which login options readers see.
  • You need a record of who changed a configuration and when.

Before you begin

  • You need the Owner or Admin project role to manage JWT configurations.
  • At least one JWT configuration must exist in your project. To create one, go to Settings () > Users & Permissions > Enterprise SSO > Create SSO > JWT. For the full setup, see Configure JWT in Document360.
  • Check how readers sign in. If a JWT configuration is the only active SSO or JWT configuration and the default login page is disabled, you can't turn it off or delete it until you enable another configuration or turn the default login page back on.

How to turn a JWT configuration on or off

Turn off a configuration when you need to suspend it temporarily. Its settings are kept, so you can turn it back on without reconfiguring.

  1. Go to Settings () > Users & Permissions > Enterprise SSO.
  2. Locate the JWT configuration you want to manage.
  3. Click the Edit () icon on the configuration.
  4. Select the Server settings tab.
  5. Expand Advanced settings.
  6. Turn the Enable JWT authentication toggle off to deactivate the configuration, or on to reactivate it.
  7. Click Update.
JWT configuration modal, Server settings tab, with Advanced settings showing the Enable JWT authentication and Show login button toggles.

When you turn a configuration off, readers can no longer start a new sign-in through it. Readers who are already signed in stay signed in until their session ends.

If this is the only active SSO or JWT configuration and the default login page is disabled, Document360 doesn't turn it off and shows this message:

This is the only active SSO or JWT configuration and the default login page is disabled, so turning it off or deleting it would lock everyone out. Enable another configuration, or turn the default login page back on, first.


How to delete a JWT configuration

CAUTION

If you might need the configuration again, turn it off instead of deleting it. Turning it off keeps its settings.

  1. Go to Settings () > Users & Permissions > Enterprise SSO.
  2. Locate the JWT configuration you want to remove.
  3. Click the Delete () icon.
  4. Confirm the deletion when prompted.

The configuration no longer appears in the Enterprise SSO list.

If this is the only active SSO or JWT configuration and the default login page is disabled, Document360 doesn't delete it and shows this message:

This is the only active SSO or JWT configuration and the default login page is disabled, so turning it off or deleting it would lock everyone out. Enable another configuration, or turn the default login page back on, first.


How to regenerate secret tokens

Each configuration has two secret tokens, and both work at the same time. Regenerating one replaces only that token; the other keeps working. To rotate without interrupting sign-in:

  1. Switch your application to the secondary secret token.
  2. Go to Settings () > Users & Permissions > Enterprise SSO and click the Edit () icon on the configuration.
  3. On the Authentication tab, under JWT keys, click the Regenerate icon next to the primary secret token and confirm. The new token takes effect immediately; there is nothing to save.
  4. Copy the new token. It can't be shown again after you close the dialog.
  5. Switch your application to the new primary secret token.
Edit JWT modal, Authentication tab, with the masked primary and secondary secret tokens and a Regenerate icon next to each.

Route readers to the right JWT configuration

When several JWT configurations are active, Document360 routes each reader to a configuration based on the domain name they enter on the login page.

When a reader types a domain on the login page, Document360 looks for the active JWT configuration whose Domain name is exactly that value, ignoring letter case. If it finds one, it sends the reader to that configuration's Login URL. Subdomains are separate entries: support.example.com and example.com can belong to different configurations, and neither matches the other.

Routing follows these rules:

  • Each domain name must be unique across all JWT configurations in the project.
  • Readers see "Enter a valid domain name" when the value matches no configuration or matches a configuration that is turned off. The same error appears for a value that starts with https:// or has no dot.
  • An email address typed in the field isn't treated as a domain; it starts SSO sign-in instead.
  • The Domain name field routes to JWT configurations only. Readers can't reach SSO providers through it.

Use one configuration or several

Domain routing only decides which Login URL a reader is sent to. It doesn't affect sign-in itself: Document360 issues a sign-in code to any caller that sends the configuration's Client ID and one of its secret tokens.

  • If several environments, such as development and production, can use the same Client ID and secret tokens, they can share one configuration.
  • If each environment needs its own secrets, or you want to keep sign-in flows apart by domain, create a separate configuration for each.

How readers reach the right sign-in page

This applies only when your project has 2 or more active JWT configurations. With one, readers always go straight to its Login URL.

When a reader opens the knowledge base URL directly

If a reader types the knowledge base address, opens a bookmark, or clicks a link in an email or chat, the browser doesn't tell Document360 where the reader came from. Document360 can't tell which configuration the reader belongs to, so it shows the Document360 login page. There the reader clicks their login button or enters their domain name. Document360 then sends them to that configuration's Login URL, which signs them in as usual and returns them to the knowledge base.

When a reader opens the knowledge base from your application

When a reader clicks a link in your application, such as a Help icon, the browser tells Document360 which site the reader came from (the referer). Document360 compares that site's domain with the Login URL of each active JWT configuration:

  • It matches: Document360 sends the reader to that configuration's Login URL. Sign-in then happens as usual: your endpoint gets a code from the Code generation URL and sends the reader to the Callback URL with the code. The reader lands in the knowledge base signed in, without seeing the login page.
  • It doesn't match: the reader sees the Document360 login page, as with a direct visit.

Example

JWT configuration Login URL
Customer portal https://portal.example.com/docs/auth
Partner portal https://partners.example.com/docs/auth
Where the reader starts What happens
Clicks Help on https://portal.example.com/dashboard Domain matches Customer portal. The reader goes to https://portal.example.com/docs/auth, which gets a code and redirects to https://yourproject.document360.io/jwt/authorize?code=…. The reader is signed in.
Clicks Help on https://partners.example.com/home Domain matches Partner portal, and the same steps run through https://partners.example.com/docs/auth.
Opens https://yourproject.document360.io from a bookmark No referer. The reader sees the Document360 login page.
Clicks Help on https://app.example.com No configuration has a Login URL on app.example.com. The reader sees the Document360 login page.

How the domain is matched

This matching works differently from the Domain name field on the login page, where the typed value must match exactly.

  • Only the domain is compared, not the path, and letter case is ignored.
  • A subdomain matches its parent domain: a Login URL on example.com also matches a reader coming from help.example.com. Sibling domains don't match: portal.example.com doesn't match partners.example.com.
  • If more than one configuration matches, the first one is used. Avoid Login URLs on a parent domain such as example.com when other configurations use its subdomains.
  • Turned-off configurations are never matched.
  • The Direct JWT login setting doesn't affect this matching.

Run JWT and SSO side by side

JWT and SSO (SAML or OpenID) configurations can be active at the same time in the same project. You manage each type separately: changing a JWT configuration doesn't affect SSO configurations, and the reverse is also true. You can then support readers from different identity systems on one knowledge base site.

Example: Your customers sign in through JWT from your application, while your employees sign in through an identity provider such as Okta using SAML. Both methods stay active together.


Arrange login buttons

The reader login page shows a login button for each active configuration, up to the limits in Considerations. When three or more providers are active, the first two in your configured order appear as primary buttons. The rest appear under Other login options as one merged list of SSO and JWT providers, in the same order.

By default, buttons appear in the order you created the SSO and JWT configurations. To change the order:

  1. Go to Settings () > Users & Permissions > Enterprise SSO.
  2. Drag a configuration to its new position in the list, or move it with keyboard reordering. The list shows all enabled SSO and active JWT configurations together.

The new order is saved automatically and applies to both the primary buttons and Other login options on the reader login page.

Customize site, Login page, with the CTA position list and a preview of the login page showing two login buttons and the Other login options link.
NOTE

The preview shows the first two buttons only. The remaining providers appear under Other login options once published.


Understand what readers see on the login page

NOTE

Check Direct JWT login first. Document360 turns it on when you create your first JWT configuration. While it is on, SSO buttons are hidden, and if exactly one JWT configuration is active, readers skip the login page and go straight to its Login URL. The table below describes the login page with Direct JWT login off. For details, see Configure JWT in Document360.

The login page readers see depends on the Disable default login page toggle and on which JWT and SSO configurations are active.

State Toggle JWT active SSO active What readers see
1 OFF No Yes Email and password form with SSO login buttons
2 OFF Yes Yes Email and password form with SSO and JWT login buttons
3 OFF Yes No Email and password form with JWT login buttons
4 ON No Yes SSO login buttons only, no email and password form
5 ON Yes No Domain name field with JWT login buttons, no email and password form
6 ON Yes Yes Domain name field with JWT and SSO login buttons, no email and password form

These rules apply in every state:

  • Readers see active configurations only. Inactive configurations are never shown, whatever the toggle state.
  • The Domain name field appears whenever the toggle is ON and at least one JWT configuration is active. This keeps JWT configurations without a visible button reachable.
  • When the toggle is OFF and some active JWT configurations have no login button, readers reach them through Other login options, which shows the Domain name field.
  • If all JWT and SSO configurations are inactive while the toggle is ON, readers see a message that no login options are available.
  • Changes to the toggle or to a configuration's status apply immediately to new reader sessions. Existing sessions aren't affected.
CAUTION

Turn on the Disable default login page toggle only after you fully configure and test JWT or SSO authentication. If the external authentication provider is misconfigured, readers can't access the knowledge base.


Track JWT changes in the audit log

Use team auditing to see who changed a JWT configuration and when. JWT events are recorded once you turn on their event category in Audit configuration.

  1. Go to Settings () > Knowledge base portal > Team auditing.
  2. Select the Audit configuration tab.
  3. Turn on the Users & security settings toggle, which includes the JWT events.
  4. Go back to the Team auditing tab. Use the Event dropdown and search for "JWT" to filter by event type.

JWT activity appears in the audit log. For filters and export options, see Team auditing.

The following JWT actions are logged:

  • Create, Update, Delete
  • Enable, Disable
  • Regenerate Primary Token, Regenerate Secondary Token
  • Enable/Disable Direct JWT Login
  • Enable/Disable Default Login Page toggle

Each log entry records:

  • The action type
  • The timestamp (UTC)
  • The administrator who performed the action
  • The configuration name at the time of the action

For update actions, the entry also lists the fields that changed, with their previous and new values. Token values are never recorded; only the fact of rotation is logged.

Logs are retained for a minimum of 90 days. Only users with Security & Audit permissions can view JWT audit logs.

Email notification recipients:

Event type Recipients
All JWT configuration events Admins
Secret token regeneration Admins and Owners

Considerations

Item Limit
JWT configurations per project Up to 5, depending on your plan. Turned-off configurations count toward the limit; delete one to free a slot.
SSO configurations per project Up to 5 SAML and OpenID configurations combined, depending on your plan.
JWT configurations with a login button Up to 3. Others are reached by entering their domain name.
Buttons shown directly on the login page 2, counting SSO and JWT together. The rest appear under Other login options.
Last active configuration You can't turn off or delete the only active SSO or JWT configuration while the default login page is disabled.

When the 3-button JWT limit is reached, all Admins receive this system notification: "You've reached the limit of 3 JWT login buttons. Additional JWT configurations will not appear as buttons on the login page. Readers can still sign in by entering their domain name."


Best practices

  • Rotate without downtime. Switch your application to the secondary secret token, regenerate the primary token, then switch back to the new primary token.
  • Turn off rather than delete JWT configurations when you troubleshoot. Turning off keeps your settings so you can reactivate without reconfiguring.
  • Check Direct JWT login when you add SSO. Document360 turns it on with your first JWT configuration, and it hides SSO buttons. Turn it off if readers need to choose between JWT and SSO.
  • Test the Disable default login page toggle in a staging environment before you turn it on in production.
  • Keep the default login page or a second configuration available before you change your last active configuration.
  • Review the audit log regularly for unexpected configuration changes or token regenerations.
  • Keep only the JWT configurations you use. Unused configurations add management work and security exposure.

FAQ

Why can't I turn off or delete my JWT configuration?

Document360 blocks the action when the configuration is the only active SSO or JWT configuration and the default login page is disabled, because no one could sign in. Enable another configuration, or turn the default login page back on, and try again.

What happens if I lose my secret token?

You can't view a secret token again after you close the dialog. Switch your application to the other secret token, then open the configuration with the Edit icon and regenerate the lost token. Regenerating invalidates only that token.

If I turn off a JWT configuration, are signed-in readers signed out?

No. Turning off a configuration stops new sign-ins through it, but existing sessions stay active until they end.

Why do readers who click through from our application see the Document360 login page?

Document360 couldn't match the site the reader came from to a JWT configuration. To find out why:

  1. In your application, open the browser's developer tools and select the Network tab.
  2. Click the link to the knowledge base, select the first request to the knowledge base, and look for Referer under Request Headers.

Use the result:

What you findCauseFix
No Referer headerThe link removes it, for example rel="noreferrer", or your application sends Referrer-Policy: no-referrerUse a normal link to the knowledge base and keep the browser's default referrer policy (strict-origin-when-cross-origin)
Referer domain differs from every Login URL domainNo configuration has a Login URL on that site, for example the reader comes from app.example.comCreate a JWT configuration whose Login URL is on that domain, with that site's own Client ID and secret token
Referer matches, but the configuration is turned offTurned-off configurations are skippedTurn the configuration on
Referer matches, but readers loop back or see an errorThe Login URL doesn't generate a code and redirect to the Callback URLCheck the sign-in endpoint (see Implement JWT in your application)

Why do readers see the login page when they open the knowledge base from a bookmark or an email link?

The browser doesn't send a referer in these cases, so Document360 can't tell which configuration to use. Readers pick their login button or enter their domain name. After they sign in, they return to the knowledge base.