Enable a directory

Create your organization's directory, choose its alias and portal URL, and set its sign-in policy and branding.

Enabling EZGH SSO creates your organization’s directory. An organization has at most one. You need sso.directories.create (in SsoFullAccess).

Create the directory

Open EZGH SSO and select Enable. Enter a name and an alias.

ezgh sso directory create --name "Acme" --alias acme
ezgh sso directory get

Call CreateDirectory with name and alias, and optionally signInPolicy, branding and tags.

curl -X POST https://sso.ezghcloud.com/v1/organizations/$ORG_ID/sso/directory \
  -H "Authorization: Bearer $EZGH_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Acme", "alias": "acme" }'

The answer includes the directory’s portalUrl and issuer, both https://acme.sso.ezgh.app. GetDirectory returns it; without a directory it’s 404.

Directory fields

Field	Description
`id`, `slug`, `resourceName`	The directory’s ID (a UUID), slug (`dir_…`) and resource name, `ezgh:us-west-1:org_…:dir_…`.
`name`	1 to 100 characters, without control characters.
`alias`	The portal’s host name: `https://<alias>.sso.ezgh.app`. See Aliases.
`portalUrl`, `issuer`	`https://<alias>.sso.ezgh.app`: where people sign in, and the OIDC issuer.
`signInPolicy`	See Sign-in policy.
`branding`	See Branding.
`tags`	Up to 50 key-value pairs. Keys are 1 to 128 characters and can’t start with `ezgh:`; values are up to 256 characters.
`status`	`active`.
`region`	`us-west-1`.

Aliases

An alias is 4 to 32 characters: lowercase letters, digits and hyphens, starting with a letter and not ending with a hyphen (^[a-z][a-z0-9-]{2,30}[a-z0-9]$). Platform words (such as www, api, admin, login, auth and ezgh) and names that imitate brands are reserved. An alias in use, or used before, by any directory is refused.

You can change the alias with UpdateDirectory. The portal and issuer move to the new host at once. The old host redirects to the new one for 30 days, and the old alias is never used again. Because the issuer changes, update your applications’ configuration (issuer, discovery URL and endpoints) when you change the alias. The same goes for SAML applications’ IdP URLs and your identity providers’ redirect URI, ACS URL and entity ID.

The policy applies to everyone in the directory, on every request.

Field	Description	Default
`mfaRequired`	Hosted users must use two factors: a passkey, or a password and a TOTP code.	`true`
`allowedFactors`	1 to 3 of `password`, `totp` and `passkey`. With `mfaRequired`, it must include `passkey`, or both `password` and `totp`.	All three
`sessionDurationSeconds`	How long a portal session lasts from sign-in: 300 to 86,400 (24 hours).	28,800 (8 hours)
`idleTimeoutSeconds`	How long a session lasts without use: 60 to `sessionDurationSeconds`.	3,600 (1 hour)
`trustUpstreamMfa`	Accept an identity provider’s evidence of MFA. See MFA and identity providers.	`false`

signInPolicy is replaced whole: send every field. A field you leave out takes its default, not its current value. (ezgh sso directory update reads the current policy and sends it with your changes.) A shorter session length or idle timeout applies to existing sessions at once.

ezgh sso directory update --session-duration 4h --idle-timeout 30m

Branding

The portal and sign-in pages show your logo and two colors. Your directory can’t add its own HTML, CSS or scripts.

Field	Description	Default
`primaryColor`	`#RRGGBB`. Buttons and links.	`#2563eb`
`backgroundColor`	`#RRGGBB`. The page background. A readable text color is chosen for each.	`#ffffff`
`logoUrl`	Read-only: where the uploaded logo is served, `https://<alias>.sso.ezgh.app/branding/logo`, or `null`.	`null`

Like the policy, branding is replaced whole. logoUrl can be left out, or sent back unchanged.

Upload a logo with UpdateDirectoryLogo: { "data": "<base64>" }, a PNG or JPEG of at most 512 KiB and 1024 × 1024 pixels. It’s converted to a PNG. SVG files and links to images elsewhere are refused. DeleteDirectoryLogo removes it. Each application’s portal tile can have its own logo too: see Tile logo.

Delete the directory

DeleteDirectory (ezgh sso directory delete) removes the directory and everything in it, at once: every user and group with their sessions and factors, its email domains, custom domains, identity providers, SCIM tokens, applications with their secrets, assignments, provisioning settings and tokens, its signing keys and SAML certificates, and the logo. Applications stop being able to sign anyone in, and nobody is deprovisioned at applications that EZGH SSO provisions. The alias is never used again. This can’t be undone.