Sign-in Flows

eCourtDate uses the OAuth 2.0 Authorization Code flow with OpenID Connect. The Agency app and the Console each have their own sign-in flow and their own Redirect URL. Both flows use the settings of the same IDP profile.

Redirect URLs by Environment

The identity provider sends each sign-in back to a Redirect URL. Register each Redirect URL that the profile uses on the client at the identity provider.

Environment	Sign-in URL	Redirect URL
Staging Agency app	https://staging.ecourtdate.com/oauth/{sign-in-path}	https://staging.api.ecourtdate.com/oauth/{sign-in-path}/redirect
Production Agency app	https://{region}.ecourtdate.com/oauth/{sign-in-path}	https://{region}.api.ecourtdate.com/oauth/{sign-in-path}/redirect
Console	https://console.ecourtdate.com/oauth/{sign-in-path}	https://console.ecourtdate.com/oauth/{sign-in-path}/redirect

A staging profile and a production profile each need their own client and their own Redirect URL. The Console uses the profile whose Sign-in Path is in the Console Sign-in URL.

Agency App

1. The user opens the Sign-in URL, https://{region}.ecourtdate.com/oauth/{sign-in-path}.
2. The Agency app asks the eCourtDate API for the authorization URL. The API finds the IDP profile that has this Sign-in Path in this region.
3. The API sends the browser to the Authorization URL, with the parameters in the next table.
4. The user signs in at the identity provider.
5. The identity provider sends the browser to the Redirect URL, https://{region}.api.ecourtdate.com/oauth/{sign-in-path}/redirect. The URL contains a code and the state.
6. The API checks the state. The state is valid for 5 minutes and for one use only.
7. The API sends the code to the Token URL. It authenticates with the Client ID and the Client Secret.
8. The API reads the claims in the ID token. It records the sign-in in Last active and IDP Last Sign In on the profile.
9. The API sends the browser to https://{region}.ecourtdate.com/login?state={state}.
10. The Agency app gets an eCourtDate session token. eCourtDate finds the user by email, or creates the user. Then it applies the agencies and the roles. See Scopes & Claims.
11. The session token is valid for 24 hours.

If no profile has the Sign-in Path in this region, step 2 opens the standard eCourtDate sign-in. A profile without a Client ID, a Client Secret, or a Token URL gives the same result.

Authorization Request

The API sends these parameters to the Authorization URL:

Parameter	Value
client_id	The Client ID of the profile
response_type	code
response_mode	query
scope	The Authorization Scope of the profile, with openid, profile, and email added when they are not in it
redirect_uri	The Redirect URL of the profile
state	A random value of 40 characters
nonce	A random UUID
sign_in	The Sign-in Path, for eCourtDate use
base_uri	The address of the Agency app, for eCourtDate use

Token Request

The API sends a form-encoded POST request to the Token URL. The request authenticates with HTTP Basic authentication: the Client ID is the user name and the Client Secret is the password. The API waits 15 seconds for a response.

Parameter	Value
grant_type	authorization_code
code	The code from the identity provider
redirect_uri	The Redirect URL of the profile
scope	The Token Scope of the profile, with openid, profile, and email added when they are not in it
region	The eCourtDate region, for eCourtDate use

Results of the Agency App Flow

Result	What the user sees
Sign-in is successful	The Agency app opens.
The return has no state	The browser goes to https://{region}.ecourtdate.com/logout?error=state.
The state is expired or used	The browser goes to https://{region}.ecourtdate.com/logout?error=redirect_uri.
The Token URL returns no ID token	The browser goes back to the Sign-in URL, which starts a new sign-in.
The ID token has no valid email claim	The sign-in page shows "An error occurred while logging in."

Console

1. The user opens the Console Sign-in URL, https://console.ecourtdate.com/oauth/{sign-in-path}. The Console finds the profile by its Sign-in Path only. It does not look at the region. If no profile has this Sign-in Path, the Console shows a "Not Found" page.
2. The Console keeps a state and a nonce in the browser session. It sends the browser to the Authorization URL. The scope is always openid profile email, and the redirect_uri is the Console Redirect URL.
3. The user signs in at the identity provider.
4. The identity provider sends the browser to the Console Redirect URL with a code and the state.
5. The Console checks that the state is the same as the value in the browser session. The value is for one use only.
6. The Console sends the code to the Token URL. It authenticates with the Client ID and the Client Secret (HTTP Basic).
7. The Token URL returns the ID token.
8. The Console reads the discovery document from the Well Known URL or the Base URL. Then it reads the signing keys from the JWKS URL in the document.
9. The Console verifies the ID token. Then it finds the user by the email claim and checks the Console access of the user.
10. The Console opens the Dashboards page.

If a check fails, the Console shows its sign-in page again. The page does not show the reason. eCourtDate logs the reason for each failed Console sign-in. To get the reason, open a support ticket with the time of the sign-in and the email address of the user.

ID Token Checks in the Console

Check	Rule
Signature	The signature is correct for a key from the JWKS URL. A key without an alg value is read as RS256.
exp, nbf, iat	The token is valid at the current time. The Console permits a clock difference of 60 seconds.
iss	The issuer is the same as the issuer in the discovery document.
aud	The audience contains the Client ID of the profile.
nonce	The nonce is the same as the nonce that the Console sent.
email	The claim is present.

User Checks in the Console

Check	Rule
The user exists	An eCourtDate user has the email address from the ID token. The Console does not create users.
Console access	The user has Console access in at least one agency. See Console Access.
Account type	The user is not an eCourtDate staff account or a partner account. These accounts use the standard eCourtDate sign-in.

Discovery Document

The Console finds the discovery document in this order:

1. The Well Known URL. If the URL does not contain .well-known, the Console adds /.well-known/openid-configuration.
2. The Base URL, with /.well-known/openid-configuration added. For a Microsoft Entra ID Base URL without /v2.0, and v2.0 Authorization and Token URLs, the Console reads the v2.0 discovery document.

The Console keeps the discovery document and the signing keys for 10 minutes.

Sign-out

Agency app: When a user signs out, eCourtDate ends the eCourtDate session. Then it sends the browser to the End Session URL with these parameters:

Parameter	Value
client_id	The Client ID of the profile
returnTo	The Logout URL, https://{region}.ecourtdate.com/logout

The identity provider ends its session. A provider that reads the returnTo parameter then sends the user to the Logout URL.

Console: Sign-out ends the Console session. The Console does not send the user to the End Session URL of the profile, so the session at the identity provider stays active.