---
title: "Users and sign-in"
description: "Create hosted users, manage their status, factors and sessions, and how people sign in with passkeys, passwords and TOTP."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Users and sign-in

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](/sso/identity-providers) are created for you on their first sign-in
(`source: jit`), or provisioned by its [SCIM](/sso/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](/sso/saml-applications#attributes) and [provisioning mappings](/sso/provisioning#attribute-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](/sso/scim#what-scim-changes): changes to them are then `409 managed_by_scim`. |
| `status` | `pendingActivation`, `active` or `suspended`. See [Statuses](#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](/sso/pricing-and-limits)).

```sh
ezgh sso users create ada@acme.com --name "Ada Lovelace"
```

Or call [CreateUser](/sso-api/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](/sso-api/ResendActivation/) sends a new one and
makes the old one unusable.

## List and change users

```sh
ezgh sso users list --status active
ezgh sso users get ada@acme.com
ezgh sso users update ada@acme.com --name "Ada King"
```

[ListUsers](/sso-api/ListUsers/) takes `status`, `limit` (1 to 100) and `cursor`.
[UpdateUser](/sso-api/UpdateUser/) changes `name`, `email`, `givenName`, `familyName`,
`department` and `tags`. [ListUserGroups](/sso-api/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](/sso-api/SuspendUser/) | 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](/sso-api/ReactivateUser/) | Back to `active`; a hosted user who never activated goes back to `pendingActivation` with a new activation email. | Suspended |
| [Reset factors](/sso-api/ResetUserFactors/) | 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](/sso-api/ResendActivation/) | A new activation email. | Hosted and pending |
| [Delete](/sso-api/DeleteUser/) | 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.

```sh
ezgh sso users suspend ada@acme.com
ezgh sso users reactivate ada@acme.com
ezgh sso users reset-factors ada@acme.com
```

Access tokens already issued to your applications stay valid until they expire (15 minutes by
default); applications that use [introspection](/sso/oidc-endpoints#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](/sso/directory#sign-in-policy), checked on every request.

- [ListSessions](/sso-api/ListSessions/) lists a user's live sessions, newest first: when
  each started and was last used, how they signed in (`amr`: `pwd`, `otp`, `hwk` for a passkey,
  `fed` for an identity provider), the IP address and user agent, and when it ends.
- [RevokeSessions](/sso-api/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

1. They open `https://<alias>.sso.ezgh.app` (or an application sends them there) and enter
   their email address.
2. If its domain is a [verified domain](/sso/domains) routed to an identity provider, they
   continue there.
3. 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](/sso/applications#portal-tiles)).

Source: https://docs.ezghcloud.com/sso/users/index.mdx