OAuth / SSO

Single sign-on (SSO) lets users sign in to eCourtDate with their account at the identity provider of their organization. Microsoft Entra ID, Google Workspace, Okta, and AWS Cognito are examples of identity providers. eCourtDate uses OpenID Connect (OIDC) with the OAuth 2.0 Authorization Code flow. The identity provider controls passwords and multi-factor authentication (MFA).

SSO works in two eCourtDate applications:

Application	Users	Sign-in URL
Agency app	Agency staff	https://{region}.ecourtdate.com/oauth/{sign-in-path}
Console	Users with Console access, such as Super Admins	https://console.ecourtdate.com/oauth/{sign-in-path}

An IDP profile in the Console holds the settings for one client at the identity provider. Each IDP profile works in one eCourtDate region only. Manage IDP profiles under IDPs in the Console.

Separate Configuration for Staging, Production, and the Console

Each environment needs its own configuration

Staging, production, and the Console each need their own configuration. A configuration for one environment does not sign users in to a different environment.

Environment	IDP profile in the Console	Redirect URL to register at the identity provider
Staging	A profile with the Region staging	https://staging.api.ecourtdate.com/oauth/{sign-in-path}/redirect
Production	A profile with the production region of the agency, such as us-east	https://{region}.api.ecourtdate.com/oauth/{sign-in-path}/redirect
Console	The profile whose Sign-in Path is in the Console Sign-in URL	https://console.ecourtdate.com/oauth/{sign-in-path}/redirect

• Staging and production: Create one IDP profile for staging and a different IDP profile for production. eCourtDate finds a profile by its Sign-in Path and its region. A staging profile does not work in production, and a production profile does not work in staging.
• Separate clients: At the identity provider, register one client (application) for staging and a different client for production. Each client has its own Client ID, Client Secret, and Redirect URL.
• Console: The Console has its own Redirect URL. Add the Console Redirect URL to the client of the profile that Console users sign in with. The Console also verifies the ID token, so that profile must have a Well Known URL or a Base URL. Only users who already have Console access can sign in to the Console.
• Sign-in Path: Give each profile a different Sign-in Path. The Console finds a profile by its Sign-in Path only. When a staging profile and a production profile have the same Sign-in Path, the Console always uses the staging profile.

Setup Overview

Do the setup in staging first. Then do all of the steps again for production, with a new IDP profile and a new client.

Step	Where	Who
1. Create the IDP profile	eCourtDate Console	eCourtDate Super Admin
2. Set the Sign-in Path and agencies	eCourtDate Console	eCourtDate Super Admin
3. Register the client	Identity provider admin portal	Identity provider administrator
Hand off the values	Secure channel	Identity provider administrator to eCourtDate Super Admin
4. Enter the provider settings	eCourtDate Console	eCourtDate Super Admin
5. Read the configuration checks	eCourtDate Console	eCourtDate Super Admin
6. Test the sign-in	Agency app and Console	eCourtDate Super Admin, with a test user
7. Give users the Sign-in URL	Agency communication	eCourtDate Super Admin

Before Starting

Have the following ready:

• Super Admin access in an agency in the region of the profile. Only a Super Admin of the profile's Default Agency can open, change, or delete the profile.
• An identity provider administrator who can register a client, add redirect URLs, and set the claims in the ID token.
• The reference of each agency, if group membership at the identity provider will control agency access. The reference shows in Agency Settings in the Console. See Group Name Format.
• A test user at the identity provider, with an email address.

Step 1: Create the IDP Profile

1. Open IDPs in the Console.
2. In Create IDP, enter a Name, such as Entra ID Staging. The name is a label for administrators only.
3. Select the Region. Select staging for the staging profile, or the production region of the agency for the production profile.
4. Click Create.

The profile page opens. eCourtDate gives the new profile a random Sign-in Path. The page shows five URLs that contain the Sign-in Path:

