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

# The SAML SSO round-trip

> Walk the four SAML steps end to end — SP metadata, SP-initiated login, the IdP's ACS POST to the callback, and optional single logout.

## The SAML SSO round-trip

These four operations are the service-provider side of SAML 2.0 SSO — the route an organization's IdP administrators walk to wire Okta, Entra ID, or similar into Orbit's sign-in. The page's `{orgSlug}` path segment selects the SAML configuration; it is a URL-safe organization slug, not an API-key credential, and the operations are deliberately unauthenticated because they begin a session rather than require one.

Sequence the round-trip like this. **(1) `GET /auth/saml/{orgSlug}/metadata`** returns the service-provider XML the IdP admin imports to register Orbit: entity ID, ACS URL, and signing details. **(2) `GET /auth/saml/{orgSlug}/login?redirect=/settings/team`** issues the SP-initiated AuthnRequest and 302-redirects the browser to the IdP's SSO URL; any `redirect` value is signed into RelayState and sweeps the post-auth destination back. **(3) The IdP POSTs the signed `SAMLResponse` to `/auth/saml/{orgSlug}/callback`** — the Assertion Consumer Service verifies signature, audience, and the replay window, provisions the user on first login, then 302-redirects to the dashboard sign-in ticket that mints the session cookie. **(4) `GET /auth/saml/{orgSlug}/logout?nameId=<subject>`** builds a LogoutRequest for the IdP's SLO endpoint when single logout is configured; otherwise it answers `200` with a `logged_out` status, and the local ceremony destroys the session.

A worked check-in sequence in cURL:

```bash cURL theme={null}
# 1. Hand this metadata to the IdP admin
curl "https://api.orbit.devotel.io/auth/saml/acme-inc/metadata"

# 2. Start SSO — the browser redirects to the IdP
curl -I "https://api.orbit.devotel.io/auth/saml/acme-inc/login?redirect=/settings/team"

# 3. The IdP POSTs here on its own — no API key involved
#    POST /auth/saml/acme-inc/callback

# 4. Log out (with the subject's NameID when available)
curl -I "https://api.orbit.devotel.io/auth/saml/acme-inc/logout?nameId=user@acme.example"
```

The first event and the first callback are both redirect-only flows — do not call them from your application; point users at them or let the IdP drive the callback.