Environment

• Product: ZCenter
• Version: 5.1.0
• Component: Base / Portal / Gateway authentication
• Trigger/Condition: A user-initiated or automated call fails because the token expires earlier than expected, and the validity period of local login tokens must be increased or decreased.

Symptoms

• After a user signs in, an API call returns an unauthenticated response before the configured validity period elapses, or the page reports that the login session has expired.
• The issue temporarily disappears after the browser or client signs in again. The Gateway log might contain Token expired, Token validation invalid, or Token verification failed.

Diagnosis

1. First, confirm whether the issue affects only old tokens. Use a token obtained from a new login to call an authenticated API, and record the returned expiresIn and refreshExpiresIn values.
2. Query the current effective setting in the database:

   SELECT category, name, setting
   FROM sys_config
   WHERE category = 'GLOBAL_SETTINGS' AND name = 'tokenExpireSeconds';

3. Check whether setting contains valid JSON and whether expireSeconds meets the business requirement without exceeding 259200 seconds.
4. To verify the TTL of a new token in Redis, use the Redis address, credentials, and database from the actual deployment to run a read-only query. Check the exact base:access_token:{userId}:{jti} and base:refresh_token:{userId}:{jti} keys. Do not delete a broad key prefix or flush the database.
5. If the database value is correct but a new token still does not have the expected lifetime, check whether the request uses a third-party identity provider. The identity provider might determine the lifetime of a third-party login token.

Cause

For a local login token, the token lifetime is first read from expireSeconds in GLOBAL_SETTINGS/tokenExpireSeconds in sys_config. The Base service falls back to jwt.token-validity-in-seconds only when the database setting does not exist or cannot be parsed. The default value in the source code is 7200 seconds, and the maximum is 259200 seconds. The 5.1.0 migration script changes the initial database value to 43200 seconds, but you must query the target database to determine whether the migration ran in a specific environment.

In the local-token flow, the refresh token lifetime is 2 times the access token lifetime. Therefore, when the access token lifetime is 43200 seconds, the refresh token lifetime is usually 86400 seconds. Do not determine the effective value solely from a property with the same name in another service's configuration file.

Resolution

1. Prerequisites

• Confirm that the operator account has permission to modify platform global settings, and record the current tokenExpireSeconds setting.
• Back up the database, or at least preserve the original setting, before making a production change. Test the change in a test environment first.
• Obtain the Redis connection information from the actual runtime configuration. Do not directly reuse the 127.0.0.1:6379 address or example password from the source code.
• Assess the impact on existing login sessions. Changing the setting does not automatically extend the JWT expiration time or Redis TTL of an issued token.

2. Procedure

1. Read and modify tokenExpireSeconds through the platform global settings API or the corresponding management page. Portal saves global settings through POST /api/portal/v4/global-setting/SaveSetting. Keep the request content valid JSON, for example:

   [{"name":"tokenExpireSeconds","setting":"{\"expireSeconds\":43200}"}]

2. Set expireSeconds to a positive value required by the business and ensure that it does not exceed 259200 seconds. Modify only this setting. Do not modify the token signing key.
3. Have the user sign in again or obtain a new token through the refresh flow. Changing only the database setting usually does not require a restart because the lifetime is read when a token is issued. If you change the default setting packaged in application.yml, redeploy the Base service for the change to take effect.
4. If the business uses a third-party identity provider, follow that provider's token policy. Do not apply the local-token setting directly to third-party tokens.

Verification

• Configuration: Query sys_config again and confirm that expireSeconds in GLOBAL_SETTINGS/tokenExpireSeconds has the target value.
• Token: Sign in again and confirm that expiresIn and refreshExpiresIn in the response match the target setting.
• Redis: Check the TTL of the keys for the newly issued token. The access token TTL should be close to expiresIn, and the refresh token TTL should be close to its actual lifetime.
• Functionality: Use the new token to repeatedly call the authenticated API that previously failed, and confirm that it remains accessible throughout the target validity period.
• Old token: Confirm that an old token is not extended incorrectly. If all users must establish new sessions, use the normal logout or session invalidation process.

Risks and rollback

• Risk: A long validity period increases the window in which a leaked token can be used. A short validity period increases the frequency of sign-in and refresh requests.
• Risk: Directly modifying a configuration file, the token signing key, or deleting Redis keys in bulk might invalidate existing sessions or disrupt platform authentication.
• Rollback: Restore tokenExpireSeconds to the valid JSON value recorded before the change, and sign in again to verify a new token. Do not use FLUSHDB or delete the entire token prefix to roll back.