OAuth Troubleshooting

This page is in order of symptom: what an administrator or a user sees. Each section gives the cause and the fix. For a step-by-step method to find the cause of a failure, see OAuth Debugging. For the settings of each provider, see Provider Settings.

Before Starting

Make sure that these conditions are true before other troubleshooting:

• The IDP profile is in the correct region. Open IDPs in the Console. A staging profile works in staging only, and a production profile works in production only.
• The user opens the correct URL. Use the Sign-in URL or the Console Sign-in URL exactly as the profile page shows it.
• The identity provider has each Redirect URL. The client at the identity provider must have the Redirect URL exactly as the profile page shows it. For Console sign-in, it must also have the Console Redirect URL.
• The change has had time to apply. After a change to the profile, the Agency app can use the old settings for up to 15 minutes. Wait 15 minutes before a new test.

Where the Error Shows

• On the page of the identity provider, before the user comes back to eCourtDate. The identity provider stopped the sign-in. Fix the problem at the identity provider.
• In the Agency app, as an error value in the URL, an error message on the sign-in page, or a sign-in that starts again.
• In the Console, as the Console sign-in page again, without a message. eCourtDate logs the reason. Open a support ticket with the time of the sign-in.

Error Reference

Symptom	Where	Cause	Fix
The Sign-in URL opens the standard eCourtDate sign-in	Agency app	No profile has the Sign-in Path in this region, or the profile has no Client ID, Client Secret, or Token URL	Standard Sign-in Opens
"An error occurred while logging in" right after the Sign-in URL opens	Agency app	The profile has no Authorization URL	Error Before the Identity Provider
Redirect URI mismatch, such as Entra AADSTS50011 or Google redirect_uri_mismatch	Identity provider	The Redirect URL is not registered exactly	Redirect URI Mismatch
The user is not assigned or access is denied, such as Entra AADSTS50105, Google admin_policy_enforced, or access_denied	Identity provider	The user is not assigned to the client, or a policy blocked the user	User Is Blocked
invalid_scope, or a consent prompt that does not complete	Identity provider	A scope is not turned on, or consent is not given	Scope and Consent Problems
The URL ends with /logout?error=state	Agency app	The return to eCourtDate had no state value	Error URLs
The URL ends with /logout?error=redirect_uri	Agency app	The sign-in took more than 5 minutes, or the state was used before	Error URLs
The browser goes back to the identity provider after the sign-in, or the sign-in repeats	Agency app	The Token URL did not return an ID token	Sign-in Starts Again
"An error occurred while logging in" after the return from the identity provider	Agency app	The ID token has no valid email claim, or the session value was used before	Error After the Return
The Console sign-in page shows again	Console	An ID token check or a user check failed	Console Sign-in Fails
"Not Found" at the Console Sign-in URL	Console	No profile has the Sign-in Path, or the profile has no Authorization URL	Console Not Found
The user has the wrong agencies	After sign-in	The groups claim is missing or the names do not follow the format	Wrong Agencies
The user has the wrong roles	After sign-in	The roles claim or the Default Role	Wrong Roles
A user is Super Admin unexpectedly	After sign-in	A role in the roles claim contains security, admin, or root as a word	Unexpected Super Admin
A user has a new, second eCourtDate user	After sign-in	The email address in the ID token changed	New or Duplicate User
"Credentials Check Failed!"	IDP profile page	The Token URL did not accept the client credentials	Credentials Check Failed
An error or a warning in the OIDC Configuration Check	IDP profile page	The discovery settings are not correct	OIDC Configuration Check Messages
An email "(ACTION MAY BE REQUIRED) IDP ... Test Failed"	Alert Contacts	The monthly credentials test failed	Monthly Test Notice

The Sign-in URL Opens the Standard eCourtDate Sign-in

Symptom: The Agency app Sign-in URL opens the standard eCourtDate sign-in, not the identity provider.

Cause: The eCourtDate API found no usable IDP profile, so it used the standard sign-in.

Fix:

