SAML SSO Setup

This guide is the entry point for configuring SAML 2.0 single sign-on between your identity provider (IdP) and your NaturalTTS workspace. If you've configured SAML for other SaaS apps before, the procedure here is familiar — what's specific to NaturalTTS is called out explicitly.

Estimated time: 20–30 minutes once you have IdP admin access.

What SAML SSO does for your workspace

SAML SSO lets users at your organization sign in to NaturalTTS using your existing identity provider — the same account they use for email, your LMS, and other corporate apps. There's no separate password to manage for NaturalTTS.

When you enable SAML for a workspace, any user whose email matches a configured domain (for example, @stanford.edu) is automatically routed to your IdP's login page when they visit NaturalTTS. After authenticating with your IdP, they land in your workspace. New users are provisioned automatically on first sign-in, with the default role you choose.

When SAML is the right fit

SAML is a good fit when:

• Your organization manages user identity centrally (Okta, Microsoft Entra ID, Google Workspace, OneLogin, etc.) and you want NaturalTTS access governed alongside other corporate apps.
• You have compliance or audit requirements that mandate centralized authentication.
• You have more than a handful of users and want to avoid managing per-user NaturalTTS passwords.
• You want to revoke NaturalTTS access by deactivating a user in your IdP, with no NaturalTTS-side cleanup needed.

SAML is not the right fit when:

• You have one or two admin users and no central IdP. Google OAuth or email/password is simpler to set up and maintain.
• Users mix personal and work accounts for NaturalTTS. Domain-routed SAML applies to everyone at the configured email domain — there's no partial-coverage mode.
• You're piloting NaturalTTS with a small group before institutional rollout. Defer SAML until the pilot is approved.

What you need before starting

• Owner or Admin role on the NaturalTTS workspace.
• Admin access to your IdP (specifically: permission to create a new SAML application or service provider connection).
• The email domain you want to use for routing (e.g., acme.edu). This domain must be unique to your workspace — no other NaturalTTS customer can claim the same domain.
• 20–30 minutes of focused time.

Setup sequence (high level)

The full setup is six steps. Each step is short on its own; the time goes into copy-pasting values between two browser tabs and confirming the test connection works.

1. In NaturalTTS: open /settings/sso and copy the Service Provider details (SP Entity ID, ACS URL, SP Metadata URL).
2. In your IdP: create a new SAML application and paste the values from step 1. Configure the IdP to send email, firstName, lastName, and displayName as SAML attributes.
3. In your IdP: copy the IdP Entity ID (Issuer), SSO URL, and X.509 Certificate. Assign the new SAML app to the users who should have NaturalTTS access.
4. In NaturalTTS: paste the IdP values from step 3 into the SAML configuration form. Set the email domain, choose a default role for new users, leave JIT Provisioning enabled, and save.
5. In NaturalTTS: click Test Connection. A new tab opens to your IdP. Authenticate and confirm you land on the NaturalTTS dashboard.
6. In NaturalTTS: read the enable warning, check the confirmation, and click Enable SSO.

After step 6, the SAML flow is live for your email domain.

IdP-specific guides

Follow the guide for your identity provider. Each one walks through the IdP-side configuration in detail with the exact menu paths and field names.

• Okta
• Microsoft Entra ID (formerly Azure AD)
• Google Workspace

If your IdP isn't listed (OneLogin, Ping, Auth0, JumpCloud, ADFS, a generic SAML 2.0 provider, etc.), the six-step sequence above still applies. The terminology will vary — your IdP may call the SP Entity ID an "Audience URI" or "Entity ID", and the ACS URL a "Reply URL" or "Single Sign-On URL". The required SAML attribute names (email, firstName, lastName, displayName) are the same across all IdPs. The troubleshooting reference covers issues common to all IdPs.

What your users experience after SAML is enabled

• A user enters their email on the NaturalTTS login page.
• If the domain matches your SAML configuration, the user is redirected to your IdP. They never see a NaturalTTS password prompt.
• After authenticating at your IdP, they land in your workspace.
• If the user is new to NaturalTTS, an account is created automatically with the default role you configured. They're added to your workspace as a member of that role.
• If the user is already in your workspace with a different role (for example, an admin you promoted manually), their existing role is preserved. SAML never downgrades an existing user.
• The user can continue using NaturalTTS as long as their IdP account is active. If you deactivate them in your IdP, their next sign-in attempt fails — there is no separate NaturalTTS deactivation step.

Default role considerations

When configuring SAML, you'll pick a default role for new users provisioned via SSO. The available roles are:

Owner is intentionally not selectable as a SAML default. The Owner role controls billing, contract terms, and workspace deletion; allowing it to be JIT-assigned would mean any compromise of your identity provider grants the attacker full workspace ownership. Excluding Owner from automated provisioning caps the worst-case impact at admin level — still serious, but recoverable by an Owner who authenticated through a different path.

Recommended default: Member. You can promote individual users to higher roles from the Members page after they've signed in for the first time.

Before you enable

The Enable button in /settings/sso is gated behind a confirmation checkbox for a reason:

Enabling SAML routes all users at @yourdomain through your IdP. Users without IdP access cannot sign in via password while SAML is enabled for their domain.

In practice this means:

• Any pre-SAML user with an @yourdomain email loses password access. They sign in via SAML instead — and because their email matches an existing NaturalTTS account, they're matched to it on first SAML sign-in, not duplicated.
• If a user had a @gmail.com address signed up to your workspace, they're unaffected — SAML routing is per email domain.
• If you need to disable SAML for any reason, the Disable SSO button in /settings/sso restores password and OAuth login immediately for the configured domain.

Always run Test Connection before clicking Enable. The confirmation checkbox exists because a misconfigured SAML connection locks out every user at your domain until you disable it again. If you sign in with an @yourdomain email yourself, make sure a teammate has Owner or Admin access from a different email before enabling — they can disable SAML for you if anything goes wrong.

Maintaining your connection

• Certificate rotation. If you rotate your IdP signing certificate, paste the new certificate into the NaturalTTS configuration form (click Replace in the Certificate field). Test Connection before relying on it; the old certificate stops being accepted as soon as you save.
• Configuration changes. Any change you save to the SAML configuration is recorded in the Recent SSO Activity log on /settings/sso. The log shows which fields changed, who changed them, and when. Certificate rotations show a fingerprint pair (previous + new) for audit purposes; the certificate bytes themselves are never displayed or logged.
• Audit. Every successful SAML sign-in is recorded with the user, workspace, and whether they were provisioned by JIT. Use this to confirm rollout health after enabling SAML.

Troubleshooting

If Test Connection fails, or users report problems after you enable SAML, the troubleshooting reference covers the common cases organized by symptom (authentication failures, wrong role assignment, certificate issues, etc.).

If the troubleshooting guide doesn't help, contact NaturalTTS support with the following details ready: your workspace name, the email domain you configured, the IdP you're using, and a screenshot or text of any error message you see. Do not send your IdP certificate or any SAML response XML — both contain sensitive material.