Skip to main content

OAuth Troubleshooting

This page is organized by symptom (what you or your users see) and moves from the likely cause to the fix. For a step-by-step way to isolate an unclear failure, see the OAuth Debugging workflow. For configuration details, see Authorization Flows and Scopes & Claims.

Before You Begin​

Most SSO problems trace back to one of three setup facts. Confirm these before troubleshooting anything else:

  • An IDP profile exists in the Console. Identity Provider profiles are managed at console.ecourtdate.com/idps. Confirm the profile for your sign-in identifier is present and saved.
  • The redirect URI is registered in the Identity Provider exactly. It must match https://{region}.api.ecourtdate.com/oauth/{yoursignin}/redirect, with no trailing slash and using https.
  • The region matches. Each IDP profile is limited to a single region. The {region} in the registered redirect URI must be the same region the IDP profile is configured for.

Where the Error Appears​

Sign-in failures show up in one of two places, and that tells you where to look:

  • On the Identity Provider's own page, before the user returns to eCourtDate. These are provider errors (redirect URI mismatch, user not assigned, consent needed). Fix them in the IDP.
  • Back at eCourtDate, as an error value on the return URL (for example .../logout?error=state), or as a bounce back to the sign-in page. These point to the login session or the token exchange.

Error Reference​

What you seeWhereLikely causeWhere to fix
Redirect URI mismatch (Azure AADSTS50011, Google redirect_uri_mismatch)IDP pageCallback URL not registered, trailing slash, or wrong regionIDP app redirect/callback settings
User not assigned / access denied (Azure AADSTS50105, Google admin_policy_enforced, access_denied)IDP pageUser is not assigned to the application, or a policy blocked itIDP app assignments
invalid_scope or a consent prompt that will not completeIDP pageA requested scope is not enabled, or admin consent was not grantedIDP API permissions and consent
?error=state or ?error=redirect_uri on the return URLeCourtDateThe login session expired or the sign-in took too longStart a fresh sign-in and finish within 5 minutes
?error=not_verified on the return URLeCourtDateThe email address on the account is not verifiedVerify the email at the provider, then sign in again
Sign-in returns to the login page without completingeCourtDateThe token exchange failed (wrong or expired client secret, or a reused code)IDP app credentials
Signed in, but in the wrong agenciesAfter sign-inGroup claim missing or misnamed, or overageIDP token/claims configuration
A user unexpectedly has Super AdminAfter sign-inThe roles claim contains security, admin, or root as a wordRename the role in the IDP

Redirect URI Mismatch​

Symptom: The Identity Provider shows an error that the redirect URI is invalid or does not match (Azure AADSTS50011, Google redirect_uri_mismatch), and the user never returns to eCourtDate.

Resolution: Register the redirect URI in your IDP exactly in this format:

https://{region}.api.ecourtdate.com/oauth/{yoursignin}/redirect

Common causes of a mismatch:

  • Not registered at all. The most frequent cause is that the URI was never added to the IDP application's allowed redirect (callback) list. Add it as an exact string.
  • Trailing slash. The URI must not end in a slash.
  • Protocol. The URI must use https, not http.
  • Region. Confirm the {region} value matches the region of the IDP profile. A URI for the wrong region will not match.
  • Sign-in identifier. Confirm {yoursignin} matches the sign-in identifier configured in the Console, including case and any hyphens.
  • Multiple regions. If you sign in from more than one region, each region's redirect URI must be registered separately in the IDP.

User Cannot Access the Application​

Symptom: The user authenticates at the Identity Provider but is bounced back with access_denied, "not assigned to this application" (Azure AADSTS50105), or admin_policy_enforced on Google.

Resolution: The user was blocked at the Identity Provider. This is an assignment or policy issue there.

  • Assign the user to the application. In Azure AD and Okta, users (or their group) must be explicitly assigned to the enterprise application. Add the user or group to the app's assignments.
  • Check conditional access and app policies. A conditional access policy, an unverified Google OAuth consent screen, or an organization app-access policy can block the user. Review the IDP's sign-in logs to see which policy denied the request.
  • Confirm the user is licensed and enabled at the Identity Provider.

Symptom: Authentication succeeds but group or profile data is missing, or the consent prompt returns invalid_scope or will not complete.

