Setup Guide
This comprehensive guide walks you through setting up Single Sign-On (SSO) for your Ravenna organization using your identity provider’s guided wizard.
Prerequisites: Ensure you have administrator access to both your identity provider and Ravenna organization before proceeding.
Step 1: Access SSO Configuration
Navigate to your Ravenna organization settings to begin the SSO setup process.
Open Workspace Settings
From your Ravenna dashboard, click on your workspace name in the top navigation and select Settings.
Navigate to Organization Integrations
In the left sidebar, click on Integrations under the Organization section.
Step 2: Start SSO Setup Wizard
Begin the SSO configuration process using Ravenna’s guided setup wizard.
Access SSO Setup
In the Organization Integrations section, find Single Sign-On and click Setup or Add SSO Provider.
Start Setup Wizard
The SSO setup wizard will open, providing a guided configuration experience for your identity provider.
Choose Identity Provider
Select your identity provider from the available options. Ravenna supports popular providers like Azure AD, Google Workspace, Okta, and custom SAML/OIDC providers.
Step 3: Configure Your Identity Provider
Use the guided configuration to set up your identity provider connection.
Follow Configuration Guide
Ravenna provides step-by-step instructions specific to your chosen identity provider. Follow the guide to configure your IdP with the required settings.
Configure Connection Details
Return to Ravenna and enter the required information from your identity provider setup:
These settings differ based on your IdP, but typically include:
- Entity ID: Your organization’s unique identifier in the IdP.
- Client ID: The application ID registered in your IdP.
- Client Secret: The secret key used to authenticate with the IdP.
This page also provides the callback URL that you need to configure in your IdP settings.
Create Connection
After entering your IdP details, save the configuration to create the SSO connection. This creates the connection but doesn’t yet link it to your organization.
Step 4: Configure Domain Settings
Set up domain-based authentication and user access control.
Review Default Managed Domain
Ravenna automatically includes your organization’s email domain as a managed domain for SSO. This is the domain associated with your Ravenna organization and requires no additional verification.
Add Additional Domains (Optional)
If you need to add additional email domains for SSO authentication, click Add Domain. Additional domains require domain ownership verification.
Verify Domain Ownership
For additional domains, you’ll need to verify ownership by adding a TXT record to your domain’s DNS settings. The SSO wizard will provide you with the specific TXT record value to add.
Domain Verification: This step ensures you have administrative control over the email domain before allowing SSO authentication for users from that domain.
Domain Realm Discovery (Enforced by Default)
Ravenna automatically enforces domain realm discovery for all managed domains. This means users with email addresses from your managed domains will be automatically redirected to your SSO provider and cannot use username/password authentication.
Important: Once SSO is enabled, users with email addresses from your managed domains will no longer be able to log in using username and password. They must use SSO authentication. Ensure you maintain at least one admin account with an email from a non-managed domain or a different authentication method as a backup.
Step 5: Test SSO Configuration
Verify that your SSO configuration is working correctly before enabling it for all users.
Run SSO Test
Use the built-in test functionality to verify your SSO configuration. This will attempt a test authentication flow.
Review Test Results
Check the test results to ensure authentication is working properly. The test will show you any issues that need to be resolved.
Step 6: Complete Setup
Finalize your SSO configuration and enable it for your organization.
Complete SSO Wizard
After testing is successful, complete the SSO setup wizard by clicking the Complete Setup button.
Verify Connection
Once completed, you’ll see your SSO identity provider successfully connected in the Organization Integrations section.
Managing Your SSO Configuration
After setup, you can manage and edit your SSO configuration as needed.
Edit SSO Settings
You can modify your SSO configuration at any time by returning to the Organization Integrations section.
Use Setup Wizard for Changes
When editing, you can use the setup wizard again to make changes to your configuration.
Notify Users
Inform your team members about the SSO activation and provide them with login instructions.
User Login Process
Once SSO is enabled, users from configured domains will see the SSO login option:
- Users visit the Ravenna login page
- Enter their email address
- Click Continue with SSO
- Get redirected to your organization’s login page
- Complete authentication with corporate credentials
- Automatically logged into Ravenna
Troubleshooting
Common Issues
Getting Help
If you continue to experience issues:
- Check the SSO logs in your Ravenna organization settings
- Review your IdP logs for any error messages
- Contact support with specific error messages and configuration details
Important: Keep your existing admin account accessible through password authentication as a backup while setting up and testing SSO.
Next Steps
After successfully setting up SSO, consider:
- Managing SSO users and permissions
- Setting up automatic user provisioning (if supported by your IdP)
- Configuring additional security policies in your organization