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