• Make sure that a profile has this Sign-in Path in the region of the URL. For https://staging.ecourtdate.com/oauth/{sign-in-path}, the profile must have the Region staging.
• Make sure that the profile has a Client ID, a Client Secret, and a Token URL. Without one of these values, the API uses the standard sign-in.
• After a change, wait 15 minutes. The Agency app can use the old result for up to 15 minutes.

Error Message Before the Identity Provider Opens

Symptom: The Agency app sign-in page shows "An error occurred while logging in" and the browser does not go to the identity provider.

Cause: The profile has no Authorization URL, so eCourtDate cannot send the browser to the identity provider.

Fix: Enter the Authorization URL and click Save changes. Wait 15 minutes, then test again.

Redirect URI Mismatch

Symptom: The identity provider shows an error that the redirect URI is not valid or does not match, such as Entra AADSTS50011 or Google redirect_uri_mismatch. The user does not come back to eCourtDate.

Cause: The Redirect URL that eCourtDate sent is not on the list of the client at the identity provider.

Fix: Copy the URLs from the profile page and add them to the client exactly:

• Agency app: the Redirect URL, https://{region}.api.ecourtdate.com/oauth/{sign-in-path}/redirect.
• Console: the Console Redirect URL, https://console.ecourtdate.com/oauth/{sign-in-path}/redirect.

Then check for these errors:

• Wrong environment. A staging profile and a production profile have different Redirect URLs. Add the Redirect URL of each profile to the client of that profile.
• Console URL missing. A client that works for the Agency app fails for the Console until it has the Console Redirect URL.
• Uppercase letters in the Sign-in Path. The Agency app sends the Sign-in Path in lowercase. Change the Sign-in Path to lowercase, and register the new Redirect URLs.
• Changed Sign-in Path. A change to the Sign-in Path changes all Redirect URLs. Register the new URLs.
• Extra characters. Do not add a slash at the end. Use https, not http.
• Wrong platform in Entra ID. Add the Redirect URLs under the Web platform, not under Single-page application.

User Is Blocked at the Identity Provider

Symptom: The user signs in at the identity provider and then sees an error. Examples are access_denied, Entra AADSTS50105 (the user is not assigned to the application), and Google admin_policy_enforced.

Cause: The identity provider blocked the user. The problem is an assignment or a policy at the identity provider.

Fix:

• Assign the user. In Entra ID and Okta, assign the user or a group of the user to the application.
• Check the policies. A conditional access policy or an app access policy can block the user. The sign-in logs of the identity provider show which policy blocked the user.
• Check the account. Make sure that the account of the user is active at the identity provider.

Scope and Consent Problems

Symptom: The consent prompt shows invalid_scope or does not complete. Or the sign-in completes, but the ID token has no email or no groups claim.

Fix:

• All providers: The Authorization Scope must contain openid, profile, and email. eCourtDate adds these scopes when they are missing. Remove scopes that the client does not permit.
• Microsoft Entra ID: If users cannot give consent, an administrator grants consent for the organization. Add email as an optional claim for the ID token. eCourtDate needs no Microsoft Graph permission other than the default User.Read.
• Google Workspace: Set the User type of the OAuth consent screen to Internal.
• Okta: Add groups to the Authorization Scope, and set the groups claim filter on the Sign On tab.
• AWS Cognito: Select openid, email, and profile on the app client.

Error URLs (?error=state and ?error=redirect_uri)

Symptom: After the identity provider, the browser goes to https://{region}.ecourtdate.com/logout?error=state or https://{region}.ecourtdate.com/logout?error=redirect_uri.

Cause and fix:

• error=state: The return to the Redirect URL had no state value. The sign-in started at the identity provider, not at eCourtDate. Start each sign-in from the eCourtDate Sign-in URL. To show eCourtDate on the app portal of the identity provider, use the Sign-in URL as the link of the app.
• error=redirect_uri: eCourtDate did not find the state value. The sign-in took more than 5 minutes, or the browser sent the same return two times. Start a new sign-in from the Sign-in URL and complete it in 5 minutes. Do not refresh the page or use the Back button during the sign-in.

Sign-in Starts Again After the Identity Provider

Symptom: The user signs in at the identity provider. Then the browser goes back to the identity provider, or the sign-in repeats many times.

