Skip to main content

Identity Troubleshooting

Summary​

Use this page to distinguish authentication failures from authorization, tenant, token-validity, and session failures without inspecting or exposing sensitive token contents.

Audience​

  • Platform and customer administrators
  • Support and implementation teams
  • Developers, QA engineers, and DevOps engineers

Purpose​

The guidance provides safe checks supported by the current source and identifies when access data or environment configuration needs authorized review.

Architecture​

Business concepts​

  • A 401 response means the request has not established an accepted authenticated principal for the operation.
  • A 403 response means authentication may have succeeded, but the operation is not allowed.
  • Tenant failures can occur during login or downstream tenant-scoped evaluation.
  • Session revocation or refresh-token expiry prevents token renewal.
  • Clock differences can affect time-based token validation outside the configured tolerance.

Technical implementation​

Identity login, refresh, current-user, and session operations return unauthorized responses for rejected credentials, invalid tokens, inactive accounts, invalid tenant context, invalid refresh credentials, or revoked sessions as applicable. Downstream applications return forbidden responses when authenticated claims do not satisfy their access rules.

Do not paste tokens, passwords, or decoded sensitive claims into tickets, chat, logs, or diagnostic tools.

Confirmed source references​

  • microservices/src/identity-service/Program.cs
  • microservices/src/identity-service/Application/Auth/IdentityAuthService.cs
  • microservices/src/identity-service/Application/Security/IdentityJwtTokenService.cs
  • microservices/src/gateway-api/Program.cs
  • microservices/src/platform-service/Api/PlatformAdminEndpoints.cs

Symptoms​

SymptomSupported interpretation
401 UnauthorizedCredentials, access token, refresh token, user state, session, portal, or tenant validation was not accepted.
403 ForbiddenThe authenticated identity does not satisfy a downstream role, permission, tenant, or resource-scope rule.
Expired-token responseThe access token is outside its accepted validity period.
Invalid-tenant responseTenant context is missing, mismatched, inactive, or no longer valid for the selected client portal.
Permission deniedRequired downstream access was not present for the principal or resource scope.
Time-related validation failureSystem clocks may differ beyond the validator’s configured tolerance.
Session expired or revokedThe refresh record is expired/revoked, the user is inactive, or the associated device session is revoked.

Cause​

Confirm the response status and correlation identifier first. Then check, through approved support tooling, whether the user selected the correct portal and tenant, the account remains active, the expected role/permission assignment exists, and the relevant device session remains active. Environment-specific token-validation configuration requires a DevOps or security owner.

Resolution​

ConditionSafe resolution
401 or expired access tokenAttempt the normal refresh flow. If refresh is rejected, sign in again through the correct portal.
403 or permission deniedAsk an authorized administrator to review the user’s role, permissions, tenant assignment, and resource scope. Do not circumvent the downstream policy.
Invalid tenantConfirm the intended client portal and tenant selection. Escalate tenant status or identity mismatch to the platform owner.
Clock skewEnsure participating hosts use approved time synchronization. Do not weaken token validation as a local workaround.
Session expired or revokedSign in again. If the revocation was unexpected, review device sessions and security events through approved channels.

Validation​

After remediation, confirm that login or refresh succeeds through the intended portal, the current-user response represents the expected tenant and role context, and the protected operation returns the expected authorized result. Use correlation-aware logs for escalation without recording credentials or token values.

See Also​

Keywords​

  • Authentication failure
  • Authorization failure
  • Tenant validation

Revision Information​

  • Last reviewed: 2026-07-14
  • Owner: identity-team
  • Status: Draft