Skip to content
Dashboard
Theme
Theme

Sign-in hooks

Call your own HTTPS endpoint to allow or deny an SSO sign-in and add custom claims before the profile is issued.

View Markdown

A sign-in hook is an HTTPS endpoint you run. OhAuthCat calls it during each enterprise SSO sign-in, after every security check has passed and before the profile is issued, and your endpoint answers allow or deny, optionally adding claims. Sign-in hooks are a Business and Enterprise feature.

Point When Your answer
pre_profile_issue During the sign-in, synchronously Allow or deny, plus claims
post_directory_event After a directory change is stored, delivered by a background job with retries (8 attempts) Ignored

POST /v1/sign_in_hooks (scope policies:write) with point, url, timeout_ms (default 2000, at most 5000) and fail_mode. The answer contains the signing secret once; POST /v1/sign_in_hooks/{hook}/rotate_secret replaces it. The CLI uses ohauthcat sign-in-hooks.

A signed JSON POST, verified the same way as webhooks, with an OhAuthCat-Hook-Call-Id header. The body has call_id, point, created_at and sign_in: the sign-in, environment, organization, connection and profile IDs, connection type, email, groups, role and, with a risk policy, risk_score and risk_reasons.

Answer 200 with a JSON body signed with the same secret, echoing the call_id: decision (allow or deny), an optional reason (up to 200 characters) and optional claims. Limits:

  • the whole answer at most 8 KiB, with no redirects followed;
  • at most 16 claims and 2 KiB in total; names are lowercase (^[a-z][a-z0-9_]{0,39}$), strings up to 256 characters, lists up to 16 items;
  • profile fields and JWT claims (email, sub, role, groups, exp and the like) are reserved and cannot be set.

Claims appear in the profile under claims.

A timeout, a non-200 status, a bad signature, an answer for another call or an answer outside the limits is a failure. With fail_mode: closed (the default) the sign-in is refused with sign_in_hook_unavailable; with open it continues without claims. A deny answers sign_in_hook_denied. Every call appears as a hook step on the sign-in timeline.

  • GET /v1/sign_in_hooks/{hook}/deliveries (scope policies:read) lists the hook’s recent calls. For pre_profile_issue each row is a sign-in with its outcome (allowed, denied, failed_open or failed_closed), the HTTP status your endpoint answered and the latency. For post_directory_event each row is a delivery with its state (pending, delivered or failed) and attempts. Payloads are never kept.
  • POST /v1/sign_in_hooks/{hook}/test (scope policies:write) sends a synthetic, signed request with test: true to your endpoint and shows the result. It does not appear in the delivery log; it is recorded in your audit log as sign_in_hook.tested.