Cause: eCourtDate sent the authorization code to the Token URL, but did not get an ID token. The Agency app then starts a new sign-in. If the session at the identity provider is still active, the sign-in can repeat without a stop.

Fix:

• Client Secret. Make sure that the Client Secret is correct and not expired. Create a new secret at the identity provider if necessary, and enter it in the profile.
• Client ID. Make sure that the Client ID is the ID of the client that has this Redirect URL.
• Client authentication. The client must accept the client secret with HTTP Basic authentication (client_secret_basic).
• Token URL. Make sure that the Token URL is the token_endpoint from the discovery document.
• Client type. Register a web application. A single-page application or a native application needs PKCE, which eCourtDate does not use.
• openid scope. Without the openid scope, the Token URL returns no ID token. eCourtDate adds openid to the Authorization Scope, so check that the client permits it.
• Extra spaces. Remove spaces or line breaks from the start and the end of the Client ID and the Client Secret.
• Slow Token URL. eCourtDate waits 15 seconds for the Token URL.

Error Message After the Return to the Agency App

Symptom: The user comes back from the identity provider. The Agency app sign-in page shows "An error occurred while logging in."

Cause and fix:

• No email claim. The ID token has no email claim, or the value is not a valid email address. Add the email claim at the identity provider. On Entra ID, add email as an optional claim for the ID token. The IDP Last Sign In panel on the profile shows the claims that eCourtDate got.
• Used session value. The sign-in session value is for one use only. A refresh of the page after the return shows this message. Start a new sign-in from the Sign-in URL.

Console Sign-in Page Shows Again

Symptom: The user signs in at the identity provider through the Console Sign-in URL. Then the Console shows its sign-in page again, without a message.

Cause: A check in the Console failed. eCourtDate logs the reason, but the page does not show it.

Fix: Check each of these causes:

• OIDC Configuration Check. Open the profile and correct each error in the OIDC Configuration Check. Without a discovery document and signing keys, the Console cannot verify the ID token.
• Signature. The ID token must be signed with a key from the JWKS URL. Use RS256.
• Time. The exp, nbf, and iat claims must be valid at the current time. The Console permits a clock difference of 60 seconds. Make sure that the clocks of the identity provider are correct.
• Issuer. The iss claim must be the same as the issuer in the discovery document. On Entra ID, use tenant-specific v2.0 URLs in all fields. On Okta, use the URLs of one authorization server in all fields.
• Audience. The aud claim must contain the Client ID of the profile.
• Nonce or state. The sign-in must start and finish in the same browser. Close other tabs, and allow cookies for console.ecourtdate.com. Start a new sign-in from the Console Sign-in URL.
• No email claim. Add the email claim at the identity provider.
• No eCourtDate user. The Console does not create users. Sign in to the Agency app first, or add the user in eCourtDate.
• No Console access. The user must be Super Admin in an agency, or have a role with consoleuser, security, or root. See Console Access.
• eCourtDate staff or partner account. These accounts cannot sign in through the identity provider of an agency. They use the standard eCourtDate sign-in.

To get the reason that eCourtDate logged, open a support ticket. Give the time of the sign-in and the email address of the user.

"Not Found" at the Console Sign-in URL

Symptom: The Console Sign-in URL shows a "Not Found" page.

Cause and fix:

• No profile. No IDP profile has the Sign-in Path in the URL. Copy the Console Sign-in URL from the profile page again. A change to the Sign-in Path changes the URL.
• No Authorization URL. The profile has no Authorization URL. Enter it and click Save changes.

Signed In With the Wrong Agencies

Symptom: A user signs in to the Agency app but does not have the expected agencies.

Cause: eCourtDate selects agencies from the groups claim and the Enabled Agencies of the profile. See Agency Access.

Fix:

