SSO
      Back to home
      1. Fluint Help Center
      2. Admin Setup for Team Licenses
      3. SSO

      Troubleshooting SSO Issues

      This guide helps you diagnose and resolve common SSO configuration problems.

      Before You Start

      Gather this information:

      • Identity provider type (Okta, Azure AD, Google, etc.)
      • Protocol used (SAML or OIDC)
      • Exact error messages
      • Screenshots of configuration screens
      • Browser console errors (if any)

      SAML Troubleshooting

      "Invalid SAML Response" Error

      Possible causes and solutions:

      ❌ Incorrect Callback URL

      • Check: Ensure your IdP's ACS URL exactly matches https://app.fluint.io/auth/sso-callback
      • Fix: Update the URL in your identity provider (no trailing slashes, exact case)

      ❌ Wrong NameID Format

      • Check: Verify NameID format is set to Email Address
      • Fix: Change NameID format to EmailAddress or urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

      ❌ Certificate Issues

      • Check: Verify the X.509 certificate is correctly copied
      • Fix: Copy the entire certificate including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- headers
      • Fix: Remove any extra spaces or line breaks

      ❌ Clock Skew Issues

      • Check: Ensure system clocks are synchronized between IdP and SP
      • Fix: Synchronize time on both systems (typically NTP)

      "Attribute Mapping Errors"

      ❌ Missing Email Attribute

      • Check: Verify email attribute is configured in your IdP
      • Fix: Add email attribute mapping in your identity provider
      • Fix: Ensure the attribute value contains the user's email address

      ❌ Incorrect Attribute Names

      • Check: Attribute names are case-sensitive
      • Fix: Use exact attribute names: email, first_name, last_name

      "SAML Assertion Not Valid"

      ❌ Audience Mismatch

      • Check: Audience restriction in SAML assertion
      • Fix: Set audience to https://app.fluint.io

      ❌ Invalid Signature

      • Check: SAML response signature verification
      • Fix: Ensure the signing certificate matches what's configured in Fluint
      • Fix: Verify certificate hasn't expired

      OIDC Troubleshooting

      "Invalid Redirect URI" Error

      ❌ URL Mismatch

      • Check: Redirect URI in your IdP configuration
      • Fix: Set exact URL: https://app.fluint.io/auth/sso-callback
      • Fix: Check for typos, extra characters, or wrong protocol (http vs https)

      ❌ Multiple URIs Configured

      • Check: Some providers require exact URI matching
      • Fix: Remove any extra redirect URIs, keep only the Fluint callback URL

      "Invalid Client Credentials"

      ❌ Wrong Client ID/Secret

      • Check: Client ID and Secret are correctly copied
      • Fix: Regenerate client secret and update in Fluint
      • Fix: Verify no extra spaces when copying credentials

      ❌ Expired Client Secret

      • Check: Client secret expiration date
      • Fix: Generate new client secret and update configuration

      "Insufficient Scope" Error

      ❌ Missing Required Scopes

      • Check: Scopes configured in your IdP
      • Fix: Ensure these scopes are granted: openid, profile, email

      General SSO Issues

      Users Can't Find SSO Option

      ❌ Connection Not Enabled

      • Check: SSO connection status in Fluint admin
      • Fix: Enable the SSO connection for your organization

      ❌ Email Domain Not Configured

      • Check: User's email domain matches your organization
      • Fix: Verify the user's email domain is associated with your SSO configuration

      ❌ User Not Assigned

      • Check: User assignment in your identity provider
      • Fix: Assign the user or their group to the Fluint application

      "Access Denied" Errors

      ❌ User Not Provisioned

      • Check: User exists in your identity provider
      • Fix: Ensure user account is active and assigned to Fluint app

      ❌ Conditional Access Policies (Azure AD)

      • Check: Conditional access blocking the request
      • Fix: Review and adjust conditional access policies
      • Fix: Temporarily disable CA policies for testing

      ❌ Application Not Approved (Google)

      • Check: App approval status in Google Workspace
      • Fix: Ensure app is enabled for the user's organizational unit

      Session Issues

      ❌ Frequent Re-authentication

      • Check: Session timeout settings
      • Fix: Adjust session timeout in your identity provider
      • Fix: Check if logout URL is correctly configured

      ❌ Users Logged Out Unexpectedly

      • Check: Single logout configuration
      • Fix: Verify logout URLs are correctly set
      • Fix: Check for conflicting session management

      Debugging Steps

      Step 1: Check Browser Console

      1. Open browser developer tools (F12)
      2. Go to Console tab
      3. Clear console and attempt SSO login
      4. Look for JavaScript errors or network failures

      Step 2: Check Network Traffic

      1. In browser dev tools, go to Network tab
      2. Clear network log and attempt SSO login
      3. Look for failed requests (red status codes)
      4. Check request/response headers for errors

      Step 3: Verify Configuration

      SAML Checklist:

      • Callback URL: https://app.fluint.io/auth/sso-callback
      • Entity ID: https://app.fluint.io
      • NameID format: Email Address
      • Email attribute configured
      • Certificate properly formatted
      • User assigned to application

      OIDC Checklist:

      • Redirect URI: https://app.fluint.io/auth/sso-callback
      • Scopes: openid profile email
      • Response type: code
      • Client ID/Secret correct
      • Endpoints URLs correct
      • User assigned to application

      Step 4: Test with Different Users

      1. Test with multiple user accounts
      2. Try users from different groups/organizational units
      3. Test with admin and non-admin users
      4. Use incognito/private browsing mode

      Provider-Specific Issues

      Okta Issues

      "Invalid SAML Response" with Okta

      • Check application assignment
      • Verify attribute statements are configured
      • Ensure NameID is set to Email

      OIDC scope issues

      • Verify default scopes include openid, profile, email
      • Check if custom authorization server is required

      Azure AD Issues

      Conditional Access blocking

      • Review conditional access policies
      • Check device compliance requirements
      • Verify location-based restrictions

      Wrong tenant configuration

      • Ensure app is registered in correct tenant
      • Verify tenant ID in OIDC endpoints

      Google Workspace Issues

      Organizational Unit problems

      • Check if app is enabled for user's OU
      • Verify inheritance settings for OUs
      • Test with users in different organizational units

      Domain verification

      • Ensure domain is verified in Google Workspace
      • Check if users are using correct domain

      Advanced Debugging

      Enable Detailed Logging

      For SAML:

      • Enable SAML tracer browser extension
      • Check IdP audit logs
      • Review SAML assertion details

      For OIDC:

      • Use JWT.io to decode tokens
      • Check OAuth flow in network tab
      • Review IdP application logs

      Test Outside Fluint

      SAML Testing:

      • Use online SAML validators
      • Test with SAML tracer tools
      • Verify assertion format

      OIDC Testing:

      • Use OAuth/OIDC testing tools
      • Test authorization code flow manually
      • Verify token contents

      Getting Help

      Information to Provide

      When contacting support, include:

      1. Identity provider type and version
      2. Protocol used (SAML/OIDC)
      3. Complete error messages
      4. Screenshots of configuration
      5. Steps to reproduce the issue
      6. Browser console errors
      7. Number of affected users

      Escalation Steps

      1. Check this troubleshooting guide
      2. Review provider-specific setup guides
      3. Test with simplified configuration
      4. Contact your identity provider support
      5. Contact Fluint support with detailed information

      Temporary Workarounds

      While troubleshooting:

      • Users can still log in with email/password
      • Create temporary local accounts if needed
      • Use different browser or incognito mode
      • Test with admin account first

      Prevention Tips

      Regular Maintenance:

      • Monitor certificate expiration dates
      • Review user assignments quarterly
      • Test SSO flow after any IdP changes
      • Keep backup of working configuration
      • Document any custom settings

      Security Best Practices:

      • Rotate certificates and secrets regularly
      • Monitor failed authentication attempts
      • Review and update user assignments
      • Audit SSO usage logs
      • Keep IdP software updated