Sign-in flow visualizer
Step through SP-initiated SAML, IdP-initiated SAML and the OIDC code flow hop by hop, with the checks that run at each step.
Walk through a flow
Section titled “Walk through a flow”Pick a flow, then use Next and Previous to walk through it one hop at a time. The dashed box is the sender and the filled box is the receiver. Each step lists the checks that run there; a linked code is the error you see when that check fails.
Your application’s code is the same for every flow: it redirects to /sso/authorize, checks state on its callback and exchanges the code server to server. OhAuthCat handles the protocol differences.
Step 1 of 8: Browser → Your app
User asks to sign in
The user enters a work email or picks their company. Your server creates state and a PKCE verifier and stores them with the browser session.
Step 2 of 8: Your app → OhAuthCat
Redirect to /sso/authorize
The browser goes to the OhAuthCat auth host with your client ID, redirect URI, state, S256 challenge and a routing hint.
Checks at OhAuthCat
- Publishable client ID is valid
client_id_invalid - Redirect URI is registered exactly
redirect_uri_not_allowed - S256 PKCE challenge present
pkce_required - An active, tested connection is selected
connection_untested
- Publishable client ID is valid
Step 3 of 8: OhAuthCat → IdP
AuthnRequest to the IdP
OhAuthCat sends a SAML AuthnRequest through the browser and remembers its request ID so the response can be matched to it.
Step 4 of 8: inside IdP
The IdP signs the user in
The IdP authenticates the user with its own password, MFA and assignment rules. Errors here come from the IdP, not from OhAuthCat.
Checks at IdP
- User is assigned to the app (in the IdP)
Step 5 of 8: IdP → OhAuthCat
SAMLResponse posted to the ACS
The browser posts the signed response to the connection's ACS URL. Every check below must pass; one failure refuses the sign-in.
Checks at OhAuthCat
- No DTD in the XML
saml_dtd_forbidden - Signature present
saml_signature_missing - Signature valid
saml_signature_invalid - Signature algorithm strong
saml_signature_algorithm_weak - No signature wrapping
saml_wrapping_detected - Exactly one assertion
saml_assertion_count_invalid - Issuer is the configured IdP
saml_issuer_mismatch - Audience is our SP entity ID
saml_audience_mismatch - Destination and recipient are our ACS
saml_destination_mismatch - Not before / not on or after
saml_response_expired - Assertion not seen before
saml_assertion_replayed - InResponseTo matches our request
saml_in_response_to_mismatch
- No DTD in the XML
Step 6 of 8: inside OhAuthCat
Admission and roles
OhAuthCat applies the organization's domain, policy and role rules to the validated identity.
Checks at OhAuthCat
- Email in a verified domain
email_outside_verified_domain - Sign-in policies allow it
sign_in_policy_denied - Role rules pick an optional role
- Email in a verified domain
Step 7 of 8: OhAuthCat → Your app
Code back to your callback
The browser is redirected to your exact redirect URI with a single-use code and your state. Your callback checks the state against the stored attempt and consumes it once.
Checks at Your app
- State matches the stored attempt
Step 8 of 8: Your app → OhAuthCat
Server-to-server code exchange
Your server posts the code, the PKCE verifier and the redirect URI to /v1/sso/token on the auth host. The browser is not involved. You receive an access token and the profile.
Checks at OhAuthCat
- Secret key authenticates your server
api_key_invalid - Code unused and under 60 seconds old
invalid_grant - PKCE verifier matches the challenge
pkce_verification_failed - Exact same redirect URI
redirect_uri_not_allowed
- Secret key authenticates your server
Step 1 of 7: Browser → IdP
User starts at the IdP dashboard
The user clicks your app's tile in their IdP. There is no request from your app, so nothing ties the response to a session yet.
Step 2 of 7: IdP → OhAuthCat
Unsolicited SAMLResponse to the ACS
The connection must have IdP-initiated sign-in turned on; it is off by default. The response must have no InResponseTo and be at most 120 seconds old, and durable replay protection must be available.
Checks at OhAuthCat
- IdP-initiated sign-in enabled
saml_idp_initiated_disabled - No DTD in the XML
saml_dtd_forbidden - Signature present
saml_signature_missing - Signature valid
saml_signature_invalid - Signature algorithm strong
saml_signature_algorithm_weak - No signature wrapping
saml_wrapping_detected - Exactly one assertion
saml_assertion_count_invalid - Issuer is the configured IdP
saml_issuer_mismatch - Audience is our SP entity ID
saml_audience_mismatch - Destination and recipient are our ACS
saml_destination_mismatch - Not before / not on or after
saml_response_expired - Assertion not seen before
saml_assertion_replayed
- IdP-initiated sign-in enabled
Step 3 of 7: OhAuthCat → Browser
Confirmation page
OhAuthCat shows the app, organization and a masked account. The user must press Continue within 120 seconds; there is no skip option.
Checks at OhAuthCat
- Origin, CSRF token and broker cookie
csrf_token_invalid - Confirmed in time
sign_in_confirmation_abandoned
- Origin, CSRF token and broker cookie
Step 4 of 7: OhAuthCat → Your app
Handoff ticket to your app
The browser lands on your registered URI with a handoff ticket. It is single use, lasts 60 seconds and is not a code or a token.
Step 5 of 7: Your app → OhAuthCat
Your normal authorize request
Your app starts its usual /sso/authorize request with fresh state, its own PKCE challenge and the handoff ticket, binding the IdP's sign-in to your flow.
Checks at OhAuthCat
- Publishable client ID is valid
client_id_invalid - Redirect URI is registered exactly
redirect_uri_not_allowed - S256 PKCE challenge present
pkce_required - Email in a verified domain
email_outside_verified_domain - Sign-in policies allow it
sign_in_policy_denied - Role rules pick an optional role
- Publishable client ID is valid
Step 6 of 7: OhAuthCat → Your app
Code back to your callback
The browser is redirected to your exact redirect URI with a single-use code and your state. Your callback checks the state against the stored attempt and consumes it once.
Checks at Your app
- State matches the stored attempt
Step 7 of 7: Your app → OhAuthCat
Server-to-server code exchange
Your server posts the code, the PKCE verifier and the redirect URI to /v1/sso/token on the auth host. The browser is not involved. You receive an access token and the profile.
Checks at OhAuthCat
- Secret key authenticates your server
api_key_invalid - Code unused and under 60 seconds old
invalid_grant - PKCE verifier matches the challenge
pkce_verification_failed - Exact same redirect URI
redirect_uri_not_allowed
- Secret key authenticates your server
Step 1 of 8: Browser → Your app
User asks to sign in
Your server creates state and a PKCE verifier exactly as for SAML. Your code does not change between protocols.
Step 2 of 8: Your app → OhAuthCat
Redirect to /sso/authorize
The same authorize request as for SAML. OhAuthCat picks the OIDC connection.
Checks at OhAuthCat
- Publishable client ID is valid
client_id_invalid - Redirect URI is registered exactly
redirect_uri_not_allowed - S256 PKCE challenge present
pkce_required - An active, tested connection is selected
connection_untested
- Publishable client ID is valid
Step 3 of 8: OhAuthCat → IdP
Authorization request to the IdP
OhAuthCat redirects the browser to the IdP with its own state, nonce and PKCE challenge, separate from yours.
Checks at OhAuthCat
- IdP discovery document reachable
oidc_discovery_unreachable
- IdP discovery document reachable
Step 4 of 8: IdP → OhAuthCat
IdP returns a code
After the user signs in, the IdP redirects back to OhAuthCat with a code and OhAuthCat's state.
Checks at OhAuthCat
- State matches the broker's flow
invalid_state
- State matches the broker's flow
Step 5 of 8: OhAuthCat → IdP
Broker exchanges the IdP code
Server to server, OhAuthCat exchanges the code with the IdP's client secret and PKCE verifier, then validates the ID token.
Checks at OhAuthCat
- Token exchange succeeds
oidc_token_exchange_failed - ID token signature, issuer, audience, expiry, nonce
oidc_id_token_invalid - Email claim present
oidc_email_missing - Email verified by the IdP
oidc_email_not_verified
- Token exchange succeeds
Step 6 of 8: inside OhAuthCat
Admission and roles
The same domain, policy and role rules as for SAML.
Checks at OhAuthCat
- Email in a verified domain
email_outside_verified_domain - Sign-in policies allow it
sign_in_policy_denied - Role rules pick an optional role
- Email in a verified domain
Step 7 of 8: OhAuthCat → Your app
Code back to your callback
The browser is redirected to your exact redirect URI with a single-use code and your state. Your callback checks the state against the stored attempt and consumes it once.
Checks at Your app
- State matches the stored attempt
Step 8 of 8: Your app → OhAuthCat
Server-to-server code exchange
Your server posts the code, the PKCE verifier and the redirect URI to /v1/sso/token on the auth host. The browser is not involved. You receive an access token and the profile.
Checks at OhAuthCat
- Secret key authenticates your server
api_key_invalid - Code unused and under 60 seconds old
invalid_grant - PKCE verifier matches the challenge
pkce_verification_failed - Exact same redirect URI
redirect_uri_not_allowed
- Secret key authenticates your server
Without JavaScript, every step is listed in order. Use the left and right arrow keys to move between the flow tabs.
See how SSO works for the application side, IdP-initiated sign-in for the confirmation and handoff details, and IdP error fixes for errors the IdP shows before OhAuthCat is reached.