​
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:
  1. Check browser developer tools: Look for network errors during the SSO redirect process
  2. Review IdP logs: Check your identity provider’s logs for specific error messages
  3. Verify callback URLs: Ensure your IdP is configured with the correct Ravenna callback URLs
  4. 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:
  1. Verify domain configuration: Check that the domain is properly configured in your SSO settings
  2. Check domain verification: Ensure domain ownership verification is complete
  3. 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:

  1. Use backup admin account: Log in with your non-SSO admin account
  2. Assess the situation: Determine if the issue is with your IdP or the SSO configuration
  3. Temporary workaround: If needed, temporarily disable SSO to allow password authentication
  4. 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

  1. Check the troubleshooting guide above for common solutions
  2. Review authentication logs in your identity provider for specific error messages
  3. Gather information: Collect relevant error messages, timestamps, and user details
  4. 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