Skip to main content

OAuth Debugging

This page gives a step-by-step method to find the cause of an SSO sign-in failure. Do the steps in order. When the error is known, find the fix on the OAuth Troubleshooting page.

Step 1: Reproduce the Failure​

Remove old sessions and old sign-in values before the test.

  • Sign in from a private browser window, so that no old cookie or session has an effect.
  • Use a test user whose groups and roles at the identity provider are known.
  • Write down the application (Agency app or Console), the Sign-in Path, and the region. Each IDP profile works in one region only.
  • Start the sign-in from the Sign-in URL or the Console Sign-in URL on the profile page. Do not start it from the identity provider.

Step 2: Record the Error​

Write down where the failure shows, because that tells where to look.

  • On the page of the identity provider, before the return to eCourtDate: copy the error and error_description values from the URL, and the error code of the provider. For example, AADSTS50011 is an Entra ID redirect URI mismatch.
  • In the Agency app URL: /logout?error=state means that the return had no state value. /logout?error=redirect_uri means that the sign-in took more than 5 minutes, or the state was used before.
  • In the Agency app, as a new sign-in: the browser goes back to the identity provider after the sign-in. eCourtDate did not get an ID token from the Token URL. Check the Client ID and the Client Secret.
  • In the Agency app, as an error message: "An error occurred while logging in." Before the identity provider opens, the profile has no Authorization URL. After the return, the ID token has no valid email claim.
  • In the Console: the Console sign-in page shows again, without a message. eCourtDate logs the reason. Write down the time of the sign-in.

Find the result in the Error Reference table.

Step 3: Read the ID Token Claims​

When the sign-in reaches eCourtDate but the user gets the wrong agencies or roles, the cause is in the ID token claims.

Open the IDP profile in the Console and read the IDP Last Sign In panel. It shows the authorized scopes and the ID token claims of the most recent Agency app sign-in, for 24 hours. For a Console sign-in, decode the ID token in the token tool of the identity provider.

Make sure that:

  • email is present and is the address of the eCourtDate user. eCourtDate finds or creates the user by this address. A missing or changed address causes a failed sign-in or a new, second user.
  • groups contains the expected group names, in the format #{agency-reference}_ECOURTDATE. The reference contains only digits, and the name starts with a prefix character such as #. For example, #100_ECOURTDATE. If the claim has object IDs and not names, set the group name format at the identity provider.
  • roles contains security, admin, or root as a standalone word only when Super Admin is necessary. These words make the user Super Admin.

For a Console sign-in, also make sure that:

  • iss is the same as the issuer in the discovery document. On Entra ID, use tenant-specific v2.0 URLs, not common.
  • aud contains the Client ID of the profile.
  • exp, nbf, and iat agree with the current time. A difference of more than 60 seconds points to a clock problem.
danger

Decode tokens only in a tool that the agency trusts. Do not put a raw token in a support ticket. Before the claims go into a ticket, remove the secrets.

Step 4: Read the Sign-in Logs of the Provider​

When the identity provider stops the sign-in, the logs of the provider give the reason:

  • Microsoft Entra ID: The Sign-in logs in the Microsoft Entra admin center show the reason and the AADSTS code. For an expired secret, check Certificates & secrets on the app registration.
  • Google Workspace: Check the OAuth consent screen in the Google Cloud console, and the audit logs in the Google Admin console. admin_policy_enforced points to an app access policy.
  • Okta: Check the System Log for the sign-in. Check Applications > the application > Sign On > OpenID Connect ID Token for the groups claim. Make sure that the user or a group of the user is assigned to the application.
  • AWS Cognito: Check the app client of the user pool for the OAuth scopes and the callback URLs. Make sure that the user pool has a domain.

Step 5: Check the IDP Profile​

Make sure that the profile in eCourtDate agrees with the identity provider.

  • Open the profile in IDPs.
  • Read the Credentials Check at the top of the page. A client that does not permit the client_credentials grant fails this check, also with correct credentials.
  • Read the OIDC Configuration Check. Correct each error and each warning.
  • Make sure that the Client ID and the Client Secret are the current values at the identity provider.
  • Make sure that the Region of the profile agrees with the URL that the user opened.
  • Make sure that the URLs agree with the provider section in Provider Settings.
  • Read Last active in the header. It changes at each Agency app sign-in that gets an ID token. If it does not change during the tests, the sign-ins stop before the token step. A Console sign-in does not change Last active.
  • After a change, wait 15 minutes before a new Agency app test.

Step 6: Request Help​

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

In the description, give:

  • The Sign-in Path, the region, the application, and the identity provider
  • The error in the URL, the message on the page, or the error code of the provider
  • The time of the failed sign-in and the email address of the user
  • The ID token claims, with secrets removed

Check status.ecourtdate.com for platform incidents.

See Also​