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

# SSO configuration

> Set up SAML 2.0 or OIDC single sign-on for your organisation.

## Overview

ORCA supports SSO via SAML 2.0 and OpenID Connect (OIDC). Once configured, your team members can sign in using your identity provider (Okta, Azure AD, Google Workspace, etc.) without separate passwords.

## Prerequisites

* Admin role in your ORCA organisation
* Access to your identity provider's admin console
* Your organisation's email domain (e.g., `company.com`)

## SAML 2.0 setup

<Steps>
  <Step title="Get ORCA's SP metadata">
    Go to **Security** in the ORCA sidebar. In the SSO Configuration section, select **SAML** as the provider and copy the **SP Metadata URL** or download the XML file.

    The metadata includes:

    * **Entity ID**: `https://app.orca.klavest.com/api/v1/sso/saml/metadata`
    * **ACS URL**: `https://app.orca.klavest.com/api/v1/sso/saml/acs`
  </Step>

  <Step title="Configure your IdP">
    In your IdP (Okta, Azure AD, etc.):

    1. Create a new SAML application
    2. Import ORCA's SP metadata, or manually enter the ACS URL and Entity ID
    3. Set **Name ID Format** to `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
    4. Map the following attributes:
       * `email` (required)
       * `firstName` (optional)
       * `lastName` (optional)
    5. Download your IdP's metadata XML or note the SSO URL and certificate
  </Step>

  <Step title="Configure ORCA">
    Back in ORCA's Security page:

    1. Enter a **Display Name** (e.g., "Okta SSO" — shown on the login button)
    2. Enter your **Email Domain** (e.g., `company.com`)
    3. Paste your IdP's **SSO URL** (the endpoint where ORCA sends SAML requests)
    4. Upload or paste your IdP's **X.509 Certificate** (.pem or .crt format)
    5. Click **Save Configuration** and toggle **Enable SSO** to on
  </Step>

  <Step title="Test">
    1. Open a private/incognito window
    2. Go to the ORCA login page
    3. Enter an email address with your configured domain
    4. You should see a "Sign in with \[Display Name]" button — click it to test the SSO flow
  </Step>
</Steps>

## OIDC setup

<Steps>
  <Step title="Register ORCA in your IdP">
    1. Create a new OIDC application in your IdP
    2. Set the **Redirect URI** to: `https://app.orca.klavest.com/sso/callback`
    3. Note the **Client ID** and **Client Secret**
    4. Note the **Discovery URL** (e.g., `https://your-idp.com/.well-known/openid-configuration`)
  </Step>

  <Step title="Configure ORCA">
    1. In ORCA's Security page, select **OIDC** as the provider
    2. Enter the **Client ID**, **Client Secret**, and **Discovery URL**
    3. Enter your **Email Domain** and **Display Name**
    4. Save and enable
  </Step>
</Steps>

## SSO enforcement

Once SSO is working, you can enforce it:

1. Toggle **Enforce SSO** in the SSO configuration
2. When enforced, password-based login is disabled for users with your email domain
3. Users only see the SSO button on the login page
4. Existing sessions remain active, but new logins must use SSO

<Warning>
  Before enforcing SSO, ensure at least one admin can log in via SSO. If SSO is misconfigured and enforced, admin users may be locked out.
</Warning>

## JIT provisioning

ORCA supports Just-In-Time (JIT) user provisioning:

* When a user logs in via SSO for the first time, their account is automatically created
* They are added to your organisation with a default role
* No manual user creation or invitation required
* Email, first name, and last name are synced from the IdP's SAML assertion or OIDC claims

## Troubleshooting

| Issue                                   | Solution                                                  |
| --------------------------------------- | --------------------------------------------------------- |
| "No SSO configuration found"            | Verify the email domain matches your SSO config           |
| SAML signature validation fails         | Re-download and upload the IdP certificate                |
| Redirect loop                           | Check that the ACS URL in your IdP matches ORCA's exactly |
| User created in wrong org               | Verify the email domain is only configured for one org    |
| "SSO enforced" but need password access | An admin must disable enforcement in Security settings    |