Single sign-on, JIT and MFA policy

Embed
Preview of the card
<a href="https://forumulate.com/p/watchtower/docs/sso"><img src="https://forumulate.com/api/public/orgs/watchtower/spaces/docs/pages/12b58fad-ef6b-4baa-b700-987b251eb29f/social-card.svg?v=3e7ae33eec8b" alt="Single sign-on, JIT and MFA policy" width="600" height="315"></a>

Org admins (ManageSecurity) manage the policy at GET|PUT /v1/orgs/{org}/sso or in Settings, Single sign-on and MFA.

Fields

Field

Meaning

atlas_connection_id

The Atlas connection that counts as "signed in through SSO".

domains

Email domains you claim. Only verified domains enforce or create members.

enforce_sso

People on a verified domain must sign in through the connection, else 403 sso_required. Needs a connection id.

jit_role

Role of a member created on first SSO sign-in (default read_only; never above engineer).

default_project_ids

Projects where the new member gets the same role.

break_glass_user_ids

Up to two members who may sign in without SSO (lockout recovery). MFA still applies.

require_mfa

The session's amr must contain mfa or otp, else 403 mfa_required. No amr counts as no MFA.

max_session_hours

1 to 12; caps the console session lifetime (default 12 h).

Verifying a domain

  1. Save the policy with the domain listed. The response carries domain_challenge.

  2. Publish a DNS TXT record _watchtower-challenge.<domain> with exactly that value.

  3. POST /v1/orgs/{org}/sso/domains/{domain}/verify. The lookup runs over DNS-over-HTTPS (WT_DNS_DOH_URL, default Cloudflare JSON API) with a 5 second timeout. Removing a domain from the list drops its verification.

How sign-in decides

After the Atlas token is verified, every org whose verified domain matches the email domain, plus every org the user belongs to, is consulted. The strictest rule wins: one unmet enforce_sso or require_mfa blocks the sign-in; the shortest max_session_hours applies. Orgs that are unrelated to the user are not consulted. The connection is read from the token claim named by WT_ATLAS_SSO_CLAIM (default connection_id) and is not re-verified against Atlas.

Every policy change is audited (org_sso.update, org_sso.domain_verify, org_sso.jit). Turning on enforcement without a working connection locks out everyone except the break-glass users, so set at least one.

Updated