SAML SSO

EmailBuilder supports SAML 2.0 single sign-on for accounts on the Orchestra plan. Configure your identity provider (IdP), point it at our SP, and your team signs in with whatever credentials they use for the rest of your stack.

Prerequisites

• Orchestra plan.
• An IdP that supports SAML 2.0 — Okta, Google Workspace, Azure AD (Entra ID), OneLogin, JumpCloud, etc.
• Admin access to that IdP.
• One or more email domains you control (e.g. acme.com).

How tenancy works

SAML in EmailBuilder is domain-keyed. You configure one or more email domains on your account; users with email addresses in those domains route to your IdP at sign-in. Users with other domains continue to use password/Google login.

This means:

• [email protected] → routed to your SAML IdP.
• [email protected] → uses password or Google OAuth as usual (unless explicitly invited and provisioned).

A given email domain can only map to one EmailBuilder account at a time.

Setup

1. Generate SP metadata

In the app, go to Account → Settings → SAML SSO. EmailBuilder generates the Service Provider details your IdP needs:

Field	Value
SP Entity ID	https://app.emailbuilder.ai/saml/<account-id>
ACS URL (Assertion Consumer Service)	https://app.emailbuilder.ai/api/auth/saml/acs
NameID format	Email address
Binding	HTTP-POST

Download the XML metadata file from the same page — most IdPs accept it for one-click setup.

2. Create the IdP app

In your IdP, create a new SAML 2.0 application using the SP metadata or values above. Set the audience to the SP Entity ID and the ACS to our ACS URL.

For attribute claims, EmailBuilder reads:

• NameID — the user's email address (required).
• email or mail — the user's email (required).
• given_name or firstName — first name (optional).
• family_name or lastName — last name (optional).

Map your IdP's user attributes to these. Most IdPs default to the right values for OIDC-style claims.

3. Paste IdP details into EmailBuilder

Back in EmailBuilder, paste:

• IdP Entity ID — the issuer URL from your IdP.
• IdP SSO URL — the sign-in URL your IdP provides.
• IdP Certificate — the X.509 certificate, in PEM format (-----BEGIN CERTIFICATE----- block).

Certificates are encrypted at rest with mongoose-field-encryption.

4. Configure domain mapping

Add the email domains that should route to this SAML config (one per line):

acme.com
acme.co.uk

These are the domains EmailBuilder will check when a user enters their email at sign-in. Public mailbox domains (gmail.com, yahoo.com, outlook.com, etc.) are blocked — adding them would let a misconfigured IdP mint accounts on consumer email.

5. Toggle options

Option	What it does
Enforce for domain	When on, password and Google login are hidden for users with matching email domains — SSO becomes mandatory for them.
Auto-provision users	When on, users authenticating for the first time are created automatically (JIT provisioning). When off, only existing team members can sign in via SAML.
Default role for new users	Role assigned to JIT-provisioned users (User or Admin).

Save the config. The status badge flips to Active.

6. Test

In an incognito window:

1. Go to the sign-in page.
2. Enter an email in the SAML-mapped domain.
3. You should be redirected to your IdP.
4. After authenticating, you should land in EmailBuilder.

If anything fails, the Settings page surfaces the error in the SAML config status. Common issues:

• Certificate mismatch — the PEM cert you pasted doesn't match the one your IdP is signing with. Re-export and re-paste.
• NameID missing — your IdP isn't asserting the user's email as NameID. Adjust the IdP's attribute mapping.
• Audience mismatch — the IdP app's audience doesn't match the SP Entity ID.

Just-in-time provisioning

With Auto-provision users on, the first SAML login for an unknown email creates the user in your account:

• The IdP-provided email, first name, last name fill the user profile.
• provider is set to saml — this user can only sign in via SAML.
• The default role (configured above) is assigned.
• emailConfirmed is set to true (the IdP is trusted to verify email).

Existing users in your account whose emails match a SAML-mapped domain get linked to SAML on their next SSO sign-in. They keep their existing roles and data.

What's not supported

• Single Logout (SLO). Signing out of EmailBuilder doesn't propagate to the IdP. Sign out of the IdP separately if you want a full sign-out.
• IdP-initiated SAML. SP-initiated only — start at our sign-in page, not at the IdP.
• Group/role provisioning from SAML claims. All JIT-provisioned users get the default role you configured; group-based role assignment isn't implemented today.
• Per-project access via SAML. SAML manages account membership; access is account-wide.

Known limitations

• Server-side enforcement of "Enforce for domain" — the option hides password login in the UI but the server-side check is currently UI-driven. If your security policy requires hard server enforcement, contact support for current state.
• The internal session token between the ACS callback and the final NextAuth sign-in has a 2-minute window — this is short by design and not configurable.

Disabling SAML

Toggle the Enabled switch off on the SAML Settings page. SAML-provisioned users will no longer be able to sign in via SSO; admins can re-enable any time.

To permanently remove the configuration, click Delete config. The IdP details and certificate are removed; SAML-provisioned users retain their accounts but can no longer authenticate (until you re-add SAML or convert them to password users).

Recommended IdP setup

For mature security postures:

• Enforce for domain = on. Prevents password compromises from being useful.
• Auto-provision = on. Avoids the friction of pre-creating users; they show up when they sign in.
• Default role = User. Admin role should be granted explicitly after the fact, not by default.
• Enforce 2FA at the IdP, not EmailBuilder. Your IdP is now the source of truth for identity; centralise 2FA there.