---
title: "EZGH SSO"
description: "A workforce directory for your organization, and an identity provider for your own apps and EZGH apps."
---

> 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.

# EZGH SSO

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](/sso/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](/sso/directory) — Choose an alias, the sign-in policy and branding.
- [Users and sign-in](/sso/users) — Hosted users, passkeys, TOTP, MFA and sessions.
- [Groups](/sso/groups) — Directory groups and their members.
- [Email domains](/sso/domains) — Verify the email domains your people use.
- [Identity providers](/sso/identity-providers) — Federate Okta, Entra ID or Google Workspace.
- [Inbound SCIM](/sso/scim) — Let your identity provider provision and deprovision your directory.
- [OIDC applications](/sso/applications) — Sign people in to your own web, single-page and native apps.
- [SAML applications](/sso/saml-applications) — Sign people in to SAML apps from the catalog or their metadata.
- [Outbound provisioning](/sso/provisioning) — Push assigned users and groups to your apps over SCIM.
- [Assignments](/sso/assignments) — Choose who may sign in to each application.
- [Console access](/sso/console-access) — Let directory users use the EZGH console as a bot.
- [OIDC endpoints](/sso/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](/sso/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](/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](/sso/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](/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](/sso/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](/sso/access-control).

## Where things are

| What | Where |
| --- | --- |
| Management API | `https://sso.ezghcloud.com`, under `/v1/organizations/{orgId}/sso`. See the [EZGH SSO API reference](/sso-api). 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](/sso/oidc-endpoints). |
| Inbound SCIM | `https://sso.ezghcloud.com/scim/v2`, for your identity provider, with a directory SCIM token. See [Inbound SCIM](/sso/scim). |
| SAML IdP | `https://<alias>.sso.ezgh.app/saml/…`, one IdP per SAML application. See [SAML applications](/sso/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](/cli/reference/sso). |

## Quick start

```sh
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.com
```

Ada 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`.

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