EZGH SSO gives your organization a directory of its people and makes EZGH Cloud their identity
provider. The people in the directory sign in once, at your organization’s portal
(https://<alias>.sso.ezgh.app), and from there reach the applications you assign them. They
don’t need to be members of your organization in the console. With
console access, they can also use the EZGH console and the ezgh CLI as a bot
you map to them, with that bot’s permissions, and get temporary API keys that end with their SSO
session.
People come from two places, which you can mix:
- Hosted users you create. They sign in with a passkey, or a password and a TOTP code.
- Your own identity provider, such as Okta, Microsoft Entra ID or Google Workspace. People whose email domain you route to it sign in there, over OIDC or SAML 2.0. They’re created on their first sign-in, or provisioned ahead of time by the identity provider’s SCIM.
Your applications trust only EZGH SSO, whichever way a person signed in: over OpenID Connect or SAML 2.0. EZGH SSO can also push the people assigned to an application to its SCIM API. EZGH SSO is free.
Enable a directory
Choose an alias, the sign-in policy and branding.
Users and sign-in
Hosted users, passkeys, TOTP, MFA and sessions.
Groups
Directory groups and their members.
Email domains
Verify the email domains your people use.
Identity providers
Federate Okta, Entra ID or Google Workspace.
Inbound SCIM
Let your identity provider provision and deprovision your directory.
OIDC applications
Sign people in to your own web, single-page and native apps.
SAML applications
Sign people in to SAML apps from the catalog or their metadata.
Outbound provisioning
Push assigned users and groups to your apps over SCIM.
Assignments
Choose who may sign in to each application.
Console access
Let directory users use the EZGH console as a bot.
OIDC endpoints
The directory's issuer, discovery, keys and OAuth endpoints.
Concepts
| Term | Meaning |
|---|---|
| Directory | Your organization’s EZGH SSO instance: its alias (the portal’s host name), sign-in policy, branding and signing keys. An organization has at most one. |
| User | A person in the directory. source is hosted (created by you), jit (created when they first signed in through your identity provider) or scim (provisioned by your identity provider). status is pendingActivation, active or suspended. |
| Group | A set of directory users. Group names are sent to applications in the groups claim and SAML attributes. source is hosted or scim. |
| Email domain | A domain your directory proved it owns with a DNS TXT record. Only verified domains route people to an identity provider. |
| Identity provider | An upstream OIDC or SAML identity provider that people from routed domains sign in through. |
| SCIM token | A directory SCIM token (ezgh_dsc_…) that lets an identity provider provision its people into the directory over SCIM. |
| Application | Something people sign in to: an oidc application (an OpenID Connect client), a saml application (a SAML 2.0 service provider) or an ezgh application (an EZGH product’s portal tile, or the console application for console access). |
| Assignment | A user or group allowed to sign in to an application. |
| Provisioning | An application’s outbound SCIM settings: EZGH SSO pushes its assigned users and groups to the application’s SCIM API. |
Directories, users, groups, identity providers and applications are regional resources
(us-west-1) in your organization, not in a project. Each has an ID (a UUID), a slug and a
resource name, such as ezgh:us-west-1:org_k3f9a0x2m7qp:dir_4k2m9x0a7qpe:usr_8a1b2c3d4e5f.
Slug prefixes: dir (directory), usr (user), dgp (group), idp (identity provider), app
(application).
Directory users aren’t members
Your organization’s members (users and bots in IAM) use the console, the CLI and the APIs. Directory users use applications. They’re separate:
- A directory user isn’t a member: they have no member account or API keys of their own, and never count as a member. A thousand people can use your apps without a thousand members.
- A directory user can use the console only through console access, as a bot that trusts them, and stays a directory user.
- The same email address can be a member and a directory user, as two separate identities.
- Directory groups (slug
dgp_…) are separate from IAM groups.
The Directory page in IAM is something else: it connects an identity provider for your members’ console sign-in. See IAM directory. EZGH SSO is the other direction: EZGH Cloud is the identity provider, and your apps trust it.
Directory decisions and IAM decisions
IAM decides what a principal may do to EZGH Cloud. The directory decides everything about its own people, from its own data, on every request:
| Decision | Made by |
|---|---|
| Who exists, and whether they’re active; how they must sign in; their sessions | The directory |
| Who is in which group | The directory |
| Who may sign in to each of your applications (assignments) | The directory |
| What an application is told about a person (claims) | The directory |
A member managing the directory, its users, groups and applications (sso.* actions) |
IAM, as that member |
| A directory user acting on an EZGH product | IAM, from policies attached to the user and their groups |
| Who may open the console through console access | The directory: the console application’s assignments |
| Which bots a directory user may use in the console, and what they may do there | IAM: each bot’s trust, and the bot’s policies |
So assignments aren’t policies, and no policy grants sign-in to your application. The two meet
only at groups: the directory says who is in engineering, and IAM can say what engineering
may do in an EZGH product. See Access control.
Where things are
| What | Where |
|---|---|
| Management API | https://sso.ezghcloud.com, under /v1/organizations/{orgId}/sso. See the EZGH SSO API reference. It takes the same credentials as the other APIs: API keys, CLI logins and console sessions. |
| Portal and sign-in | https://<alias>.sso.ezgh.app, for directory users. It never accepts EZGH Cloud credentials. |
| OIDC issuer | https://<alias>.sso.ezgh.app. See OIDC endpoints. |
| Inbound SCIM | https://sso.ezghcloud.com/scim/v2, for your identity provider, with a directory SCIM token. See Inbound SCIM. |
| SAML IdP | https://<alias>.sso.ezgh.app/saml/…, one IdP per SAML application. See SAML applications. |
| Console | EZGH SSO: Overview, Users, Groups, Domains, Custom domains, Identity providers, Applications, Console access, SCIM and Settings. |
| CLI | ezgh sso. See the command reference. |
Quick start
ezgh sso directory create --name "Acme" --alias acme
ezgh sso users create ada@acme.com --name "Ada Lovelace"
ezgh sso applications create --name "Wiki" --type web --redirect-uri https://wiki.acme.com/callback
ezgh sso assignments add Wiki --user ada@acme.comAda gets an activation email, sets up a passkey or a password and TOTP, and can then sign in to
the wiki through https://acme.sso.ezgh.app.