SSO (per-org)

Documentation Index

Fetch the complete documentation index at: https://docs.pylonsync.com/llms.txt

Use this file to discover all available pages before exploring further.

• OIDC — discovery doc + PKCE (S256) + nonce + state, single-use.
• SAML 2.0 — SP-Initiated AuthnRequest (HTTP-Redirect), Response via HTTP-POST to the ACS, XML signature verified with the configured IdP cert.

​

Trust model

​

Endpoints

​

Configuring OIDC SSO

curl -X PUT https://your-app/api/auth/orgs/org_acme/sso \
  -H 'Authorization: Bearer pylon_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "issuer_url": "https://acme.okta.com",
    "client_id": "0oa1abcd2efgh3ijk4",
    "client_secret": "OktaSecret...",
    "default_role": "member",
    "email_domains": ["acme.com", "acme.io"]
  }'

{ "configured": true }

​

OIDC sign-in flow

1. Client redirects user to GET /api/auth/orgs/org_acme/sso/start?callback=<success_url>&error_callback=<error_url>.
2. Pylon validates both URLs against manifest.auth.trustedOrigins (or PYLON_TRUSTED_ORIGINS), mints a single-use state + PKCE verifier + nonce, persists them, and 302s to the IdP’s authorization endpoint with scope=openid email profile, response_type=code, code_challenge_method=S256.
3. IdP authenticates the user and 302s back to /api/auth/orgs/org_acme/sso/callback?code=...&state=....
4. Pylon consumes the state (single-use), exchanges code for tokens against the IdP’s token endpoint with the PKCE verifier, validates the id_token’s nonce claim per OIDC §3.1.2.1, fetches userinfo for email + name.
5. Pylon either matches the user’s email to an existing User row OR creates one. emailVerified is stamped to now — the IdP just vouched for it.
6. If the user isn’t already a member of the org, they’re added with the configured default_role. Idempotent — re-signing-in via SSO doesn’t downgrade an admin.
7. Pylon mints a session, writes the auth cookie, audits a SignIn event with method=org_sso, and 302s to the caller’s callback URL.

​

Configuring SAML

curl -X PUT https://your-app/api/auth/orgs/org_acme/saml \
  -H 'Authorization: Bearer pylon_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "idp_entity_id": "https://idp.okta.com/exk1abcd...",
    "idp_sso_url": "https://acme.okta.com/app/abc/sso/saml",
    "idp_x509_cert_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "default_role": "member",
    "email_domains": ["acme.com"],
    "email_attribute": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "name_attribute": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
  }'

​

SAML sign-in flow

1. Client redirects to GET /api/auth/orgs/org_acme/saml/start?callback=<success_url>&error_callback=<error_url>.
2. Pylon builds a SAML AuthnRequest, deflates + base64-encodes it for the HTTP-Redirect binding, 302s to the IdP’s SSO URL with SAMLRequest=...&RelayState=<state>.
3. IdP authenticates the user and HTTP-POSTs a SAMLResponse to POST /api/auth/orgs/org_acme/saml/acs.
4. Pylon parses the XML, verifies the digital signature against the configured idp_x509_cert_pem using xmlsec1, validates assertions, extracts the email + display name from the configured attributes.
5. Same user-lookup / auto-join / session-mint flow as OIDC.

# macOS
brew install libxmlsec1 libxml2

# Debian / Ubuntu
apt-get install libxmlsec1-dev libxml2-dev

​

Email-domain discovery

curl https://your-app/api/auth/sso/discover?email=alice@acme.com

{
  "org_id": "org_acme",
  "kind": "oidc",
  "start_url": "/api/auth/orgs/org_acme/sso/start"
}

{
  "org_id": "org_acme",
  "kind": "saml",
  "start_url": "/api/auth/orgs/org_acme/saml/start"
}

​

Security guarantees

• State + PKCE + nonce on OIDC. State is single-use, scoped to the org, and re-used or wrong-org states return 403 INVALID_SSO_STATE.
• PKCE S256 binds the token exchange to the same client that started the flow. A leaked authorization code can’t be redeemed without the matching code_verifier.
• Nonce binding per OIDC §3.1.2.1 defeats id_token replay across distinct sign-in attempts.
• Redirect-URL allowlist — both callback and error_callback are validated against manifest.auth.trustedOrigins (or PYLON_TRUSTED_ORIGINS) before the IdP gets to see them. Loopback is auto-trusted.
• SAML signature verification with xmlsec1 — assertions without a valid signature from the configured cert are rejected.
• https:// enforced on idp_sso_url.
• Freemail domain blocklist — common consumer-mail domains (gmail, yahoo, outlook, icloud, hotmail, live, msn, aol, mail.com, protonmail / proton.me, gmx, yandex, qq, 163, 126, fastmail, mac.com, me.com, the full list lives in BLOCKLIST_FREEMAIL_DOMAINS in crates/auth/src/org_sso.rs) refuse to be claimed by any org.
• Operator domain allowlist via PYLON_SSO_ALLOWED_DOMAINS=acme.com,acme.io,....
• Default role can never be owner — IdP-mediated owner-promotion would let an IdP misconfiguration silently hand over org control.
• client_secret encrypted at rest when PYLON_SECRET is set.
• Auto-join is idempotent — re-signing-in via SSO doesn’t change an existing member’s role. To re-apply the IdP’s default role, remove the membership and let the next sign-in re-add it.

​

Configuration

PYLON_PUBLIC_URL=https://your-app.com           # required for SSO callbacks
PYLON_SECRET=<openssl rand -hex 32>             # encrypts client_secret at rest
PYLON_TRUSTED_ORIGINS=https://your-app.com,...  # OAuth callback allowlist (or declare in manifest.auth.trustedOrigins)
PYLON_SSO_ALLOWED_DOMAINS=acme.com,acme.io      # optional: positive domain allowlist

​

Where to go next

• Organizations — the org model SSO auto-joins users to
• OAuth — global OAuth (Google + GitHub for everyone) vs per-org SSO