1. Read the claims. Open the profile and read the IDP Last Sign In panel. Make sure that the ID token has a groups claim with the expected group names.
2. Check the group name format. The name must contain ecourtdate and start with one prefix character, such as #. The numeric agency reference must come before the first underscore. For the reference 100, the group name is #100_ECOURTDATE. See Group Name Format.
3. Include the prefix character. eCourtDate removes the first character before it reads the reference. It reads 100_ECOURTDATE as the reference 00.
4. Check the Enabled Agencies. A group selects an agency only when the agency is in the Enabled Agencies of the profile. The agency must also be active and in the region of the profile.
5. Entra ID sends object IDs. By default, Entra ID sends group object IDs, not names. Select sAMAccountName or Cloud-only group display names for the groups claim. See Microsoft Entra ID.
6. Entra ID group overage. When a user is in more than 200 groups, Entra ID sends no group list in the token. Select Groups assigned to the application for the groups claim, and assign only the #..._ECOURTDATE groups to the application.
7. Nested groups. The token can leave out a membership that comes through a parent group. Add the user to the group directly.
8. Okta filter. The regex #\d+_ECOURTDATE.* is case-sensitive. Name the groups with ECOURTDATE in uppercase.
9. AWS Cognito. Cognito sends groups in cognito:groups. eCourtDate reads only groups. See AWS Cognito.
10. Google Workspace. Google ID tokens have no groups claim. Each user gets all of the Enabled Agencies.

The User Gets All Agencies or No Agencies

Symptom: A user gets all of the Enabled Agencies, or gets no agency from the sign-in.

Cause and fix:

• All Enabled Agencies: The ID token has no groups claim, or no group follows the Group Name Format. Then eCourtDate gives all of the Enabled Agencies. Add correctly named groups to the groups claim.
• No agency: At least one group follows the format, but no group has the reference of a usable Enabled Agency. A usable agency is active and in the region of the profile. Add the agency to the Enabled Agencies, or correct the reference in the group name.

Agency Access Is Not Removed

Symptom: A user leaves a group at the identity provider, but still has the agency in eCourtDate.

Cause: A sign-in adds agencies. It never removes an agency.

Fix: Remove the agency from the user in eCourtDate.

Signed In With the Wrong Roles

Symptom: A user has the wrong roles in an agency after a sign-in.

Cause and fix:

• roles claim present: The roles from the claim replace the roles of the user at each sign-in. Correct the roles at the identity provider. Use role names that exist in the agency.
• No roles claim, new agency: The user gets the Default Role of the profile. Change the Default Role, or send a roles claim.
• No roles claim, existing agency: The roles of the user do not change. Change the roles in eCourtDate.

Unexpected Super Admin

Symptom: A user is Super Admin in the agencies of the sign-in, but the agency did not plan this.

Cause: A role in the roles claim contains security, admin, or root as a standalone word. Uppercase and lowercase letters are the same. A space, a hyphen, a period, or the start or end of the name separates words. An underscore does not separate words.

• admin, Security, ROOT, super-admin, and court admin give Super Admin.
• Court_Security_Team does not give Super Admin.

Fix:

1. At the identity provider, change the role name so that these words do not stand alone.
2. In eCourtDate, turn off Super Admin for the user. A sign-in never turns off Super Admin.

New or Duplicate User

Symptom: A user who already had an eCourtDate user signs in and gets a new, second user.

Cause: eCourtDate finds the user by the email claim. The email address in the ID token is different from the email address of the existing user.

Fix:

• Changed email address. If the email address of the user changed at the identity provider, change the email address of the eCourtDate user to agree.
• Different claim value. Some identity providers put a different address in the email claim, such as an alias. Read the IDP Last Sign In panel to see the value that eCourtDate got.

Credentials Check Failed

Symptom: The top of the profile page shows "Credentials Check Failed!" with one of these messages.

Message	Cause	Fix
"Missing client_id in IDP data"	The Client ID is empty	Enter the Client ID.
"Missing client_secret in IDP data"	The Client Secret is empty	Enter the Client Secret.
"Missing token_url in IDP data"	The Token URL is empty	Enter the Token URL.
"Unable to validate IDP credentials"	The Token URL did not accept the request	See the next list.
"Missing access_token in token response"	The Token URL answered without an access token	Make sure that the Token URL is correct.
"Test IDP Failed"	The Console could not connect to the Token URL	Make sure that the Token URL is correct and uses HTTPS.

For "Unable to validate IDP credentials":

