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

# Setup

> Step-by-step setup guide for configuring SAML or OIDC single sign-on with Ravenna's guided wizard, including domain verification and IdP setup.

<Info>Connect your identity provider using guided SSO wizard</Info>

This guide walks you through setting up Single Sign-On (SSO) for your organization using your identity provider's guided wizard.

## Prerequisites

Before you begin, ensure you have:

* Administrator access to your identity provider
* Organization admin privileges
* Domain verification completed for your organization
* SSL certificate configured on your IdP (recommended)

## Setup guide

### Access SSO configuration

<Steps>
  <Step title="Navigate to SSO settings">
    Go to **Settings > SSO**.
  </Step>

  <Step title="Start setup wizard">
    1. Click **Setup** or **Add SSO Provider**
    2. The SSO setup wizard will open with guided configuration
    3. Select your identity provider from available options (Azure AD, Google Workspace, Okta, custom SAML/OIDC)
  </Step>
</Steps>

### Configure identity provider

<Steps>
  <Step title="Follow configuration guide">
    Follow the step-by-step instructions specific to your chosen identity provider to configure your IdP with required settings
  </Step>

  <Step title="Configure connection details">
    Enter the required information from your identity provider setup:

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

    Note the callback URL provided for configuring in your IdP settings
  </Step>

  <Step title="Create connection">
    Save the configuration to create the SSO connection (this creates the connection but doesn't yet link it to your organization)
  </Step>
</Steps>

### Configure domain settings

<Steps>
  <Step title="Review default managed domain">
    Your organization's email domain is automatically included as a managed domain for SSO (requires no additional verification)
  </Step>

  <Step title="Add additional domains (optional)">
    1. Click **Add Domain** if you need additional email domains
    2. Additional domains require domain ownership verification
    3. Add the provided TXT record to your domain's DNS settings
  </Step>

  <Step title="Domain realm discovery">
    Domain realm discovery is automatically enforced for all managed domains

    <Warning>
      Users with email addresses from managed domains will be automatically redirected to your SSO provider and cannot use username/password authentication. Maintain at least one admin account with an email from a non-managed domain as backup.
    </Warning>
  </Step>
</Steps>

### SSO enforcement

After enabling SSO, you have control over which authentication methods your users can access.

<AccordionGroup>
  <Accordion title="Automatic SSO redirect for new users" defaultOpen>
    When a new user enters an email address with a domain matching your SSO configuration, they are automatically redirected to authenticate through your identity provider instead of receiving an email invitation.

    This ensures that all users from your managed domains authenticate through your corporate identity provider from their first login.
  </Accordion>

  <Accordion title="Disable other login methods">
    By default, users can still authenticate through email/password or Google sign-in even after SSO is enabled. Organization admins can explicitly disable these alternative authentication methods to enforce SSO-only access.

    <Steps>
      <Step title="Navigate to SSO settings">
        Go to **Settings > SSO**
      </Step>

      <Step title="Locate SSO enforcement section">
        Find the **Enforce SSO-Only Authentication** section (only visible after SSO is enabled)
      </Step>

      <Step title="Enable SSO-only enforcement">
        Toggle the switch to enable SSO-only enforcement and remove email/password and Google sign-in options
      </Step>

      <Step title="Confirm enforcement">
        After enabling, an **Enforced** badge will appear next to the section title
      </Step>
    </Steps>

    <Info>
      Users will only be able to authenticate through your identity provider after other methods are disabled. This provides complete control over authentication in your organization. Once enabled, the toggle switch is disabled and can only be re-enabled by detaching your SSO connection.
    </Info>
  </Accordion>

  <Accordion title="Restoring other login methods">
    If you need to restore email/password and Google sign-in options, you can do so by detaching your SSO connection. This automatically re-enables the default authentication methods.

    <Warning>
      Detaching SSO will remove your identity provider integration and restore standard authentication methods. Users will need to set up passwords if they haven't already.
    </Warning>
  </Accordion>
</AccordionGroup>

<Warning>
  **Backup admin access**: Maintain at least one organization admin account that uses an email domain not configured for SSO. This ensures you can access your organization if your SSO provider becomes unavailable.
</Warning>

### Test and complete setup

<Steps>
  <Step title="Test SSO configuration">
    1. Use the built-in test functionality to verify your SSO configuration
    2. Review test results to ensure authentication is working properly
    3. Resolve any issues shown in the test results
  </Step>

  <Step title="Complete setup">
    1. Click **Complete Setup** after testing is successful
    2. Verify your SSO identity provider appears as connected in Organization Integrations
    3. Inform team members about SSO activation and login instructions
  </Step>
</Steps>

### Direct SSO login URL

After SSO is enabled, your organization receives a direct SSO login URL that bypasses the email entry step:

```text theme={"system"}
https://app.ravenna.ai/login?connection=<connection-name>
```

This URL enables one-click SSO login. Users are immediately redirected to your identity provider without entering their email first.

<Info>
  The connection name is displayed in your SSO settings after setup is complete. It's typically based on your organization name (e.g., `acme-corp`).
</Info>

#### Configuring in your IdP portal

Add this direct login URL to your identity provider's app portal to give users one-click access to Ravenna:

| Identity Provider       | Configuration Location                                                       |
| ----------------------- | ---------------------------------------------------------------------------- |
| **Okta**                | Applications → Your App → General → Login URL                                |
| **Entra ID (Azure AD)** | Enterprise Applications → Your App → Properties → Home page URL              |
| **Google Workspace**    | Apps → Web and mobile apps → Your App → Service provider details → Start URL |
| **JumpCloud**           | SSO Applications → Your App → SSO Configuration → Login URL                  |

<Tip>
  Users accessing Ravenna through your IdP's app portal will be logged in directly without needing to enter their email address.
</Tip>

#### Direct login URL vs organization login URL

| URL Type                   | Format                      | Use Case                                                       |
| -------------------------- | --------------------------- | -------------------------------------------------------------- |
| **Direct SSO login URL**   | `/login?connection=<name>`  | One-click login from IdP portals, bypasses email entry         |
| **Organization login URL** | `/login?organization=<org>` | Redirects based on organization settings, may prompt for email |

Use the direct SSO login URL when you want the fastest login experience from identity provider dashboards.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication response invalid">
    **Cause**: Incorrect certificate or signature validation issues

    **Solution**:

    * Verify certificates and keys are correctly configured
    * Ensure proper formatting of authentication credentials
    * Check that the IdP is using the correct signing configuration
  </Accordion>

  <Accordion title="User attributes missing">
    **Cause**: Incorrect attribute mapping configuration

    **Solution**:

    * Verify attribute names match those sent by your IdP
    * Check authentication response in browser developer tools
    * Ensure all required attributes are being sent by the IdP
  </Accordion>

  <Accordion title="Domain not configured">
    **Cause**: User's email domain is not added to SSO configuration

    **Solution**:

    * Add the user's email domain to the configured domains list
    * Ensure domain verification is completed
  </Accordion>

  <Accordion title="Test authentication fails">
    **Cause**: Configuration mismatch or network connectivity issues

    **Solution**:

    * Double-check all configuration values in both systems
    * Verify callback URLs are accessible and correct
    * Check IdP logs for specific error messages
    * Test network connectivity between systems
  </Accordion>
</AccordionGroup>