SAML sign-in

Embed
Preview of the card
<a href="https://forumulate.com/p/watchtower/guides/saml"><img src="https://forumulate.com/api/public/orgs/watchtower/spaces/guides/pages/2272fdaf-f64a-48a4-96be-9f93eac8720e/social-card.svg?v=3e7ae33eec8b" alt="SAML sign-in" width="600" height="315"></a>

Status: pre-audit. The XML parser, canonicalization and signature checks are hand-written. They have had an internal code review, but no external security audit, and they have not yet run against a real identity provider (Okta, Entra, ADFS, Keycloak, Google). Test with your IdP before relying on them, and do not treat them as audited.

Connecting

Add a connection under organization settings with your IdP's metadata (metadata_xml or an https metadata_url), or set idp_entity_id, idp_sso_url and idp_certs directly. Give the IdP the SP metadata at /v1/auth/saml/<connection id>/metadata. WT_PUBLIC_URL and WT_SECRET_KEY must be set.

What the IdP must send

  • A signed assertion. The Response signature alone counts only with want_assertions_signed off.

  • A stable NameID: persistent, or an email that is never reassigned. Transient is refused. The account is the NameID together with its Format, so changing either creates a new user.

  • An AuthnStatement, an audience restriction, and an assertion under 1 hour old.

  • Attributes matched by Name. email_attr and the groups attribute do not match FriendlyName.

  • Exclusive c14n with SHA-256 or stronger. AES-CBC and RSA PKCS#1 v1.5 are refused, which rules out IdPs that cannot avoid them.

Settings that weaken a connection

Setting

Risk

allow_idp_initiated

Login CSRF: a member of the IdP can sign someone else's browser in as themselves.

allow_sha1

SHA-1 signatures can be forged with enough effort. Legacy IdPs only.

allow_encrypted_assertions

RSA decryption of unauthenticated input with a crate that has an unfixed timing advisory (RUSTSEC-2023-0071). HTTPS already protects the assertion in transit. Needs its own decryption_secret and sp_decryption_cert_pem; it never uses the signing key. The console form has a field for the decryption key.

Disabling or deleting a connection, or changing its idp_certs, ends the sessions it issued. Changes to these settings are recorded in the audit log.

Updated