Troubleshooting
Diagnose and resolve common SSO authentication issues and configuration problems with step-by-step solutions.
Common Issues
Users Cannot Access SSO
Symptoms: Users receive error messages when trying to authenticate via SSO.
Solutions:
- Verify the user’s email domain is configured for SSO
- Check that the user exists in your identity provider
- Ensure the IdP application is active and properly configured
- Review user attribute mappings
Intermittent Authentication Failures
Symptoms: SSO works sometimes but fails at other times.
Solutions:
- Check IdP server status and availability
- Verify network connectivity between Ravenna and your IdP
- Review certificate expiration dates
- Check for any recent changes to IdP configuration
Missing User Information
Symptoms: Users authenticate successfully but some profile information is missing.
Solutions:
- Review user attribute mapping configuration
- Verify your IdP is sending all required user attributes
- Check the authentication response in browser developer tools
- Update attribute mapping as needed
Advanced Troubleshooting
Authentication Response Debugging
When troubleshooting authentication issues:
- Check browser developer tools: Look for network errors during the SSO redirect process
- Review IdP logs: Check your identity provider’s logs for specific error messages
- Verify callback URLs: Ensure your IdP is configured with the correct Ravenna callback URLs
- Test with different users: Determine if the issue affects all users or specific accounts
Certificate and Configuration Issues
Domain Configuration Issues
Domain Not Recognized
If users from your domain cannot access SSO:
- Verify domain configuration: Check that the domain is properly configured in your SSO settings
- Check domain verification: Ensure domain ownership verification is complete
- Review realm discovery: Confirm that domain realm discovery is properly configured
Multiple Domain Issues
When managing multiple domains:
- Consistent configuration: Ensure all domains have the same IdP configuration
- Attribute mapping: Verify attribute mappings work for users from all domains
- Testing: Test authentication with users from each configured domain
Emergency Access
When SSO is Unavailable
If your SSO provider becomes unavailable:
Emergency Access: Always maintain at least one organization admin account that uses password authentication as a backup method. This account must not have the same email domain as your SSO-managed domains.
Steps to regain access:
- Use backup admin account: Log in with your non-SSO admin account
- Assess the situation: Determine if the issue is with your IdP or the SSO configuration
- Temporary workaround: If needed, temporarily disable SSO to allow password authentication
- Communicate with users: Inform affected users about the temporary access method
Backup Account Best Practices
- Secure storage: Store backup account credentials securely
- Regular testing: Periodically test backup account access
- Limited use: Only use for emergencies and testing
- Documentation: Document the emergency access procedure
Getting Help
Before Contacting Support
- Check the troubleshooting guide above for common solutions
- Review authentication logs in your identity provider for specific error messages
- Gather information: Collect relevant error messages, timestamps, and user details
- Document steps: Note what troubleshooting steps you’ve already tried
When to Contact Support
Contact Ravenna Support when:
- You’ve tried the common solutions without success
- You encounter error messages not covered in this guide
- You need assistance with domain configuration changes
- You require help with advanced attribute mapping
Information to Include
When contacting support, please provide:
- Detailed error description: What exactly is happening vs. what should happen
- Error messages: Exact error text or screenshots
- User details: Affected usernames or email addresses (without passwords)
- Timing: When the issue started and any recent changes
- Troubleshooting steps: What you’ve already tried
Useful Resources
- User Management - Managing SSO users and permissions
- Monitoring & Maintenance - Ongoing SSO management
- Setup Guide - Initial SSO configuration
- Your identity provider’s SSO documentation
- Ravenna Support - Direct support contact