URL	Format	Use
Sign-in URL	https://{region}.ecourtdate.com/oauth/{sign-in-path}	Users open this URL to sign in to the Agency app.
Redirect URL	https://{region}.api.ecourtdate.com/oauth/{sign-in-path}/redirect	Register this URL at the identity provider. The identity provider sends Agency app sign-ins back to it.
Logout URL	https://{region}.ecourtdate.com/logout	Register this URL at the identity provider as a sign-out redirect URL, if the provider has this setting.
Console Sign-in URL	https://console.ecourtdate.com/oauth/{sign-in-path}	Users open this URL to sign in to the Console.
Console Redirect URL	https://console.ecourtdate.com/oauth/{sign-in-path}/redirect	Register this URL at the identity provider. The identity provider sends Console sign-ins back to it.

Step 2: Set the Sign-in Path and Agencies

Do this step before the identity provider administrator registers the client. The Redirect URLs contain the Sign-in Path, so they change when the Sign-in Path changes.

1. Optional: change the Sign-in Path to a readable value, such as agency-sso. Use lowercase letters, numbers, and hyphens only.
2. In Default Agency, select the agency that owns the profile.
3. In Enabled Agencies, select each agency that users of this profile can get. To select more than one agency, hold Ctrl (Cmd on a Mac).
4. In Default Role, select the role that a new user gets when the ID token has no roles claim.
5. Click Save changes.
6. Copy the Redirect URL and the Console Redirect URL. Send them to the identity provider administrator.

Rules for these fields:

• Sign-in Path: The Sign-in Path must be unique in its region. Reserved words, such as admin, auth, oauth, ecourtdate, and demo, are not accepted. For a Sign-in Path or a region that is not accepted, the Console shows "Invalid Sign In or region".
• Enabled Agencies: At least one agency is necessary. If no agency is selected, the Console shows "Select at least one Enabled Agency" and does not save. The list shows the active agencies in the region of the profile.
• Default Role: The list shows the roles of the Default Agency. After a change to the Default Agency, save the profile to see the roles of the new agency.

For how group membership selects agencies from the Enabled Agencies list, see Agency Access.

Step 3: Register the Client

The identity provider administrator does this step. For the screens and the URLs of each provider, see Provider Settings.

1. Register a new client (application) for this IDP profile. Select the web application type, which uses a client secret.
2. Add the Redirect URL as an allowed redirect URL. Some providers call it a callback URL.
3. If Console users sign in with this profile, add the Console Redirect URL also.
4. If the provider has a list of sign-out redirect URLs, add the Logout URL.
5. Turn on the Authorization Code grant.
6. Set the client authentication method to client secret with HTTP Basic (client_secret_basic).
7. Make sure that the ID token contains the email claim.
8. Optional: add a groups claim to control agency access. See Agency Access.
9. Optional: add a roles claim to set user roles. See Roles.
10. Assign to the client the users or groups that can use eCourtDate.
11. Create a client secret. Write down the date when the secret expires.

Hand Off the Values

Send these values to the eCourtDate Super Admin through a secure channel. Do not send the Client Secret in a support ticket or in a plain email.

Value	Where it comes from
Client ID	The overview page of the client at the identity provider
Client Secret	Step 3, when the secret was created
Expiry date of the secret	Step 3
Well Known URL	The OpenID Connect discovery document of the provider
Authorization URL	The authorization_endpoint value in the discovery document
Token URL	The token_endpoint value in the discovery document
End Session URL	The end_session_endpoint value in the discovery document, if the document has one
Additional scopes	Scopes that the claims need, such as groups for Okta

Step 4: Enter the Provider Settings

1. Open the profile in IDPs.
2. Enter the Client ID and the Client Secret.
3. Enter the Well Known URL.
4. Enter the Authorization URL and the Token URL.
5. In Authorization Scope, enter openid profile email. Add the additional scopes, such as groups, separated by spaces.
6. Enter the End Session URL.
7. In Alert Contacts, enter the email addresses that get a notice when the monthly credentials test fails.
8. Click Save changes.

For each field, see IDP Profile Fields. For the values of each provider, see Provider Settings.

Step 5: Read the Configuration Checks

Each time the profile page opens, it runs two checks. The page opens again after each save.

Credentials Check, at the top of the page:

• "Credentials Check Passed!" means that the Token URL accepted the Client ID and the Client Secret.
• The check uses the client_credentials grant. It does not test the sign-in flow.
• A client that does not permit the client_credentials grant fails this check, also when the Client ID and the Client Secret are correct. For this type of client, use a test sign-in to confirm the values.
• The page does not show this check for a Google Token URL.

OIDC Configuration Check, below the form:

• The check 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.
• "Discovery, issuer, and signing keys all resolved" means that the Console can verify ID tokens with this configuration.
• An error stops every Console sign-in. A warning shows a setting that can cause sign-ins to fail.

To correct each message, see OIDC Configuration Check Messages.

Step 6: Test the Sign-in

After a change to the profile, the Agency app can use the old settings for up to 15 minutes. If a test fails right after a change, wait 15 minutes and test again.

Test the Agency app:

1. Open a private browser window.
2. Open the Sign-in URL of the profile.
3. Sign in at the identity provider as the test user.
4. Make sure that the Agency app opens.
5. Make sure that the user has the correct agencies and roles.
6. In the Console, open the profile again. The header shows Last active.
7. Read the IDP Last Sign In panel. Make sure that email, groups, and roles have the correct values.

The IDP Last Sign In panel shows the authorized scopes and the ID token claims of the most recent Agency app sign-in. The Console keeps this record for 24 hours.

Test the Console:

1. Open a new private browser window.
2. Open the Console Sign-in URL of the profile.
3. Sign in as a user who has Console access.
4. Make sure that the Console opens on the Dashboards page.

A Console sign-in does not change Last active or the IDP Last Sign In panel. These show Agency app sign-ins only.

If a test fails, see OAuth Troubleshooting.

Step 7: Give Users the Sign-in URL

Give the Sign-in URL to the users of the Agency app, for example on the agency intranet. Give the Console Sign-in URL only to users who have Console access.

At the first sign-in to the Agency app, eCourtDate creates the user. The Console does not create users. See User Provisioning.

IDP Profile Fields

The fields are in the order of the profile page.

Field	Description
Sign-in Path	The last part of the Sign-in URL and of the Redirect URLs. It must be unique in its region. Use lowercase letters, numbers, and hyphens. A change to the Sign-in Path changes all five URLs. After a change, update the identity provider and the links that users have.
Region	The eCourtDate region of the profile, such as staging or us-east. The profile works in this region only. Do not change the region of a profile that is in use. Create a new profile for a different region.
Name	A label for administrators. Users do not see it.
Client ID	The client ID from the identity provider.
Client Secret	The client secret from the identity provider. eCourtDate sends it to the Token URL with HTTP Basic authentication.
Well Known URL	The OpenID Connect discovery document of the provider, such as https://{issuer}/.well-known/openid-configuration. The Console reads the issuer and the signing keys from it. If the URL does not contain .well-known, the Console adds /.well-known/openid-configuration.
Base URL	The issuer URL of the provider. The Console uses it to find the discovery document only when the Well Known URL is empty.
Authorization URL	The authorization endpoint of the provider. Sign-in sends the browser to this URL. This field is necessary.
Authorization Scope	The scopes that the Agency app requests, separated by spaces. eCourtDate adds openid, profile, and email when they are not in the field. The Console always requests openid profile email and does not use this field.
Token URL	The token endpoint of the provider. eCourtDate sends the authorization code to this URL to get the ID token. This field is necessary.
Token Scope	Scopes that the Agency app sends with the token request. eCourtDate adds openid, profile, and email when they are not in the field. Leave it empty unless the provider needs a scope on the token request.
User URL	The userinfo endpoint of the provider. Sign-in reads the user from the ID token and does not call this URL.
End Session URL	The end-session (sign-out) endpoint of the provider. When a user signs out of the Agency app, eCourtDate sends the browser to this URL with the client_id and returnTo parameters.
Audience	The audience parameter for the Credentials Check and the monthly credentials test. Sign-in does not use it.
Default Role	The role that a user gets in a new agency when the ID token has no roles claim. The list shows the roles of the Default Agency.
Default Agency	The agency that owns the profile. Only a Super Admin of this agency can open, change, or delete the profile.
Enabled Agencies	The agencies that users of this profile can get. At least one is necessary. The list shows the active agencies in the region of the profile.
Alert Contacts	Email addresses, separated by commas, that get a notice when the monthly credentials test fails. Phone numbers and webhook URLs in this field do not get the notice.