Resolution: Confirm the required scopes are enabled and consented for your provider:

  • Azure AD: The GroupMember.Read.All permission requires admin consent. An Azure AD administrator must grant consent in the Azure portal before this scope works. Without it, users sign in but no groups are returned.
  • Google Workspace: The group directory scopes (admin.directory.group.member.readonly, admin.directory.group.readonly) require domain-wide delegation configured in the Google Admin console.
  • Okta: Assign the groups scope to the application and configure the groups claim in the ID Token.
  • AWS Cognito: Enable openid, email, and profile on the app client.
  • All providers: Include openid, email, and profile at minimum. eCourtDate always requests these three. A missing openid scope prevents an ID token from being issued.

Sign-in Returns to the Login Page​

Symptom: The user authenticates at the Identity Provider, comes back to eCourtDate, and lands on the sign-in page again without an obvious error.

Resolution: eCourtDate completed authentication at the provider but could not exchange the authorization code for a token. Common causes:

  • Wrong or expired client secret. Provider client secrets expire. Azure AD (Microsoft Entra ID) secrets commonly expire after 6 to 24 months. Generate a new secret in the IDP and update it in the Console IDP profile.
  • Wrong client ID. Confirm the client ID in the Console profile matches the IDP application.
  • Reused or expired authorization code. Authorization codes are single-use and short-lived. Using the browser back button, refreshing the callback, or double-submitting triggers this. Start a fresh sign-in.
  • Stray whitespace. A trailing space or line break copied into the client ID or secret will fail the exchange.

Login Session Expired​

Symptom: The return URL carries ?error=state or ?error=redirect_uri.

Resolution: eCourtDate could not match the returning sign-in to the login it started. A sign-in must be completed within 5 minutes of starting it.

  • Took too long. If the user paused on the provider's login or MFA screen for more than 5 minutes, the login session expired. Start a fresh sign-in and complete it promptly.
  • Stale tab. A sign-in started in a tab left open too long, or opened in one tab and finished in another, will not match. Close extra tabs and start again from eCourtDate.
  • Blocked cookies. Strict privacy settings or blocked cookies can drop the session between the redirect and the return. Test in a standard browser profile or allow cookies for the sign-in domains.

Email Not Verified​

Symptom: The return URL carries ?error=not_verified.

Resolution: The account's email address is not marked verified at the provider. Verify the email at the Identity Provider, then sign in again.

Token Errors​

Symptom: Sign-in fails with a signature error, an "expired" or "not yet valid" token, or an issuer/audience error.

Resolution: These come from how the Identity Provider issues and signs tokens. Check the setting that matches the message:

  • Signature error. The provider rotated its signing keys, or is signing with an unexpected algorithm. Tokens should be signed with RS256 and be verifiable against the provider's published keys (the JWKS endpoint). Confirm the provider signs with RS256 and that its Well Known / JWKS URL is reachable.
  • Expired or "not yet valid" token. The token's exp (expiration) or nbf (not before) time did not line up with the current time. This is usually clock skew. Sync the provider and server clocks to NTP.
  • Issuer (iss) mismatch. The iss in the token does not match the provider endpoint configured in eCourtDate. On Azure, this is often a v1.0 versus v2.0 endpoint difference, or a tenant-specific issuer when the common endpoint was configured. Use the tenant-specific endpoints from your Authorization Flows provider section.
  • Audience (aud) mismatch. The aud claim does not match the configured client. Confirm the client ID in the Console profile matches the application that issued the token.

Signed In But in the Wrong Agencies​

Symptom: Users authenticate but are not assigned to the agencies you expect.

