Skip to main content
Back to documentation

SAML SSO Troubleshooting

Common SAML SSO issues organized by symptom. Each entry starts with what you're seeing, then explains the most likely cause and how to fix it.

If you're new to NaturalTTS SAML setup, start with the general setup overview and your IdP-specific guide (Okta, Microsoft Entra ID, Google Workspace).

Test Connection opens the IdP but I don't land back on the NaturalTTS dashboard

After authenticating at your IdP, you should be redirected back to NaturalTTS and land on /dashboard. If that doesn't happen, the SAML response is reaching NaturalTTS but something is rejecting it — or it isn't reaching NaturalTTS at all.

Likely cause: ACS URL mismatch between the IdP and NaturalTTS. The IdP is POSTing the SAML response to a URL that doesn't exist (or isn't your workspace's ACS endpoint).

How to check:

  1. In NaturalTTS /settings/sso, copy the ACS URL from the Service Provider details panel.
  2. In your IdP's SAML configuration, compare it character-by-character to the field labeled:
    • Okta: Single sign on URL
    • Entra: Reply URL (Assertion Consumer Service URL)
    • Google: ACS URL
  3. Any mismatch — extra trailing slash, http:// instead of https://, wrong workspaceId in the path — and the round-trip silently fails.

Fix: Paste the NaturalTTS ACS URL into the IdP exactly as shown.

I authenticated successfully at my IdP but get "Authentication failed" in NaturalTTS

You see your IdP's login screen, enter credentials, get redirected back to NaturalTTS, and land on a page that says Authentication failed. The HTTP status is 401.

Likely cause: signature verification failure. NaturalTTS received the SAML response but the signature doesn't match the certificate on file.

How to check:

  1. In NaturalTTS /settings/sso, note the certificate fingerprint shown next to the Certificate field (formatted as aabb:ccdd:eeff:0011).
  2. In your IdP, view the active SAML signing certificate and compare its fingerprint. Most IdP admin pages either display the fingerprint directly or let you download the cert (you can compute the fingerprint locally with openssl x509 -in cert.pem -noout -fingerprint -sha256 and compare the first 16 hex chars without colons).
  3. If the fingerprints differ, the IdP is signing with a different key than NaturalTTS has on file.

Most common subcause: the IdP rotated its signing certificate but NaturalTTS still has the old one. Download the current certificate from your IdP, click Replace next to the Certificate field in NaturalTTS, paste the new certificate, and click Update connection. Then run Test Connection again.

Less common subcause: the IdP is signing with a different algorithm than NaturalTTS expects. NaturalTTS accepts SHA-256 RSA signatures; if your IdP is configured to sign with SHA-1 (rare in modern setups), the signature won't verify. Switch the IdP to SHA-256.

The response body is intentionally generic (Authentication failed) — it never reveals which validation failed, to avoid giving useful feedback to attackers probing the endpoint. Use your IdP's logs to confirm the assertion was actually issued, then check the certificate as the first diagnostic step.

A user authenticates and lands in NaturalTTS, but in the wrong workspace

Users are reaching NaturalTTS but ending up in someone else's workspace, or seeing a workspace they shouldn't have access to.

Likely cause: the email domain configured for SAML is also claimed by another workspace's SAML config. NaturalTTS routes SAML logins by email domain, and domains are globally unique.

How to check:

  1. In NaturalTTS /settings/sso, confirm the Email domain field shows your organization's actual domain (e.g., acme.edu, not a generic example.com).
  2. Verify no other workspace in your account has SAML configured for the same domain. This shouldn't be possible — NaturalTTS rejects duplicate domain claims at save time with Email domain already configured for another workspace. But if you're seeing this symptom, the domains may have been configured at different times by different admins.

Fix: Each workspace's SAML configuration must use a domain that uniquely identifies that workspace's users. If your organization has multiple workspaces that should all use SAML, each needs a distinct email subdomain (e.g., teachers.acme.edu, students.acme.edu).

A user authenticates but lands with the wrong role

A new user signs in via SAML and is provisioned, but their role isn't what you expected (e.g., they're a member but you wanted them to be a teacher, or vice versa).

Two possible causes:

Cause 1: Default role for new users is set to something different than you intended.

Open NaturalTTS /settings/sso and check the Default role for new users dropdown in the SAML configuration form. Whatever's selected is the role assigned to every JIT-provisioned user. If you change it, only users created after the change get the new role; existing users keep their current role.

Cause 2: the user already existed in your workspace before SAML was enabled, and SAML didn't downgrade them.

NaturalTTS deliberately never reduces an existing user's role through SAML. If alice@acme.edu was already in your workspace as an admin before you enabled SAML, her next SAML sign-in matches the existing account and preserves the admin role — it does not reset her to the SAML default.

This is intentional: SAML configuration changes shouldn't be able to silently revoke admin access from a user who was elevated for a reason. If you want to change an existing user's role, do it explicitly from the Members page.

Fix: If you need to bulk-change roles after SAML rollout, do it from the Members page. SAML only sets roles for users it creates.

Some users can authenticate, others can't

A subset of your users can sign in via SAML, but others get an IdP-side error and never reach NaturalTTS.

Likely cause: the affected users aren't assigned to the SAML application in your IdP.

