Skip to main content

OAuth Troubleshooting

This page covers common issues encountered when configuring OAuth / SSO with eCourtDate and how to resolve them.

Redirect URI Mismatch​

Symptom: The Identity Provider returns an error indicating the redirect URI is invalid or does not match.

Resolution: Ensure the redirect URI registered in your IDP exactly matches the following format:

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

Common causes of mismatch:

  • Trailing slashes -- The URI must not have a trailing slash
  • Protocol -- Must be https, not http
  • Region -- Verify the correct eCourtDate region is specified
  • Sign-in identifier -- Confirm {yoursignin} matches the value configured in the eCourtDate Console

Scope Issues​

Symptom: Authentication succeeds but group information or profile data is missing.

Resolution: Verify all required scopes are configured 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 will work.
  • Google Workspace -- Group-related scopes (admin.directory.group.member.readonly, admin.directory.group.readonly) require domain-wide delegation to be configured in the Google Admin console.
  • Okta -- Ensure the groups scope is assigned to the application.
  • AWS Cognito -- Verify openid, email, and profile scopes are enabled on the app client.

Group Assignment Not Working​

Symptom: Users authenticate successfully but are not assigned to the expected agencies.

Resolution:

  1. Verify group name format -- Group names must follow the pattern {AgencyReference}_ECOURTDATE (case-insensitive). For example, if the agency reference is municipal-court-123, the group name should be municipal-court-123_ECOURTDATE.

  2. For Okta -- Confirm the "groups" claim is included in the ID Token with a regex filter of .*_ECOURTDATE. This is configured in the Okta application's token claims settings.

  3. Check group membership -- Verify that users are actually members of the relevant group in the Identity Provider. Group membership changes may not take effect until the user's next sign-in.

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

User Gets Default Agency Only​

Symptom: Users sign in but are only assigned to the Default Agency, not their expected agencies.

Resolution: This typically means the groups claim is not being included in the token. Check the following:

  • Token claims configuration -- Verify the IDP is configured to pass group claims in the id_token
  • Scope authorization -- Confirm the scopes required for group access have been authorized (see Scopes & Claims)
  • Token inspection -- Use your IDP's token debugger to confirm groups are present in the token payload
  • Group name format -- Ensure group names match the {AgencyReference}_ECOURTDATE pattern

Role Mapping​

Symptom: A user is unexpectedly granted Super Admin privileges.

Resolution: Role names containing any of the following keywords (case-insensitive) are automatically elevated to Super Admin status:

  • SECURITY
  • ADMIN
  • ROOT

If a user has a role with any of these keywords in the name, they will receive Super Admin designation. To resolve this, rename the role in your Identity Provider to remove the keyword. For example, rename Court_Security_Team to Court_Sec_Team if Super Admin access is not intended.

Additional Resources​

For further debugging assistance, see the OAuth Debugging guide.