Skip to main content

Troubleshooting OIDC IDP Integration Issues

Overview​

Use this guide to diagnose and resolve OIDC sign-in, linking, and provider-configuration failures in Atria. It maps common user-facing symptoms to Recorded Errors, event codes, and database log evidence so issues can be triaged quickly and consistently. The goal is to reduce time-to-resolution by moving from error message to root cause with a repeatable workflow.

What to Check First​

Start with these data points so every investigation has enough context for correlation across UI errors, Recorded Errors, and backend logs. Missing basic context is the main reason troubleshooting takes longer than necessary.

Collect these details before investigating:

  • Customer, user, timestamp
  • Login URL used (/login deep link if applicable)
  • Provider name
  • UI error text
  • Correlation ID (if shown)

Common End-User/Admin Errors​

This section maps visible user/admin symptoms to likely causes and first actions. Use it for rapid triage before moving into event-code and database-level analysis.

Password and Azure AD Paths​

These errors usually occur during initial sign-in entry or popup authentication. Most are resolved by validating user path selection, credentials, and network connectivity.

  • Your credentials are invalid.

    • Cause: incorrect username/password, or password path blocked when default SSO is enforced.
    • Action: retry credentials or use SSO button.

  • Azure AD popup cancelled/closed

    • Cause: popup closed or login denied.
    • Action: start sign-in again and complete popup flow.

  • Azure AD popup network error

    • Cause: no connectivity/VPN/network path.
    • Action: validate network path and retry.

Configuration-Time (Admin UI) Errors​

These issues occur while creating or updating provider definitions in Atria. They typically indicate malformed metadata, missing required values, or uniqueness constraints.

  • Well-known validation icon shows error and Save is blocked

    • Cause: malformed/unreachable .well-known endpoint.
    • Action: validate URL format and reachability.

  • Client Secret required

    • Cause: code flow requires client secret but it is empty.
    • Action: add secret and save.

  • Duplicate display name

    • Cause: another provider already uses the same display name in that customer scope.
    • Action: choose a unique display name.

Recorded Errors and Log Events​

Use Recorded Errors and structured OIDC events to move from symptom to verified root cause. Event metadata provides the fastest way to isolate failures in callback, linking, and provider lifecycle operations.

OIDC events are logged with OIDC_EVT prefix and include fields such as:

  • EventCode
  • CorrelationId
  • CustomerId
  • UserId
  • ProviderId
  • Subject
  • Route
  • HttpStatus
  • FailureCode
  • Detail

Recorded errors are designed to surface EventCode and FailureCode clearly.

Event Codes and Typical Causes​

Use this mapping to quickly interpret failure categories before reviewing detailed tags and raw log payloads.

EventCodeTypical Causes
OIDC_LOGIN_FAILUREInvalid token, missing session, callback issues.
OIDC_LOGIN_TOKEN_REDEEM_FAILUREToken endpoint errors, malformed token response, code exchange failure.
OIDC_LOGIN_TOKEN_VALIDATION_FAILUREInvalid signature, invalid audience/issuer, nonce mismatch.
OIDC_LOGIN_PROVIDER_RESOLUTION_FAILUREMissing provider mapping, claim mapping failures, identity/provider not resolved.
OIDC_LINK_START_FAILUREMissing provider/session, provider lookup failures.
OIDC_LINK_FAILUREInvalid token, database errors, unexpected callback/link processing errors.
OIDC_LINK_DUPLICATE_SUBJECTSubject already linked to another identity (unique key collision).
OIDC_PROVIDER_CREATE_FAILURECustomer not found, validation failures, secret-store failures, DB errors.
OIDC_PROVIDER_UPDATE_FAILUREProvider not found, validation failures, secret-store failures, DB errors.
OIDC_PROVIDER_DELETE_FAILUREProvider not found, validation failures, DB errors.

Common Detail Reason Tags​

Reason tags provide branch-level failure context for callback and link operations. They are the most useful discriminator when multiple events share the same high-level failure code.

Callback flow (/api/account/oidc/callback) often includes:

  • SESSION_MISSING
  • STATE_PROVIDER_ID_MISSING
  • PROVIDER_LOOKUP_FAILED
  • TOKEN_AND_CODE_MISSING
  • TOKEN_UNREADABLE
  • TOKEN_VALIDATION_EXCEPTION
  • NONCE_MISMATCH
  • CLAIM_LINK_VALUE_MISSING
  • USER_PROPERTY_LOOKUP_FAILED
  • IDENTITY_OR_PROVIDER_NOT_RESOLVED

Link flow (/api/account/oidc/link) often includes:

  • ID_TOKEN_MISSING
  • TOKEN_UNREADABLE
  • TOKEN_PARSE_FAILED
  • NONCE_MISMATCH
  • SUBJECT_MISSING

Use these queries to collect a consistent evidence set from logging, request-trace, and login-history tables. Run them with a bounded time window around the affected incident whenever possible.

Use these SQL checks when investigating incidents.

SELECT TOP (500)
  Id,
  TimeStamp,
  Severity,
  MessageTemplate,
  Message,
  CorrelationId,
  CustomerId,
  UserId,
  LogEvent
FROM dbo.Logs
WHERE Message LIKE 'OIDC_EVT %'
ORDER BY Id DESC;
SELECT TOP (200)
  AuditActionId,
  TimeStamp,
  CorrelationId,
  Route,
  Source,
  UserId,
  ImpersonatingUserId
FROM dbo.AuditActions
WHERE Route LIKE '%oidc%'
ORDER BY AuditActionId DESC;
SELECT TOP (200)
  LoginHistoryID,
  UserID,
  LoginDateTime,
  Reason,
  SessionID
FROM dbo.LoginHistory
WHERE Reason LIKE 'OIDC_LOGIN_%'
ORDER BY LoginHistoryID DESC;

Use the following pages for provider configuration and ongoing operational management.