How to check:

  • Okta: open the NaturalTTS app → Assignments tab. Confirm the affected users (or a group they're in) are listed.
  • Entra: open the NaturalTTS Enterprise Application → Users and groups. Confirm the affected users are assigned. If Assignment required? is set to Yes in the application's Properties, only assigned users can sign in.
  • Google Workspace: open admin.google.com → Apps → Web and mobile apps → NaturalTTS → User access. Confirm the affected users are in an OU or group with access enabled.

Fix: assign the missing users to the SAML application in your IdP. Changes typically take effect immediately, except in Google Workspace where propagation can take a few minutes.

After enabling SAML, my password login stopped working for some users

Users at your SAML email domain can no longer sign in with their NaturalTTS password.

This is by design. Once SAML is enabled for an email domain, users at that domain must authenticate via SAML. The login form detects the domain match and routes them to your IdP automatically; the password field is bypassed for matching emails.

Users whose email is at a different domain (e.g., the workspace owner using a @gmail.com email, or a teammate at a contractor company) are unaffected — they continue to use password or OAuth login.

If you need to temporarily allow password login again: disable SAML for your workspace. In NaturalTTS /settings/sso, open the Enable SSO for this workspace card and click Disable SSO. Domain routing stops within a few seconds; the configuration is preserved so you can re-enable later without re-entering anything.

My IdP certificate expired and now no one can log in

After a certificate expires, every SAML sign-in attempt fails signature verification, even for users who had previously been working.

Fix:

  1. In your IdP, generate or download a new SAML signing certificate.
  2. In NaturalTTS /settings/sso, click Replace next to the Certificate field.
  3. Paste the new certificate (including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines).
  4. Click Update connection.
  5. Run Test Connection to verify the new cert works before relying on it for real sign-ins.

The Recent SSO Activity log records this as a saml.config.updated event with previous and new certificate fingerprints. The cert bytes themselves are never logged — only the fingerprints — so the log is safe to share with compliance auditors as proof of rotation.

Preventing the next expiration: most IdPs send email reminders before SAML certificates expire. Configure those reminders to go to a monitored alias (not a single person's inbox) so the rotation gets done before the cert dies.

I want to use SAML for some users and password login for others at the same domain

Users at the same email domain need to be split: some via SAML, some via password.

This isn't supported today. Domain routing in NaturalTTS is all-or-nothing: every user at a configured SAML domain is routed to the IdP.

Workarounds:

  • Subdomain split. If your organization has email subdomains (teachers.acme.edu, staff.acme.edu), configure SAML for one subdomain only. Users at the other subdomains continue to use password or OAuth login.
  • Separate email for SAML-exempt users. A user who needs password login can be invited with a different email (a personal address, or an alias not under the SAML domain). This works for a small number of exceptions but is fragile at scale.
  • OAuth for some users. Google OAuth still works for users at the SAML domain if you haven't enabled SAML — but once SAML is enabled, the email-domain match takes precedence and OAuth is bypassed for matching emails.

Most organizations resolve this by ensuring everyone in the SAML domain has IdP access. If you have a structural reason this isn't possible, contact support to discuss whether your use case fits the domain-routing model at all.

The "Test Connection" button is disabled

In /settings/sso, the Open IdP test login button is greyed out and clicking it does nothing.

Likely cause: the saved SAML configuration is incomplete. Test Connection requires Entity ID, SSO URL, Certificate, and Email domain all set on the saved record (not just typed in the form). Any unsaved changes or missing fields disable the button.

Fix: ensure all four SAML fields are filled in, click Update connection, then refresh the page. The button activates once the saved configuration is complete.

The "Enable SSO" button is disabled even after saving

In /settings/sso, the Enable SSO button stays disabled.

Likely cause: the saved configuration is incomplete (same conditions as Test Connection). The Enable button has the same completeness check.

Fix: ensure all four SAML fields are saved (not just typed). The page shows "Save a complete configuration before enabling" when this is the issue.

I rotated my certificate but new sign-ins still fail

You replaced the certificate in NaturalTTS, but Test Connection still fails or live users still can't sign in.

Two likely causes:

Cause 1: Browser cached the old SAML response. Some IdPs cache SAML responses or session state. Open Test Connection in an incognito/private window to avoid this.

Cause 2: The new certificate isn't actually active in your IdP yet. Some IdPs let you stage a new certificate before activating it. Confirm the new cert is the one your IdP is currently using to sign assertions, not just one you uploaded.

Fix: verify the active cert in your IdP, ensure its fingerprint matches the one shown in NaturalTTS, and retry in a fresh browser session.

I see SAML activity in the log for sign-ins I didn't expect

The Recent SSO Activity log shows saml.signin events for users you didn't manually invite.

Likely cause: JIT provisioning is enabled (the default), and the listed users authenticated via SAML and were auto-created. This is the expected behavior.

Each log entry shows:

  • The user who signed in (their NaturalTTS user ID; resolve to email via the Members page).
  • Whether they were a new user (isNewUser: true).
  • Whether they were added to the workspace (addedToWorkspace: true — usually true for new users; can be false for an existing user signing in to a workspace they already belonged to).

If JIT provisioning is creating users you don't want:

  • Tighten access in your IdP — only assign the SAML app to users who should have NaturalTTS.
  • Or disable JIT in the NaturalTTS configuration form. With JIT off, only users already in the workspace (added manually from the Members page) can sign in via SAML; unknown users hit an Authentication failed response.

Where to get more help

If your issue isn't in this list, contact NaturalTTS support with:

  • Your workspace name.
  • Your SAML email domain.
  • Your IdP (Okta, Entra, Google Workspace, or other).
  • The specific symptom you're seeing, including any error message text.
  • The approximate time the issue started.
  • Whether anything changed recently (cert rotation, IdP migration, plan change).

Do not send:

  • Your IdP certificate (sensitive material).
  • The SAML response XML (contains user assertions and signed data).
  • User passwords (NaturalTTS support never needs them).

Support can investigate using only the workspace identifier and the symptom description — sensitive material is not required for diagnosis.