Single Sign On Blueprint

Enterprise SSO via SAML 2.0 and OIDC with JIT provisioning

   
Feature single-sign-on
Category Auth
Version 1.0.0
Tags authentication, sso, saml, oidc, enterprise, identity, federation
YAML Source View on GitHub
JSON API single-sign-on.json

Fields

Name Type Required Label Description
idp_entity_id text Yes IdP Entity ID Validations: required, maxLength
metadata_url url No IdP Metadata URL Validations: url
certificate text Yes X.509 Certificate Validations: required
attribute_mapping json Yes Attribute Mapping  
enabled boolean Yes SSO Enabled  
sso_protocol select Yes SSO Protocol Validations: required, oneOf
organization_id text Yes Organization ID Validations: required
default_role text No Default Role for JIT-Provisioned Users  
domain_whitelist text No Allowed Email Domains  
sign_requests boolean No Sign Authentication Requests  
sp_entity_id text Yes Service Provider Entity ID  
acs_url url Yes Assertion Consumer Service URL Validations: required, url
slo_url url No Single Logout URL  

Rules

  • security:
    • assertion_validation:
      • verify_signature: true
      • verify_issuer: true
      • verify_audience: true
      • verify_destination: true
      • verify_conditions: true
      • clock_skew_seconds: 120
      • replay_prevention: true
    • certificate_management:
      • allow_multiple_certs: true
      • validate_expiry: true
      • expiry_warning_days: 30
      • min_key_size_bits: 2048
    • encryption:
      • encrypt_assertions: false
      • sign_requests: true
      • algorithm: RSA_SHA256
    • rate_limit:
      • window_seconds: 60
      • max_requests: 20
      • scope: per_organization
  • jit_provisioning:
    • enabled: true
    • default_role: member
    • sync_attributes_on_login: true
    • deactivate_on_removal: false
  • session:
    • bridge_idp_session: true
    • max_session_hours: 8
    • force_reauth_on_sensitive_action: true
  • saml:
    • binding: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
    • name_id_format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
    • authn_context: urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
  • oidc:
    • response_type: code
    • scopes: openid, email, profile
    • pkce_required: true
    • token_endpoint_auth: client_secret_post

Outcomes

Rate_limited (Priority: 1) — Error: SSO_RATE_LIMITED

Given:

  • request_count (computed) gt 20

Result: show “Too many authentication attempts. Please wait a moment.”

Sso_not_configured (Priority: 2) — Error: SSO_NOT_CONFIGURED

Given:

  • ANY: sso_config (db) not_exists OR enabled (db) eq false

Result: show “SSO is not configured for your organization. Please contact your administrator.”

Invalid_assertion (Priority: 3) — Error: SSO_INVALID_ASSERTION

Given:

  • ANY: assertion_signature (computed) neq valid OR assertion_audience (computed) neq sp_entity_id OR assertion_not_on_or_after (computed) lt now

Then:

  • emit_event event: sso.failed

Result: show “Authentication failed. Please try again or contact your administrator.”

Replay_attack_detected (Priority: 4) — Error: SSO_REPLAY_DETECTED

Given:

  • assertion_id (computed) exists

Then:

  • emit_event event: sso.replay_detected

Result: show “Authentication failed. Please try again.”

Domain_not_allowed (Priority: 5) — Error: SSO_DOMAIN_NOT_ALLOWED

Given:

  • domain_whitelist (db) exists
  • user_email_domain (computed) not_in domain_whitelist

Then:

  • emit_event event: sso.failed

Result: show “Your email domain is not authorized for this organization.”

Jit_provision_new_user (Priority: 6) | Transaction: atomic

Given:

  • assertion_valid (computed) eq true
  • local_user (db) not_exists
  • jit_provisioning_enabled (db) eq true

Then:

  • create_record target: user — Create local user from IdP attributes via JIT provisioning
  • set_field target: role value: default_role — Assign default organization role
  • create_record target: session — Create authenticated session
  • emit_event event: sso.provisioned
  • emit_event event: sso.authenticated

Result: new user provisioned and authenticated — redirect to application

Existing_user_login (Priority: 10) | Transaction: atomic

Given:

  • assertion_valid (computed) eq true
  • local_user (db) exists
  • status (db) neq disabled

Then:

  • set_field target: user_attributes value: idp_attributes when: sync_attributes_on_login == true — Sync user attributes from IdP (name, email, groups)
  • create_record target: session — Create authenticated session bridged to IdP session
  • emit_event event: sso.authenticated

Result: redirect to application

Errors

Code Status Message Retry
SSO_RATE_LIMITED 429 Too many authentication attempts. Please wait a moment. Yes
SSO_NOT_CONFIGURED 404 SSO is not configured for your organization No
SSO_INVALID_ASSERTION 401 Authentication failed. Please try again or contact your administrator. Yes
SSO_REPLAY_DETECTED 403 Authentication failed. Please try again. Yes
SSO_DOMAIN_NOT_ALLOWED 403 Your email domain is not authorized for this organization. No
SSO_CERTIFICATE_EXPIRED 500 SSO configuration error. Please contact your administrator. No
SSO_PROVISIONING_DISABLED 403 Automatic account provisioning is not enabled. Contact your administrator. No
SSO_ACCOUNT_DISABLED 403 This account has been disabled. Please contact your administrator. No

Events

Event Description Payload
sso.authenticated User authenticated via SSO user_id, organization_id, protocol, timestamp
sso.provisioned New user provisioned via JIT from IdP user_id, organization_id, idp_entity_id, timestamp
sso.failed SSO authentication attempt failed organization_id, idp_entity_id, timestamp, reason
sso.replay_detected SAML assertion replay attack detected organization_id, assertion_id, timestamp, ip_address
sso.certificate_expiring IdP signing certificate nearing expiry organization_id, certificate_expiry, days_remaining
Feature Relationship Reason
login recommended SSO is an alternative to password-based login for enterprise users
oauth-social-login optional Organizations may use OAuth for non-enterprise social login alongside SSO
session-management recommended SSO sessions need tracking, bridging, and revocation
multi-factor-auth optional MFA may be enforced at the IdP level or additionally at SP
logout required Single logout (SLO) must terminate both SP and IdP sessions
UI Hints ```yaml layout: single_column_centered max_width: 480px show_logo: true login_discovery: email_domain_detection: true prompt: Enter your work email to continue admin_configuration: show_metadata_upload: true show_manual_config: true show_test_connection: true show_certificate_status: true actions: primary: label: Continue with SSO type: submit full_width: true links: - label: Sign in with password instead target: login position: below_form accessibility: autofocus: email aria_live_region: true loading: disable_button: true show_spinner: true redirect_message: Redirecting to your identity provider... ```