Organization authentication settings

Every Organization has a set of fields that control the authentication and provisioning of its Members. These controls have admin-like capabilities and should be updated deliberately.

The Organization auth settings are grouped by type of auth factor. The auth setting field names are prepended with an auth factor like email or sso or oauth. For example, all Organization fields that begin with email_* are settings that specifically affect provisioning and auth flows via Email Magic Links.

An Organization must always have at least one auth setting that allows new Members to be created and join. As a result, sso_jit_provisioning, email_jit_provisioning, email_invites cannot all be simultaneously set to NOT_ALLOWED.

Here is an example Organization object with its auth settings fully shown.

{
    "organization_name": "Example Org",
    "organization_slug": "example-org",
   
    // Auth settings for Email Magic Links
    "email_invites": "NOT_ALLOWED" | "RESTRICTED" | "ALL_ALLOWED",    
    "email_jit_provisioning": "NOT_ALLOWED" | "RESTRICTED",
    "email_allowed_domains": ["stytch.com"],

    // Auth settings for Single Sign On
    "sso_jit_provisioning": "NOT_ALLOWED" | "RESTRICTED" | "ALL_ALLOWED",
    "sso_default_connection_id": "...",
    "sso_jit_provisioning_allowed_connections": [
        "saml-connection-live-7111f7b1-9896-4ce3-a658-9e0707fc5192",
    ],
    "sso_active_connections": [
        { "connection_id": … },
        { "connection_id": … }      
    ]

  // Auth settings for Allowed Auth Methods
  "auth_methods": "RESTRICTED" | "ALL_ALLOWED",
  "allowed_auth_methods": ["sso", "magic_link", "password", "google_oauth", "microsoft_oauth"]

  // Auth settings for MFA
  "mfa_methods": "RESTRICTED" | "ALL_ALLOWED",
  "allowed_mfa_methods": ["sms_otp", "totp"]

    …
}

Auth settings for Email Magic Links:

  • If email_allowed_domains is empty
    • then email_invites cannot be set to RESTRICTED.
    • then email_jit_provisioning cannot be set to RESTRICTED.
  • If email_allowed_domains is not empty
    • and email_invites is set to RESTRICTED, then all new Members must have an email address that complies with email_allowed_domains in order to be invited by email.
    • and email_invites is set to ALL_ALLOWED, then any new Member can be invited to email.
    • and email_invites is set to NOT_ALLOWED, then email invites are disabled.
  • If email_allowed_domains is not empty
    • and email_jit_provisioning is set to RESTRICTED, then all new Members must have an email address that complies with email_allowed_domains in order to be provisioned via Email Magic Links.
    • and email_jit_provisioning is set to ALL_ALLOWED, then any new Member can be provisioned via Email Magic Links.
    • and email_jit_provisioning is set to NOT_ALLOWED, then JIT provisioning via Email Magic Links is disabled.
  • If email_allowed_domains is updated
    • then the entire list will be overwritten by the new value.
    • then all Members will remain active even if their email_address no longer complies with email_allowed_domains.
    • and either email_invites or email_jit_provisioning is set to RESTRICTED, then email_allowed_domains cannot be set to an empty array.

Auth settings for Single Sign On:

  • If sso_jit_provisioning_allowed_connections is empty
    • then sso_jit_provisioning cannot be set to RESTRICTED.
  • If sso_jit_provisioning_allowed_connections is not empty
    • and sso_jit_provisioning is set to RESTRICTED, then all new Members must have an SSO login that complies with sso_jit_provisioning_allowed_connections in order to be provisioned via SSO.
    • and sso_jit_provisioning is set to ALL_ALLOWED, then all new Members will be automatically provisioned via any of the Organization's sso_active_connections.
    • and sso_jit_provisioning is set to NOT_ALLOWED, then JIT provisioning via SSO is disabled.
  • If sso_jit_provisioning_allowed_connections is updated
    • then the entire list will be overwritten by the new value.
    • then all currently active Members will remain active even if their sso_registrations no longer complies with sso_jit_provisioning_allowed_connections.
    • and sso_jit_provisioning is set to RESTRICTED, then sso_jit_provisioning_allowed_connections cannot be set to an empty array.

Auth settings for Allowed Auth Methods:

  • If allowed_auth_methods is empty
    • then auth_methods cannot be set to RESTRICTED.
  • If allowed_auth_methods is not empty
    • and auth_methods is set to RESTRICTED, then all members looking to authenticate will be required to use one of these auth methods.
  • If allowed_auth_methods is updated
    • then the entire list will be overwritten by the new values.
    • then all currently active Members will remain active even if their auth methods no longer complies with allowed_auth_methods. However, the member will not be able to authenticate with the disallowed methods.
    • and auth_methods is set to RESTRICTED, then auth_methods cannot be set to an empty array.

Auth settings for Allowed MFA Methods:

  • If allowed_mfa_methods is empty
    • then mfa_methods cannot be set to RESTRICTED.
  • If allowed_mfa_methods is not empty
    • and mfa_methods is set to RESTRICTED, then all members looking to authenticate with MFA will be required to use one of these MFA methods.
  • If allowed_mfa_methods is updated
    • then the entire list will be overwritten by the new values.
    • then all currently active Members will remain active even if their MFA methods no longer complies with allowed_mfa_methods. However, the member will not be able to MFA authenticate with the disallowed methods.
    • and mfa_methods is set to RESTRICTED, then mfa_methods cannot be set to an empty array.