Troubleshooting Single Sign-On (SSO) in Streamline

Setting up Single Sign-On (SSO) can look different for every organization.

Because each identity provider (IdP) and configuration varies, you might encounter unique issues during setup or login.

This guide helps you diagnose and resolve common SSO problems in Streamline, from quick checks to advanced debugging.

Common Causes of SSO Issues

Most SSO setup or login errors are caused by one of the following:

• Outdated or mismatched metadata between Streamline and your IdP
• Incorrect URLs (for example, using the Entity ID instead of the ACS URL)
• Missing or mismatched user attributes in your IdP mapping
• Domain verification not completed or expired
• Incorrect encryption or binding method (for example, using HTTP-Redirect instead of HTTP-POST)
• SAML assertion or audience mismatch

Tip: First determine whether the issue affects all users or just a few. If only certain users are impacted, the problem is likely related to user group assignments or missing attributes in your IdP.

Quick Troubleshooting Checklist

Start with these quick steps before diving into error-specific fixes.

1. Check for recent changes
   • Confirm with your IT team whether your IdP metadata, certificate, or login URLs have changed recently.
   • If they have, reimport the updated metadata into Streamline.
2. Run the Testing flow in the SSO Setup Suite
3. Verify your connection details
   • In Streamline, go to Settings → Security → Single Sign-On (SSO).
   • Make sure your ACS URL and Entity ID match what’s in your IdP configuration.
4. Review group assignments
   • Verify that affected users are assigned to the Streamline app in your IdP and belong to valid mapped groups.
5. Validate user attributes
   • Ensure your IdP sends required attributes such as email, displayName, given_name, and family_name.
6. Confirm binding method
   • Streamline supports HTTP-POST bindings for SAML responses.
   • If your IdP is configured for HTTP-Redirect, update it to use POST instead.
7. Test with a clean user
   • Create a new test user in your IdP and assign them to Streamline.
   • This helps confirm whether the issue is configuration-wide or user-specific.

Using SAML Tracer

If your organization uses SAML 2.0, the SAML Tracer browser extension can help identify where issues occur between Streamline and your IdP.

What SAML Tracer does:

• Captures the SAML request and response exchanged between your browser, IdP, and Streamline
• Highlights invalid assertions, missing attributes, or binding mismatches

How to use SAML Tracer:

1. Install SAML Tracer for Chrome or Firefox.
2. Open the extension and start recording.
3. Attempt to log in to Streamline via your IdP.
4. Stop recording once the error occurs.
5. Review the captured data for errors or warnings.

Most issues identified using SAML Tracer, such as missing attributes or invalid audience URLs, can be resolved by updating your IdP configuration.

Tip: Save your trace file before reaching out to support. It helps the team diagnose issues faster.

Common Errors and Recommended Fixes

404 – Not Found

Cause: The ACS URL in your IdP configuration doesn’t match Streamline’s metadata, or SSO is turned off.

Fix:

• Enable SSO in Settings → Security → Single Sign-On (SSO).
• Verify that the ACS URL in your IdP exactly matches the one provided in Streamline.

405 – Method Not Allowed

Cause: The IdP uses the Entity ID instead of the ACS URL.

Fix:

• Open your IdP’s Streamline app settings.
• Replace any URL ending with /samlEntityId with the ACS URL ending in /process.

Application Identifier Not Found

Cause: The application identifier doesn’t match Streamline’s metadata or the metadata is outdated.

Fix:

• Reimport Streamline’s Service Provider metadata into your IdP.
• Save and retest your connection.

Invalid Audience or Invalid Response

Cause: The SAML assertion is pointing to the wrong endpoint (for example, a forms-based SSO URL).

Fix:

• Recreate your SSO application in your IdP using the latest Streamline metadata.
• Verify that the ACS and Entity ID URLs match those in Streamline.

InvalidNameIDPolicy

Cause: The NameID format or attribute mapping doesn’t match what Streamline expects.

Fix:

• Set the NameID field in your IdP to use Email Address.
• Confirm that an email attribute is included in the SAML response.

Unable to Encrypt Assertion

Cause: The IdP is set to always encrypt SAML assertions, which Streamline doesn’t require.

Fix:

• In your IdP, set Encrypt SAML2 Assertion to Never.

SAML Response Not Found (Only HTTP_POST Supported)

Cause: The IdP is sending the response using HTTP-Redirect instead of HTTP-POST.

Fix:

• Update your IdP’s binding configuration to HTTP-POST.
• Re-run a test connection in Streamline.

Username Already Exists for This Authentication Provider

Cause: The user’s Streamline account already exists under a different authentication method.

Fix:

• Have the user log in with their existing method (for example, email and password).
• If their username changed, update the attribute in your IdP to match the Streamline account.

Failure Decrypting Data

Cause: The x509 certificate used by your IdP is invalid or expired.

Fix:

• Update your IdP certificate.
• Reimport the metadata file into Streamline and test again.

Reference Validation Failed

Cause: Streamline received a response from an unexpected host or domain.

Fix:

• Confirm that your IdP is configured to send responses only to your Streamline ACS URL.
• Check that your IdP’s metadata domain matches your verified Streamline domain.

Generic Invalid Response or Requester Error

Cause: The SAML response is malformed or being redirected through an unsupported page.

Fix:

• Make sure your IdP sends a valid SAML XML response directly to Streamline’s ACS URL.
• Avoid routing authentication through custom web pages that modify or filter XML data.

Advanced Troubleshooting for IT Administrators

If your team manages SSO at a deeper technical level, these steps can help with advanced diagnosis.

1. Check Streamline Logs (Admins only)
   • Streamline logs SSO events under your admin account’s audit history.
   • Look for failed authentication attempts or metadata import warnings.
2. Validate Token Claims (OIDC setups)
   • Use a JWT decoder to inspect ID tokens for OIDC-based SSO.
   • Confirm that the audience and issuer match Streamline’s configuration.
3. Inspect Certificate Expiration Dates
   • Verify that your IdP certificate hasn’t expired and matches the certificate shown in Streamline’s metadata.
4. Run Metadata Comparison
   • Export both the IdP and Streamline metadata files and compare them.
   • Look for differences in ACS URLs, entity IDs, or binding methods.
5. Recreate the App Integration (Last Resort)
   • If the issue persists after all checks, create a new SSO application in your IdP using Streamline’s latest metadata.
   • Retest the connection to confirm success.

Tip: Advanced troubleshooting should be handled by your IT or IdP administrator with admin access to both systems.

When to Contact Support

If issues persist after reviewing these steps, our support team can help investigate further.

Before contacting us, please gather the following information.

• Your Organization ID
• The name of your Identity Provider (for example, Okta, Microsoft Entra ID, OneLogin, ADFS)
• The type of provider (SAML or OpenID Connect)
• A copy of your SAML Trace file (if applicable)
• A screenshot of the error message or code

Providing this information helps the team resolve your issue faster.

Closing Notes

Most SSO issues can be resolved by verifying metadata, checking URLs, or reviewing your attribute and group mappings.

After making changes, run another test under Settings → Security → Single Sign-On (SSO) to confirm the fix.

Next Step: Review the Setting up Single Sign-On (SSO) in Streamline guide to ensure your setup follows the latest Streamline best practices.