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.
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.
Hook points
Section titled “Hook points”| 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 |
Create a hook
Section titled “Create a hook”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 / replaces it. The CLI uses ohauthcat sign-in-hooks.
The request
Section titled “The request”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.
The answer
Section titled “The answer”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,expand the like) are reserved and cannot be set.
Claims appear in the profile under claims.
When the hook fails
Section titled “When the hook fails”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.
Delivery log and test events
Section titled “Delivery log and test events”GET /(scopev1/ sign_in_hooks/ {hook}/ deliveries policies:read) lists the hook’s recent calls. Forpre_profile_issueeach row is a sign-in with itsoutcome(allowed,denied,failed_openorfailed_closed), the HTTP status your endpoint answered and the latency. Forpost_directory_eventeach row is a delivery with its state (pending,deliveredorfailed) and attempts. Payloads are never kept.POST /(scopev1/ sign_in_hooks/ {hook}/ test policies:write) sends a synthetic, signed request withtest: trueto your endpoint and shows the result. It does not appear in the delivery log; it is recorded in your audit log assign_in_hook.tested.