• The check uses the client_credentials grant. A client that does not permit this grant always fails the check. For this type of client, a test sign-in is the correct check of the Client ID and the Client Secret.
• Make sure that the Client ID and the Client Secret are correct, and that the secret is not expired.

OIDC Configuration Check Messages

The OIDC Configuration Check shows errors and warnings below the profile form. An error stops every Console sign-in. A warning shows a setting that can cause sign-ins to fail.

Message starts with	Type	Fix
"No Well Known URL or Base URL is set"	Error	Enter the Well Known URL.
"Unable to fetch the OIDC discovery document"	Error	Make sure that the Well Known URL is correct and that the internet can reach it.
"No issuer could be resolved from the discovery document"	Error	The URL does not point to a discovery document. Enter the correct Well Known URL.
"The discovered issuer contains the literal {tenantid} placeholder"	Error	The URL is a Microsoft multi-tenant URL. Use the URLs with the tenant ID.
"Unable to fetch or parse the JWKS signing keys"	Error	Make sure that the jwks_uri in the discovery document is reachable.
"The discovery document does not advertise a jwks_uri"	Error	Use the discovery document of an OpenID Connect provider that publishes signing keys.
"... uses an Azure multi-tenant endpoint (common/organizations/consumers)"	Warning	Use the URLs with the tenant ID.
"... points at the Azure v1.0 endpoint"	Warning	Use v2.0 URLs in all fields.
"Authorization URL (...) does not match the authorization_endpoint ..."	Warning	Copy the Authorization URL from the authorization_endpoint in the discovery document.
"Token URL (...) does not match the token_endpoint ..."	Warning	Copy the Token URL from the token_endpoint in the discovery document.
"The discovery document lists neither an email scope nor an email claim"	Warning	Make sure that the ID token contains the email claim. On Entra ID, add email as an optional claim.

Monthly Credentials Test Notice

Symptom: The Alert Contacts get an email with the subject (ACTION MAY BE REQUIRED) IDP {sign-in-path} Test Failed. The email gives the Sign-in Path, a link to the profile, the region, the last active time, and the status.

Cause: On the first day of each month, eCourtDate tests the credentials of each profile that has had a sign-in. The test sends the same client_credentials request as the Credentials Check. The test failed.

Fix:

1. Read the status in the email.
2. Make sure that the Client Secret is not expired. If it is expired, create a new secret and enter it in the profile.
3. Make sure that the client still exists at the identity provider.
4. If the client does not permit the client_credentials grant, the test fails each month. Confirm with a test sign-in that sign-in works.

Sign-out Does Not Return to eCourtDate

Symptom: After a sign-out from the Agency app, the user stays on a page of the identity provider.

Cause and fix:

• eCourtDate sends the browser to the End Session URL with the client_id and returnTo parameters. Only a provider that reads returnTo sends the user back to the Logout URL.
• If the provider has a list of sign-out redirect URLs, add the Logout URL of the profile to it.
• Google does not have an end-session endpoint. Enter the Logout URL of the profile as the End Session URL.
• A Console sign-out does not use the End Session URL. The session at the identity provider stays active.

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 Console attaches the current page. Updates show under My Tickets in the same panel.

In the description, give:

• The Sign-in Path and the region of the IDP profile
• The application: Agency app or Console
• The identity provider, such as Entra ID, Google Workspace, Okta, AWS Cognito, or a different provider
• The error in the URL, the message on the page, or the error code of the provider, such as AADSTS50011
• The time of the failed sign-in and the email address of the user
• The ID token claims from the IDP Last Sign In panel, with secrets removed

Check status.ecourtdate.com for platform incidents.

danger

Do not put a Client Secret or a raw token in a support ticket or a log. Remove them, and give only the claims that are not secret.

See Also

• OAuth / SSO: setup steps, IDP profile fields, and FAQs
• OAuth Debugging: a step-by-step method to find the cause of an SSO failure
• Provider Settings: client registration and URLs for each provider
• Sign-in Flows: the Agency app and Console flows, and the ID token checks
• Scopes & Claims: scopes, group names, roles, and user provisioning
• Token Lifecycle: time limits, sessions, sign-out, and client secrets
• OAuth Security: security controls and the production checklist