Skip to content
Dashboard
Theme
Theme

How the SSO flow works

The end-to-end flow: your app redirects the user to /sso/authorize with PKCE, the broker resolves the organization's active connection and talks to the IdP, then redirects back with a single-use code that your server exchanges at POST /v1/sso/token.

View Markdown

  1. Your server creates a random state value and a PKCE verifier. Store them with the initiating browser session, expected organization, exact redirect URI and a short expiry.
  2. Redirect the browser to https://auth.ohauthcat.com/sso/authorize with the publishable client_id, response_type=code, state, S256 challenge and a routing hint.
  3. The broker selects an active, tested connection and performs SAML or OIDC validation with the IdP. It verifies the returned email against the organization’s verified domains.
  4. On your callback, reject repeated parameters, missing or mismatched state, the wrong browser session and expired attempts. Atomically consume the stored attempt before exchanging its code.
  5. Your server calls POST https://auth.ohauthcat.com/v1/sso/token, authenticating with the environment’s secret key and sending grant_type=authorization_code, client_id, code, code_verifier and the exact redirect_uri.
  6. Check the returned profile’s organization, map it to an allowed local identity and create your own session.

Token exchange and GET /v1/sso/profile run on the auth host. The management API host returns not_implemented for these operations. Browser-facing routes are unversioned; server-to-server exchange uses /v1/.

Authorization codes expire after 60 seconds. A second exchange returns invalid_grant and revokes the token from the first exchange at the profile endpoint. Restart sign-in after an interrupted or invalid grant; do not keep retrying the old code. Broker state is sealed, bound to the flow and single-use; your application’s state check is still required.

The response contains an ES256 access token with a 600-second lifetime and a profile. Use the Node SDK’s sso.verifyAccessToken(token) with the correct clientId, environmentId and issuer when verifying a token. A local signature check does not query broker revocation state; the profile endpoint checks the token’s current validity. Do not hand-decode a JWT and treat its claims as verified.

See sign-in errors and the SSO API reference.