Scopes & Claims

Scopes tell the identity provider which claims to put in the ID token. eCourtDate reads the claims in the ID token to find the user, select the agencies, and set the roles.

Scopes

Application	Scopes that eCourtDate requests
Agency app	The Authorization Scope of the IDP profile. eCourtDate adds openid, profile, and email when they are not in the field.
Console	openid profile email. The Console does not use the Authorization Scope.

Add a scope to the Authorization Scope only when the provider needs it for a claim:

Provider	Authorization Scope
Microsoft Entra ID	openid profile email
Google Workspace	openid profile email
Okta	openid profile email groups
AWS Cognito	openid profile email

eCourtDate does not call Microsoft Graph or the Google Directory API. It does not need directory scopes, such as GroupMember.Read.All.

Claims That eCourtDate Reads

eCourtDate reads claims from the ID token only. It does not call the User URL.

Claim	Necessary	Use
email	Yes	Finds the eCourtDate user. eCourtDate changes the address to lowercase.
name	No	The name of a new user. eCourtDate keeps the first 36 characters.
picture	No	The photo of a new user. eCourtDate keeps the URL only when it has 100 characters or fewer.
groups	No	Selects the agencies of the user. Agency app sign-ins only. See Agency Access.
roles	No	Sets the roles and Super Admin. Agency app sign-ins only. See Roles.
iss, aud, exp, nbf, iat, nonce	Console only	The Console verifies the ID token with these claims. See Sign-in Flows.

To see the claims of a sign-in, open the IDP profile in the Console. The IDP Last Sign In panel shows the ID token claims of the most recent Agency app sign-in for 24 hours.

Agency Access

At each Agency app sign-in, eCourtDate selects agencies from the Enabled Agencies of the IDP profile:

1. eCourtDate reads the groups claim.
2. It keeps each group whose name follows the Group Name Format, and reads the agency reference from the name.
3. If at least one group follows the format, the user gets each Enabled Agency whose reference is in a group name. The agency must also be active and in the region of the profile.
4. If no group follows the format, the user gets all of the Enabled Agencies. The same is true when the ID token has no groups claim.

Groups in the ID token	References of the Enabled Agencies	Agencies that the sign-in gives
#100_ECOURTDATE, #200_ECOURTDATE	100, 200, 300	100 and 200
#100_ECOURTDATE, Staff	100, 200	100
#900_ECOURTDATE	100, 200	None
Staff, All Users	100, 200	100 and 200
No groups claim	100, 200	100 and 200

A sign-in adds agencies. It never removes an agency from a user. When a user leaves a group at the identity provider, remove the agency from the user in eCourtDate.

Group Name Format

A group name selects an agency when all of these conditions are true:

• The name contains ecourtdate. Uppercase and lowercase letters are the same.
• The name starts with one prefix character. Use #.
• The agency reference comes immediately after the prefix character and before the first underscore (_).
• The agency reference contains only digits.

Format:

#{agency-reference}_ECOURTDATE

Example: For the agency with the reference 100, name the group:

#100_ECOURTDATE

A label after a second underscore is permitted. #100_ECOURTDATE_STAFF also selects the agency with the reference 100. The reference of each agency shows in Agency Settings in the Console.

warning

Always start the group name with the prefix character. eCourtDate removes the first character before it reads the reference. It reads 100_ECOURTDATE as the reference 00, not 100. A reference that contains letters cannot select an agency.

Roles

The roles claim is a list of role names. eCourtDate stores the list as the roles of the user in each agency of the sign-in. Use role names that exist in the agency.

Situation	The ID token has a roles claim	The ID token has no roles claim
The sign-in gives the user a new agency	The user gets the roles from the claim.	The user gets the Default Role of the IDP profile.
The user already has the agency	The roles from the claim replace the old roles.	The roles of the user do not change.

Super Admin

eCourtDate makes a user Super Admin from the roles claim. Group names do not give Super Admin.

When a role in the roles claim contains one of these words, the user becomes Super Admin in each agency of the sign-in:

• security
• admin
• root

Uppercase and lowercase letters are the same. The word must stand alone. A space, a hyphen, a period, or the start or end of the role name must be on each side of it. An underscore does not separate words.

• admin, Security, ROOT, super-admin, court admin, and system.root give Super Admin.
• Court_Security_Team does not give Super Admin, because the underscores join Security to the other words.
• administrator does not give Super Admin, because admin does not stand alone.

A sign-in can turn on Super Admin. It never turns off Super Admin. To remove Super Admin, change the user in eCourtDate. To prevent Super Admin, keep these words out of role names as standalone words.

Console Access

A user can sign in to the Console only when the user has Console access in at least one agency. A user has Console access in an agency when one of these conditions is true:

• The user is Super Admin in the agency.
• The roles of the user in the agency contain consoleuser, security, or root as a standalone word.

The roles claim of an Agency app sign-in can give Console access in this way. A Console sign-in does not change roles.

User Provisioning

eCourtDate finds the user by the email address in the ID token. One email address is one eCourtDate user in all agencies and all regions.

Behavior	Agency app	Console
Find the user	By the email claim, in lowercase	By the email claim
No user has the email address	eCourtDate creates the user from the email, name, and picture claims.	The sign-in fails. The Console does not create users.
Agencies and roles	eCourtDate applies the groups and the roles at each sign-in.	No change.
email_verified claim	Not checked	Not checked

If the email address of a user changes at the identity provider, the next Agency app sign-in creates a new eCourtDate user. To keep the same user, change the email address of the user in eCourtDate to the new address also.