Monthly credentials test: 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. When the test fails, each email address in Alert Contacts gets a notice. A client that does not permit the client_credentials grant fails the test each month.

Delete a profile: Click DELETE at the bottom of the profile page. The Console does not ask for confirmation. After the deletion, the Sign-in URL opens the standard eCourtDate sign-in, and the Console Sign-in URL shows a "Not Found" page.

FAQs

Does one IDP profile work in staging and in production?

No. Each profile works in one region only. Create one profile with the Region staging, and a different profile with the production region of the agency. Register a separate client at the identity provider for each profile.

Does the Console need its own configuration?

Yes. The Console has its own Redirect URL: https://console.ecourtdate.com/oauth/{sign-in-path}/redirect. Register it on the client of the profile that Console users sign in with. The Console also verifies the ID token, so that profile must have a Well Known URL or a Base URL. A profile that works for the Agency app does not work for the Console until these settings are complete.

Which profile does the Console use?

The profile whose Sign-in Path is in the Console Sign-in URL. The Console does not look at the region. Select one profile for Console sign-in, such as the production profile. Give its Console Sign-in URL to Console users.

Can a staging profile and a production profile have the same Sign-in Path?

The Console accepts the same Sign-in Path in two regions, because a Sign-in Path must be unique only in its region. Do not do this. With the same Sign-in Path, the Console Sign-in URL always uses the staging profile.

Does SSO create users in eCourtDate?

The Agency app creates users. At the first sign-in, eCourtDate creates the user from the email, name, and picture claims in the ID token. The Console does not create users. A user must exist in eCourtDate, with Console access, before a Console sign-in.

Who can sign in to the Console with SSO?

A user who already has Console access in at least one agency. A Super Admin has Console access. A user whose roles contain consoleuser, security, or root also has Console access. eCourtDate staff accounts and partner accounts cannot sign in through the identity provider of an agency. They use the standard eCourtDate sign-in.

Does SSO remove agency access when a user leaves?

No. When the identity provider disables a user, the user cannot start a new sign-in. The agencies of the user in eCourtDate do not change. An Agency app session that started before stays valid for up to 24 hours. Remove the user from the agencies in eCourtDate also.

Does a group removal at the identity provider remove agency access?

No. A sign-in adds agencies and never removes them. To remove an agency from a user, change the agencies of the user in eCourtDate.

Does a role removal at the identity provider remove Super Admin?

No. A sign-in can turn on Super Admin, but it never turns it off. To remove Super Admin, change the user in eCourtDate.

How long does a change to a profile take to apply?

The Console uses the new settings at the next sign-in. The Agency app can use the old settings for up to 15 minutes. The Console keeps the discovery document and the signing keys for 10 minutes.

What happens when the client secret expires?

Sign-ins fail when eCourtDate sends the authorization code to the Token URL. Before the old secret expires, create a new secret at the identity provider. Enter it in Client Secret and click Save changes. Add Alert Contacts to get a notice from the monthly credentials test.

How long does an Agency app session last?

24 hours. Then the user signs in again. The token lifetime at the identity provider does not change the length of the eCourtDate session.

Does SSO work with multi-factor authentication?

Yes. The identity provider asks for MFA before it sends the user back to eCourtDate. eCourtDate does not ask SSO users for MFA. Set the MFA rules at the identity provider.

Does eCourtDate support SAML?

No. eCourtDate supports OpenID Connect with the OAuth 2.0 Authorization Code flow.

Does eCourtDate use PKCE?

No. eCourtDate is a confidential client. It authenticates at the Token URL with the Client ID and the Client Secret. Register the client as a web application, not as a single-page application or a native application.

Does eCourtDate need the email_verified claim?

No. eCourtDate does not check email_verified for the identity provider of an agency. The agency controls the email addresses in its directory.