> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose and fix SSO authentication failures in Ravenna covering attribute mappings, certificate expiry, IdP errors, and intermittent login issues.

## 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

### Users cannot sign in after SSO enforcement

**Symptoms**: Users cannot sign in after disabling other login methods, or users with non-SSO domains are blocked.

**Solutions**:

* Verify SSO is properly enabled and working before disabling other methods
* Ensure the user's email domain is configured for SSO
* Check that users exist in your identity provider
* If you need to restore other login methods, detach and re-attach your SSO connection
* Verify backup admin accounts use email domains not configured for SSO

### New users not redirected to SSO

**Symptoms**: New users with matching domains receive email invitations instead of SSO redirect.

**Solutions**:

* Verify the user's email domain is configured in SSO settings
* Check that domain realm discovery is enabled for the domain
* Ensure the domain verification is complete for additional domains
* Clear browser cache and try again

## 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

<AccordionGroup>
  <Accordion title="Certificate Problems">
    **Common causes:**

    * Expired or invalid certificates
    * Incorrect certificate format
    * Missing certificate chain

    **Solutions:**

    * Verify certificate validity and expiration dates
    * Ensure proper certificate formatting (PEM format)
    * Check that the full certificate chain is included
  </Accordion>

  <Accordion title="Configuration Mismatches">
    **Common causes:**

    * Incorrect callback URLs
    * Mismatched entity IDs
    * Wrong attribute mappings

    **Solutions:**

    * Double-check all configuration values
    * Verify URLs are accessible and correct
    * Ensure attribute names match exactly
  </Accordion>

  <Accordion title="Network Connectivity">
    **Common causes:**

    * Firewall blocking requests
    * DNS resolution issues
    * Network timeouts

    **Solutions:**

    * Verify network connectivity between systems
    * Check firewall rules and whitelist necessary IPs
    * Test DNS resolution for all involved domains
  </Accordion>
</AccordionGroup>

## 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:

<Warning>
  **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.
</Warning>

#### 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 **[Support](mailto:support@ravenna.ai)** 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