Scopes & Claims

Scopes define what data your OAuth integration can access, and claims carry user identity information within tokens. Correct scope and claim configuration is essential for proper authentication and agency assignment in eCourtDate.

Standard OIDC Scopes

The following standard OpenID Connect scopes are used across all providers:

Scope	Required	Description
openid	Yes	Indicates an OIDC authentication request; returns a sub (subject) claim
email	Recommended	Returns the user's email address
profile	Recommended	Returns basic profile information (name, etc.)

Provider-Specific Scopes

Each Identity Provider may require additional scopes for full functionality, particularly for group-based agency assignment:

Provider	Additional Scopes	Purpose
Azure AD	GroupMember.Read.All, User.Read	Read group memberships and user profile via Microsoft Graph
Google Workspace	admin.directory.group.member.readonly, admin.directory.group.readonly	Read Google Workspace group memberships
Okta	groups	Include group membership in the ID token
AWS Cognito	openid, email, profile	Standard OIDC scopes (no additional scopes required)

Group Claim Configuration

Group claims enable automatic agency assignment when users sign in through SSO. The Identity Provider sends group membership information in the token, and eCourtDate maps those groups to agencies.

Group Name Format

For a group to map to an agency, the group name must meet all of these conditions:

• It contains the text ecourtdate somewhere in the name (matched case-insensitively).
• It begins with a single prefix character (use #), followed immediately by the numeric agency reference.
• The prefix character and the agency reference come before the first underscore (_).

The agency reference must be numeric. eCourtDate reads the characters before the first underscore, drops the leading prefix character, and matches the remaining digits against an agency reference.

Format:

#{AgencyReference}_ECOURTDATE

Example: For the agency whose reference is 100, name the group:

#100_ecourtdate

A trailing label after another underscore is allowed, so #100_ecourtdate_admin also maps to agency reference 100. The ecourtdate text is matched case-insensitively, so #100_ECOURTDATE works as well.

warning

Always include the leading # prefix. eCourtDate always drops the first character before the underscore, so 100_ecourtdate (no prefix) is read as reference 00, not 100. Only numeric agency references can be mapped through groups.

Super Admin Designation

Super Admin is granted from the roles claim in the token, not from group names. eCourtDate checks each role in the roles claim, and if any role matches one of these keywords as a whole word (case-insensitive), that user is made Super Admin in every agency they are assigned:

• security
• admin
• root

The keyword must stand as its own word, set off by a non-word character (a space, hyphen, or period) or the start or end of the role name. An underscore does not separate words here:

• admin, Security, ROOT, super-admin, court admin, and system.root trigger Super Admin.
• Court_Security_Team does not trigger it, because the underscores keep Security from standing as its own word.

To grant Super Admin intentionally, include a role such as admin. To avoid it, keep these keywords out of role names as standalone words.

User Provisioning

When a user signs in through SSO, eCourtDate provisions them as follows:

Behavior	Details
User matching	The incoming user is matched to an existing profile by email address.
Profile creation	If no profile has that email, a new one is created from the token claims (name, email, picture).
Default role	A default role configured on the IDP profile is assigned to newly created users.
Agency assignment	Agencies come from the agency list configured on the IDP profile, filtered by the user's matching #{AgencyReference}_ECOURTDATE groups.
No matching groups	If the token carries no matching groups, the user is assigned to all agencies configured on the IDP profile.

Because users are matched by email, the email in the token must match the email on the existing eCourtDate profile. If the email at the Identity Provider changes, the sign-in may create a separate profile instead of resolving to the existing one.