A directory user is a person who signs in at your portal. Users you create are hosted: they
sign in with factors they set up in EZGH SSO. Users who sign in through your
identity provider are created for you on their first sign-in
(source: jit), or provisioned by its SCIM (source: scim), and have no factors
here.
User fields
| Field | Description |
|---|---|
id, slug, resourceName |
The user’s ID (a UUID), slug (usr_…) and resource name, ezgh:us-west-1:org_…:dir_…:usr_…. In tokens, sub is the user’s ID. |
name |
1 to 200 characters. |
email |
Up to 254 characters, unique in the directory (in any letter case). |
givenName, familyName |
Optional, up to 100 characters each, or null. |
department |
Optional, up to 256 characters, or null. Used by ${user.department} in SAML attributes and provisioning mappings. |
tags |
Up to 50 key-value pairs, as for the directory. |
source |
hosted, jit or scim. |
identityProviderId |
The identity provider the user came from: for a SCIM user, the one whose token provisioned them; otherwise the one they were first linked to at sign-in. null for none, or once it’s deleted. |
locked |
true while the user’s identity provider manages them over SCIM: changes to them are then 409 managed_by_scim. |
status |
pendingActivation, active or suspended. See Statuses. |
activatedAt, lastSignInAt |
When the user activated and last signed in, or null. |
Create a user
You need sso.users.create. A directory holds up to 5,000 users by default
(limits).
ezgh sso users create ada@acme.com --name "Ada Lovelace"Or call CreateUser with name and email. Another user with the
same email is 409 email_taken.
The new user is pendingActivation, and gets an activation email from
no-reply@mail.ezghcloud.com with a link to https://<alias>.sso.ezgh.app/activate. The link
works once, for 24 hours. Following it, they set up what the sign-in policy needs: a passkey, or
a password (and a TOTP authenticator when MFA is required). Then they’re active and signed in.
If the link expired, ResendActivation sends a new one and makes the old one unusable.
List and change users
ezgh sso users list --status active
ezgh sso users get ada@acme.com
ezgh sso users update ada@acme.com --name "Ada King"ListUsers takes status, limit (1 to 100) and cursor.
UpdateUser changes name, email, givenName, familyName,
department and tags. ListUserGroups lists a user’s groups.
Statuses
| Status | Meaning |
|---|---|
pendingActivation |
Created, and hasn’t completed their activation link. Can’t sign in. |
active |
Can sign in. |
suspended |
Can’t sign in. Everything they had is ended. |
| Action | Does | Allowed when |
|---|---|---|
| Suspend | Ends their sessions, sign-ins in progress, unused links, application grants and refresh tokens, and refuses new sign-ins. Takes effect on the next request. | Not already suspended |
| Reactivate | Back to active; a hosted user who never activated goes back to pendingActivation with a new activation email. |
Suspended |
| Reset factors | Removes their password, TOTP and passkeys, ends everything as suspension does, and emails a 24-hour link to set up factors again. | Hosted and active |
| Resend activation | A new activation email. | Hosted and pending |
| Delete | Ends everything, removes them from their groups and assignments, and deletes them. | Always |
Anything else is 409 (user_suspended, user_not_suspended, user_not_active,
user_not_hosted, user_not_pending_activation). For a locked user, updating, suspending,
reactivating and deleting are 409 managed_by_scim: their identity provider does these over
SCIM. You can still revoke their sessions.
ezgh sso users suspend ada@acme.com
ezgh sso users reactivate ada@acme.com
ezgh sso users reset-factors ada@acme.comAccess tokens already issued to your applications stay valid until they expire (15 minutes by default); applications that use introspection see the change at once.
Sessions
Signing in at the portal starts a session in that browser. Its length and idle timeout come from the sign-in policy, checked on every request.
- ListSessions lists a user’s live sessions, newest first: when
each started and was last used, how they signed in (
amr:pwd,otp,hwkfor a passkey,fedfor an identity provider), the IP address and user agent, and when it ends. - RevokeSessions signs the user out of every session and
sign-in in progress. It also ends their application grants without
offline_access, and every EZGH resource token grant. It answers how many sessions it ended.
How people sign in
- They open
https://<alias>.sso.ezgh.app(or an application sends them there) and enter their email address. - If its domain is a verified domain routed to an identity provider, they continue there.
- Otherwise they sign in here: with a passkey, which is enough on its own, or with a password followed, when MFA is required, by a TOTP code.
The pages look the same whether or not the email address belongs to a user, and a failed sign-in says only that it failed.
| Factor | Details |
|---|---|
| Passkey | A WebAuthn credential (security key, or a platform authenticator such as Touch ID or Windows Hello), bound to <alias>.sso.ezgh.app, with user verification. Counts as two factors. Up to 20 per user. |
| Password | 8 to 256 characters when MFA is required, and at least 15 when it isn’t. It can’t contain the email address or be a commonly used password. |
| TOTP | An authenticator app: 6 digits, 30-second steps. One per user. A code can’t be used twice. |
A user with no second factor under an MFA policy can’t finish signing in with a password alone: an administrator resets their factors so they can enroll. There’s no self-service recovery by email or SMS.
Throttling
Repeated failures for an email address slow down further attempts for it, and ten failures lock
it for 15 minutes. Many failures from one IP address are limited the same way. A throttled
attempt is 429 with Retry-After, and looks the same for addresses that aren’t users.
The account page
At https://<alias>.sso.ezgh.app/account, a signed-in user can:
- see their profile;
- change their password (with the current one; their other sessions end);
- add and remove passkeys, and set up or remove TOTP (within 15 minutes of signing in, or they’re asked to sign in again);
- see their sessions and sign out of any of them.
A factor can’t be removed when the user would then be unable to sign in under the policy.
The portal, https://<alias>.sso.ezgh.app, shows a tile for each application they’re assigned
to that has somewhere to open (see portal tiles).