SAML SSO Troubleshooting Guide

This guide helps you identify and fix the most common SAML configuration issues between Tellius (Service Provider / SP) and your Identity Provider (IdP) such as Okta, Azure AD, Ping, ADFS, and others.

SAML implementations vary across IdPs, and some setups are highly customized. This guide covers the frequently seen issues. If your issue isn’t listed here, please capture a SAML trace and contact your IdP admin or Tellius Support. In the trace, confirm:

• whether the SAML Response or SAML Assertion is signed

• whether the assertion is encrypted

• the NameID / identifier value being sent

• the Issuer, Audience, and ACS URL values

Tellius v6.1 includes an enhanced SAML flow that has been validated across a broader set of real-world IdP configurations. It is designed to reduce configuration-related login failures by being more tolerant of common IdP variations (while still enforcing core security requirements).

v6.1 improvements include:

• Broader validation across different IdP behaviors and signing patterns

• More flexible handling of user identifier formats (based on your configuration)

• Better resilience to customer-specific IdP configuration differences

• A safety fallback toggle to revert to the legacy SAML flow if needed during troubleshooting

Quick Glossary

• IdP (Identity Provider): Okta / Azure AD / Ping / ADFS. Authenticates the user.

• SP (Service Provider): Tellius. Receives the SAML message and logs the user in.

• SAML Response: The overall message the IdP sends to Tellius.

• SAML Assertion: The part inside the response that contains the user identity and attributes.

• ACS URL (SSO URL): Where the IdP posts the SAML response in Tellius.

• Entity ID / Audience URI: Identifier Tellius and the IdP must match.

• NameID / Identifier: The user identity value used to match/create the user in Tellius (often email).

What Tellius expects from your IdP

1. During SAML login, Tellius uses the user’s email address as the username (unique identifier).

2. For security, Tellius requires a signed SAML payload. Your IdP must sign at least one of the SAML Response or the SAML Assertion (or both). The following are the supported signing combinations:

• Response signed, Assertion unsigned

• Response unsigned, Assertion signed

• Both signed

1. Tellius expects unencrypted SAML assertions.

Your SAML message remains protected in transit through HTTPS/TLS, and SAML signing provides integrity. If your IdP encrypts assertions, disable assertion encryption for the Tellius application.

1. Your IdP must send the user identifier in a format that matches what Tellius expects (email/username/custom attribute depending on your setup). At minimum, ensure:

• The identifier is present

• The value is stable (does not change unexpectedly)

• The value format matches your intended Tellius username format

Quick pre-flight checklist

Confirm the following before deeper debugging:

1. Your IdP is configured with the correct ACS URL (Single Sign-On URL) from Tellius.

2. The Entity ID / Audience URI matches exactly.

3. Signing is enabled for Response or Assertion.

4. Assertion encryption is disabled (unencrypted).

5. The identifier field you send (email/username) matches what Tellius expects.

6. The user/user group is assigned access to the Tellius app in the IdP.

7. In Okta Advanced Settings, these are safe defaults that work for most SAML setups:

   • Response: Signed ✅

   • Assertion Signature: Signed ✅

   • Signature Algorithm: RSA-SHA256 ✅

   • Digest Algorithm: SHA256 ✅

   • Assertion Encryption: Unencrypted ✅

Common Errors, Causes, and Fixes

Error 1: “Username already exists” (HTTP 422)

If you see a message similar to: “Error occurred while trying to update user info, Username already exists… (status 422)”, then the email already exists as a username for another Tellius user.

How to fix

1. Under Settings → Users, search for the email/username.

2. If the user already exists:

   • Use the existing account (recommended)

   • Avoid creating a second account with the same email

3. If this was caused by an incorrect identifier mapping, make sure the correct email is being sent (NameID/identifier) in your IdP.

4. If your organization truly needs separate users, then they must have unique email identities (or a unique identifier setup aligned with Tellius)

Error 2: SAML payload not signed (Response and Assertion unsigned)

If the login fails with an error indicating missing signature / unsigned SAML, then your IdP is sending both an unsigned Response and an unsigned Assertion. Tellius requires at least one signature for security.

How to fix: In your IdP, enable signing for Response or Assertion. The recommended baseline (especially for Okta) is to sign both.

Error 3: Signature validation failed (invalid signature)

If the login fails even though signing is enabled, then the following are the most common causes:

• IdP signing certificate changed (rotation) and Tellius is still using old metadata/cert

• Wrong certificate uploaded/selected in IdP or Tellius

• Algorithm mismatch (less common)

How to fix

1. Re-export fresh metadata from the IdP and update Tellius SAML configuration.

2. Confirm your signing algorithm is modern (example: RSA-SHA256).

3. If cert rotation happened recently, confirm the correct active signing cert is in use.

Error 4: Encrypted assertion (assertion encryption enabled)

If the login fails and your IdP is configured to encrypt assertions, then Tellius cannot read the user attributes.

How to fix: In your IdP, set Assertion Encryption = Unencrypted. Disable “Encrypt assertion” on Tellius.

Error 5: Identifier missing or not matching (NameID / email mapping issue)

This happens when user authenticates at IdP but Tellius cannot log them in or provision them. It's because Tellius did not receive the expected identifier value, or it came in an unexpected format.

How to fix

1. In the IdP, confirm the identifier you send:

   • NameID value (commonly email), or

   • An attribute claim (like email, upn, username)

2. Ensure it is:

   • Present and non-empty

   • Stable and unique

   • In the format Tellius expects

Error 6: Audience / Entity ID mismatch

Tellius rejects the response due to the assertion's audience-Tellius Entity ID mismatch or the issuer value mismatch.

How to fix

In the IdP app configuration:

• Ensure Audience URI / Entity ID exactly matches Tellius

• Confirm you’re using the correct environment URL (prod vs staging)

• Avoid trailing slashes or whitespace differences

Error 7: ACS URL mismatch (SSO URL wrong)

Authentication happens at IdP but Tellius rejects the POST or you land on an error page. The IdP is posting the SAML response to the wrong ACS URL.

How to fix

• Copy the ACS URL directly from Tellius SAML settings and paste into IdP.

• Confirm the correct Tellius environment (prod vs staging) is configured.

Error 8: User not assigned / blocked by IdP policy

User cannot launch Tellius from IdP dashboard, or login is denied by IdP. This could mean that the user is not assigned to Tellius or blocked by sign-on rules (MFA, device trust, network zones).

How to fix

• Assign the user or their group to Tellius in IdP.

• Review IdP sign-on policies and Tellius access rules.

Additional issues (if your error is not listed above)

These issues can happen in some environments and are not always obvious:

• Clock skew between IdP and Tellius can cause “assertion not yet valid / expired” errors

• Certificate rotation / expired signing certificate

• Incorrect binding (POST vs Redirect)

• Wrong environment URLs (prod vs staging)

• RelayState handling differences

• User not assigned to the app in IdP or blocked by IdP policies (MFA, network zones, device trust)