Skip to content
Dashboard
Theme
Theme

From home-grown SAML

How to move connections from a SAML integration you built yourself to OhAuthCat.

View Markdown

Lever D keeps your application’s existing ACS or OIDC callback while your server forwards the response to OhAuthCat. Configure and test an active connection first; forwarding does not bypass setup or domain verification.

Use PATCH /v1/connections/{conn} with connections:write on the management API. Set forwarding.until to a future timestamp at most 366 days away, together with forwarding.acs_urls for SAML or forwarding.redirect_uris for OIDC. Each list has at most five HTTPS URLs without credentials or fragments. For SAML, set sp_entity_id to the audience your IdP already uses when required; non-default overrides are restricted to imported connections or connections with forwarding enabled.

Omitted URL lists keep their values; an omitted or null until turns forwarding off. Include the intended end date when updating URLs.

Send POST https://auth.ohauthcat.com/v1/sso/forwarded with an sso:forward secret key and the same environment’s publishable client_id. See the broker API for the request schema.

Protocol Fields
SAML connection, client_id, base64 saml_response, the receiving acs_url, and the original in_response_to for an SP-initiated request
OIDC connection, client_id, oidc_code, registered redirect_uri, original code_verifier and nonce

Send exactly one protocol response. With one registered SAML ACS, acs_url can be omitted; with several, name the receiving URL. Preserve your application’s state and session checks. IdP-initiated SAML remains refused unless explicitly enabled on the connection.

The broker uses the normal SAML/OIDC validators, including replay, signature, audience, time and verified-domain checks. SAML Destination and Recipient must match the registered app ACS where the response arrived. Success returns an access token and profile; verify tokens using the supported SDK verifier and check the profile’s organization before establishing your own session. Never log assertions, codes, secrets or tokens.

Disabled or expired forwarding returns sso_forwarding_disabled. Connection reads expose expires_in_days, a Lever B hint and the last recorded warning threshold while forwarding is configured.

The worker attempts owner/admin expiry notices at 30, 7 and 1 days. A window receives at most one warning at each crossed threshold; a delayed run uses the nearest crossed threshold. Changing the end date resets warnings. Failed mail sends are counted and are not retried, so do not rely on delivery as your deadline tracker. Warnings never extend the window. Move the IdP to Lever B before expiration.