SSO Troubleshooting Guide

Common Issues and Solutions

OIDC Issues

"Invalid redirect URI"

Symptoms:

• Error message: "Invalid redirect URI" or "redirect_uri_mismatch"
• User cannot complete SSO login

Solutions:

1. Verify the redirect URI in your OIDC provider matches exactly:

   https://your-domain.com/auth/callback/oidc?provider_id={provider_id}&tenant_id={tenant_id}

2. Ensure provider_id and tenant_id parameters are included
3. Check for trailing slashes or URL encoding issues
4. Verify the domain matches your Lager Guru deployment

"User email not found"

Symptoms:

• Error: "User email not provided by OIDC provider"
• SSO login fails after authentication

Solutions:

1. Ensure your OIDC provider returns the email claim in the ID token
2. Verify the email scope is included in your SSO provider configuration
3. Check your OIDC provider's user attribute mapping
4. For Azure AD, ensure "email" is included in token claims

"State parameter mismatch"

Symptoms:

• Error: "Invalid state parameter - possible CSRF attack"
• SSO login fails on callback

Solutions:

1. This usually indicates a session timeout or browser issue
2. Clear browser cookies and try again
3. Ensure cookies are enabled in the browser
4. Check if the session storage is being cleared prematurely

"Failed to create OIDC client"

Symptoms:

• Error during SSO initiation
• Cannot connect to OIDC provider

Solutions:

1. Verify the issuer URL is correct and accessible
2. Check the metadata URL is valid and returns proper JSON
3. Ensure network connectivity to the OIDC provider
4. Verify SSL certificates are valid

SAML Issues

"SAML response validation failed"

Symptoms:

• Error: "SAML callback handling failed"
• SSO login fails after authentication

Solutions:

1. Verify your SAML provider's certificate is valid and not expired
2. Check that the metadata URL is accessible and up-to-date
3. Ensure the entity ID matches exactly between provider and Lager Guru
4. Verify SAML response signatures are valid
5. Check SAML provider logs for detailed error messages

"User email not found in SAML response"

Symptoms:

• Error: "User email not found in SAML response"
• SSO login fails

Solutions:

1. Verify your SAML provider returns the email attribute
2. Check attribute name mapping (see SAML.md for supported attributes)
3. Ensure Name ID format includes email address
4. For Azure AD SAML, configure "email" in token claims
5. Check SAML assertion in browser developer tools (if accessible)

"SAML request ID mismatch"

Symptoms:

• Error: "SAML request ID mismatch - possible replay attack"
• SSO login fails on callback

Solutions:

1. This usually indicates a session timeout
2. User should retry the SSO login
3. Ensure session storage is not being cleared
4. Check browser privacy settings

"Failed to fetch SAML metadata"

Symptoms:

• Error during SSO provider configuration
• Cannot load SAML metadata

Solutions:

1. Verify the metadata URL is accessible from your network
2. Check for CORS issues if accessing from browser
3. Ensure the metadata URL returns valid XML
4. Try downloading metadata XML and hosting it yourself

General Issues

"SSO provider not found or inactive"

Symptoms:

• Error: "SSO provider not found or inactive"
• SSO login button not working

Solutions:

1. Verify the SSO provider is marked as "Active" in System Settings
2. Check that the provider belongs to the correct tenant
3. Ensure the provider ID matches
4. Verify tenant admin permissions

"Tenant ID mismatch"

Symptoms:

• Error: "Tenant ID mismatch"
• SSO login fails

Solutions:

1. This is a security feature - users can only access their assigned tenant
2. Verify the user belongs to the tenant that initiated SSO
3. Check tenant assignment in System Settings
4. Contact administrator to verify tenant configuration

"User provisioning failed"

Symptoms:

• Error: "Failed to map SSO user to tenant"
• SSO login fails after authentication

Solutions:

1. Verify the user's email is valid and unique
2. Check that the tenant exists and is active
3. Ensure proper permissions for user creation
4. Check database constraints and RLS policies
5. Review application logs for detailed error messages

SSO Button Not Showing

Symptoms:

• "Mit Unternehmens-SSO anmelden" button not visible on login page

Solutions:

1. Verify at least one SSO provider is configured and active
2. Check tenant detection (subdomain routing)
3. Ensure proper tenant context
4. Verify user has access to SSO-enabled tenant

Debugging Steps

1. Check SSO Provider Configuration

1. Go to System Settings → SSO Integration
2. Verify provider is active
3. Check all required fields are filled
4. Test metadata URL accessibility

2. Verify Network Connectivity

1. Test access to OIDC metadata URL or SAML metadata URL
2. Check firewall rules
3. Verify DNS resolution

3. Review Browser Console

1. Open browser developer tools (F12)
2. Check Console tab for errors
3. Check Network tab for failed requests
4. Review session storage for SSO state

4. Check Application Logs

1. Review server-side logs for detailed error messages
2. Check Supabase logs for database errors
3. Review authentication flow logs

5. Test with Different Browser

1. Try SSO login in incognito/private mode
2. Test with different browser
3. Clear cookies and cache

Getting Help

If you continue to experience issues:

1. Collect Information:

   • Error messages (exact text)
   • Browser console logs
   • Network request details
   • SSO provider configuration (without secrets)

2. Contact Support:

   • System administrator
   • Lager Guru support team
   • Your SSO provider's support

3. Provide Details:

   • Steps to reproduce
   • Expected vs. actual behavior
   • Screenshots if applicable
   • Relevant log entries

Best Practices

1. Test in Staging First:

   • Always test SSO configuration in a staging environment
   • Verify user provisioning works correctly
   • Test with multiple users

2. Monitor Logs:

   • Regularly review authentication logs
   • Set up alerts for SSO failures
   • Monitor user provisioning

3. Keep Metadata Updated:

   • Regularly refresh SAML metadata
   • Update OIDC endpoints if provider changes
   • Rotate client secrets periodically

4. Document Configuration:

   • Keep a record of SSO provider settings
   • Document any custom attribute mappings
   • Maintain a change log

Security Considerations

• Never share client secrets or private keys
• Use HTTPS for all SSO endpoints
• Regularly rotate credentials
• Monitor for suspicious authentication attempts
• Implement proper session management
• Use strong encryption for stored secrets