Skip to main content

OAuth Debugging

This page is a diagnostic workflow for isolating an OAuth / SSO sign-in failure when the cause is not obvious. Work through the steps in order. Once you know the error, look up the fix by symptom on the OAuth Troubleshooting page.

Step 1: Reproduce Cleanly​

Rule out cached sessions and stale state before anything else.

  • Sign in from a private or incognito window so no existing cookies or sessions interfere.
  • Reproduce with a known test user whose group memberships and role at the Identity Provider you can verify.
  • Note the exact sign-in identifier and region in use. Each IDP profile is limited to a single region, and the region must match the redirect URI.

Step 2: Capture the Error​

Note where the failure shows up, because that tells you where to look.

  • On the provider's page, before returning to eCourtDate: copy the error and error_description query parameters (for example error=access_denied) and any provider error code (for example Azure AADSTS50011 for a redirect URI mismatch).
  • Back at eCourtDate: check the return URL for an error value. ?error=state or ?error=redirect_uri means the login session expired (finish sign-in within 5 minutes); ?error=not_verified means the account email is not verified.
  • Returned to the sign-in page with no error: the token exchange failed, usually a wrong or expired client secret or a reused code.
  • Match what you captured to the Error Reference table.

Step 3: Inspect the Token​

If sign-in reaches eCourtDate but the user lands in the wrong agency or role, the answer is usually in the token claims.

Use your IDP's token debugger or a JWT inspection tool to decode the id_token and confirm:

  • email is present. eCourtDate matches (or creates) the profile by email, so a missing or changed email explains a failed or duplicate sign-in.
  • Group claims are present and each expected group is named #{reference}_ecourtdate, where the reference is the numeric agency reference and the name begins with a prefix character such as # (for example #100_ecourtdate). If the groups claim is absent on a user in many groups, suspect an Azure group overage.
  • roles claim does not include security, admin, or root as a whole word unless Super Admin is intended, since those keywords elevate the user to Super Admin.
  • iss (issuer) matches your provider's endpoint. On Azure, confirm you are using v2.0 tenant-specific endpoints, not common.
  • aud (audience) matches the client ID in the Console IDP profile.
  • exp and nbf are consistent with the current time. A large gap points to clock skew.
danger

Decode tokens only in a trusted tool, and never paste a raw or decoded token that still contains secrets into a support ticket. Redact before sharing.

Step 4: Read the Provider Sign-in Logs​

When the failure happens at the Identity Provider (the user is blocked before eCourtDate sees a token), the provider's own logs name the reason. Where to look:

  • Azure AD (Microsoft Entra ID): Sign-in logs in the Entra admin center show the failure reason and AADSTS code. Check App registrations > your app > API permissions for consent status, and Certificates & secrets for an expired secret.
  • Google Workspace: Check the OAuth consent screen configuration in the Google Cloud Console and the admin audit logs. admin_policy_enforced points to an app-access or verification policy.
  • Okta: Check the Okta System Log for the sign-in, and Application > Sign On > OpenID Connect ID Token for the groups claim configuration. Confirm the user or group is assigned to the app.
  • AWS Cognito: Check User Pool > App integration for the app client's allowed OAuth scopes and callback URLs, and confirm the Cognito domain is deployed.

Step 5: Verify the eCourtDate IDP Profile​

Confirm the Console side matches the provider.

  • Open the IDP profile at console.ecourtdate.com/idps.
  • Confirm the client ID and client secret match the current values at the provider. A rotated or expired secret makes sign-in return to the login page without completing.
  • Confirm the profile's region matches the region in the registered redirect URI.
  • Confirm the Well Known, Authorization, Token, User, and End Session URLs match your provider's section in Authorization Flows.
  • Check the profile's Last Active time. It updates on a successful sign-in, so if it is not moving while you test, sign-ins are not completing through this profile.

Step 6: Escalate With the Right Details​

If the failure persists, create a support ticket in the Console: sign in, click the Help button in the bottom-right corner, and complete the Create a Ticket form. The page you are on is attached automatically, and you can follow updates under My Tickets in the same panel.

In the description, include:

  • The sign-in identifier, region, and Identity Provider
  • The error from the return URL, or the provider error code
  • The decoded, redacted id_token claims
  • The approximate time of the failed sign-in

Check status.ecourtdate.com for platform incidents.

See Also​