---
title: "Enterprise SSO"
description: "The Better Auth enterprise OIDC and SAML runtime enabled for StackShip organizations."
---

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

# Enterprise SSO

StackShip enables the `@better-auth/sso` plugin in the production identity
runtime. It supports enterprise OIDC and SAML connections associated with a
StackShip organization.

There is no billing or plan gate for SSO today.

## Runtime contract

The API identity issuer is:

```text
https://api.stackship.run/api/auth
```

SSO is configured with organization provisioning enabled and a default
provisioned organization role of `member`. Better Auth remains responsible for
provider discovery, the protocol callback, account linking, and connection
storage.

Users start SSO from the public sign-in page with a work email. The dashboard
normalizes the address, sends it to Better Auth for provider discovery, and
shows a generic failure if discovery or the provider exchange does not
complete. It does not disclose whether a domain has a configured connection.

The production OIDC redirect URI is:

```text
https://stackship.run/api/auth/sso/callback
```

This dashboard endpoint is a same-origin auth boundary that forwards to the
API issuer, round-trips Better Auth's signed callback state cookie, and
produces a host-only dashboard session. Unrelated cookies are not forwarded.
Register the exact URI with every OIDC provider.

An SSO-authenticated identity still needs a live StackShip organization
membership. Successful authentication does not bypass the active-organization
or product-permission checks.

## Current administration surface

The dashboard organization page manages members and invitations. It does not
currently provision SSO connections, verify domains, show enforcement status,
map identity-provider groups, or expose break-glass administration.

Production SSO connection provisioning is therefore an operator-assisted
Better Auth workflow today. Use the exact endpoint and callback
metadata returned by the deployed Better Auth version and environment; do not
infer URLs from organization slugs or examples in old design material.

For a SAML provider whose Better Auth `providerId` is `<provider-id>`, configure
its `samlConfig.callbackUrl` and the IdP assertion consumer service URL as:

```text
https://stackship.run/api/auth/sso/saml2/sp/acs/<provider-id>
```

The dashboard permits a cross-origin form POST only on Better Auth's exact
SAML callback and ACS route families, accepts only
`application/x-www-form-urlencoded`, and caps the body at 256 KiB. Every other
cross-origin auth mutation is rejected. Better Auth then validates the
assertion. IdP-initiated login is disabled, and `InResponseTo` validation is
required.

## Security requirements

- OIDC connections must use an exact issuer and registered redirect URI.
- SAML assertions must be validated by Better Auth for the configured provider;
  do not terminate or parse assertions in dashboard application code.
- Provider secrets and SAML private material are secrets and must never enter
  source control, logs, analytics, or browser URLs.
- A provider identity must map to the expected organization.
- Removing or deactivating a user must revoke access through the identity
  system; stale application membership checks fail closed.
- Operators must retain a tested recovery path before enforcing an external
  identity provider.

## SSO and SCIM

SSO authenticates a request. SCIM provisions and deactivates directory
identities. StackShip enables both Better Auth plugins, but they have separate
credentials and lifecycle behavior.

See [SCIM provisioning](/admin/scim).

## Related pages

- [Authentication](/authentication)
- [Organization administration](/admin)
- [Roles and permissions](/admin/teams)

Source: https://docs.stackship.run/admin/sso/index.mdx