# Enterprise & SSO

Operational guide for an AI agent setting up enterprise single sign-on (SSO) for a Briefs
organization. This is an early version and will be expanded with more detail later.

## What enterprise SSO does

Enterprise setup creates an organization, claims a company's email domain, and provisions a
WorkOS organization for identity management. The user who runs setup becomes the org admin.
Once configured, users at the verified domain can sign in via the company's identity
provider (SSO) rather than individual accounts.

## The setup flow

1. `setup_company_sso` — provide the company display name, an org namespace (lowercase
   letters, numbers, dashes), and the company email domain (e.g. `acme.com`). This creates
   the org, claims the domain, provisions WorkOS, and makes the caller the admin.
2. `get_sso_setup_link` with type `domain_verification` — generates a secure WorkOS Admin
   Portal link to verify ownership of the email domain via a DNS TXT record. This is required
   first. Share the link with the org admin to complete in their browser.
3. `get_sso_setup_link` with type `idp` — once the domain is verified, generates a portal
   link to connect the identity provider (Okta, Microsoft Entra, Google Workspace, etc.).
   Share it with the admin to complete IdP configuration.
4. `get_sso_status` — poll to follow progress: whether the email domain is verified and
   whether the identity provider is connected. It returns a `nextStep` (`verify_domain`,
   `configure_idp`, or `done`) you can use to decide which link to generate next.

## The tools

- `setup_company_sso` — create the org, claim the domain, provision WorkOS, assign the caller
   as admin.
- `get_sso_setup_link` — generate a WorkOS Admin Portal link for the admin to complete a
  setup step in their browser. Use type `domain_verification` to verify the email domain
  (DNS TXT record, required first), or type `idp` to connect the identity provider. Requires
  org admin.
- `get_sso_status` — check setup progress through domain verification and IdP setup; returns
  the current state and a `nextStep` to drive the flow. Requires org admin.

## Agent etiquette

- SSO setup is a significant, account-level action. Confirm intent, the exact domain, and
  the namespace with the user before calling `setup_company_sso`.
- Setup links are sensitive — hand them to the user/admin directly and treat them as
  credentials.
- Setup is multi-step and asynchronous: verify the domain first, then configure the IdP. After
  each step, check `get_sso_status` and follow its `nextStep` rather than assuming it
  finished.

## Related Briefs

- Organizations (roles, members, settings): https://sharebriefs.com/brief/organizations
- Concept overview: https://sharebriefs.com/brief/intro

> Note: This Brief is an initial draft. Expand with concrete examples, IdP-specific notes,
> and troubleshooting once the enterprise flow is exercised end to end.