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:
https://api.stackship.run/api/authSSO 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:
https://stackship.run/api/auth/sso/callbackThis 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:
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.