Resolution: Agency assignment comes from the group claims in the token, matched against the agency list configured on the IDP profile. Confirm the groups are present and named correctly.

  1. Verify the group name format. A group maps to an agency only when its name:

    • contains the text ecourtdate (case-insensitive),
    • begins with a single prefix character (use #) followed by the numeric agency reference,
    • places that prefix and reference before the first underscore.

    For agency reference 100, the group is #100_ecourtdate (a trailing label such as #100_ecourtdate_admin is allowed). See Scopes & Claims: Group Name Format.

  2. Include the leading prefix. eCourtDate drops the first character before the underscore, so 100_ecourtdate is read as reference 00, not 100. Always start the name with #.

  3. Use numeric agency references. Only numeric references can be mapped through groups. A group whose reference is not numeric is skipped.

  4. Check for an Azure group overage. When a user is a member of a large number of groups (Azure AD stops emitting the groups claim above roughly 200 groups for ID and access tokens), Azure returns a reference to the Microsoft Graph API instead of the group list, and the claim appears to be missing. Reduce the user's group count, or assign the app the specific #..._ecourtdate groups rather than "all groups."

  5. Confirm nested groups are expanded. Membership inherited through a nested (parent) group may not appear in the token unless the IDP is configured to include transitive membership. Add the user to the group directly, or enable transitive group claims.

  6. For Okta: Include the groups claim in the ID Token with a filter that emits the #..._ecourtdate groups. See Authorization Flows: Okta.

  7. Confirm the agency is active and in the right region. A group only assigns an agency that is active and in the IDP profile's region. An inactive agency, or one in another region, is not assigned even when its group matches.

  8. Inspect the token. Use your IDP's token debugger or a JWT inspection tool to confirm the group claims are present in the id_token.

User Reaches All or No Expected Agencies​

Symptom: A user lands in every agency on the IDP profile, or in none of the ones you expected.

Resolution: When the token carries no matching #..._ecourtdate groups, eCourtDate assigns the user to all agencies configured on the IDP profile. When it carries matching groups, the user is assigned only the agencies whose numeric references match.

  • User reached all agencies: the group claim did not reach eCourtDate or none of the groups matched the format. Confirm the groups claim is present and the names follow #{reference}_ecourtdate.
  • User reached only some agencies: only some matching groups were present, or some referenced agencies are inactive or in another region. Confirm a correctly named group exists for each expected agency and that the user is a member of each.

Unexpected Super Admin​

Symptom: A user unexpectedly has Super Admin across their agencies.

Resolution: Super Admin comes from the token's roles claim. If any role in that claim matches security, admin, or root as a whole word (case-insensitive), the user is made Super Admin in every agency they are assigned.

The keyword must stand as its own word, set off by a non-word character (space, hyphen, or period) or the start or end of the role name. An underscore does not separate words here:

  • admin, Security, ROOT, super-admin, and court admin trigger Super Admin.
  • Court_Security_Team does not trigger it, because the underscores keep Security from standing as its own word.

To resolve unintended elevation, rename the role in your Identity Provider so these words do not stand alone. To grant Super Admin intentionally, include a role such as admin.

New or Duplicate Profile Created​

Symptom: A user who already had an eCourtDate account signs in and appears as a new, separate profile.

Resolution: eCourtDate matches an SSO user to an existing profile by email address. If the token's email does not match the email on the existing profile, a new profile is created instead.

  • Changed email at the provider. If the user's email at the Identity Provider changed (for example a name change or a switch of email domain), it no longer matches the existing eCourtDate profile. Align the emails.
  • Missing email claim. Confirm the email scope is requested and the provider releases the email claim. Without it, the sign-in cannot resolve or create the profile.

Provider-Specific Notes​

  • Azure AD (Microsoft Entra ID): GroupMember.Read.All needs admin consent. Client secrets expire and are a frequent cause of sign-in returning to the login page. Watch for group overage on users in many groups.
  • Google Workspace: Group directory scopes need domain-wide delegation. An unverified OAuth consent screen can block users with admin_policy_enforced.
  • Okta: The groups claim must be added to the ID Token and filtered to the #..._ecourtdate groups, and the app must be assigned to the user or group.
  • AWS Cognito: Confirm the Cognito domain is deployed and the app client has openid, email, and profile enabled. Endpoints are region-specific.

Getting Help​

To request help, 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 (Region, Agency, Feature, and a Description). 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 and region of the IDP profile
  • The Identity Provider (Azure AD, Google, Okta, Cognito, or custom)
  • The error shown on the return URL, or the provider error code (for example AADSTS50011)
  • The decoded id_token claims with any tokens or secrets redacted
  • The approximate time of the failed sign-in

Check status.ecourtdate.com for platform incidents.

danger

Never share OAuth client secrets or raw tokens in a support ticket or logs. Redact them and share only the decoded, non-sensitive claims.

See Also​