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

# Configuring Single Sign-On (SSO) for Chevre Enterprise

> Configure SAML 2.0 or OIDC Single Sign-On for your Chevre Enterprise workspace using Okta, Azure AD, Google Workspace, or any compatible IdP.

Chevre supports SAML 2.0 and OIDC-based Single Sign-On (SSO) for Enterprise workspaces, allowing your team to log in using your existing identity provider. With SSO enabled, members authenticate through your corporate IdP and land directly in Chevre — no separate Chevre password required.

<Note>
  SSO is available on the **Enterprise plan only**. If your workspace is on the Free or Pro plan, upgrade first before following the steps on this page. See the [Billing & Plans guide](/configuration/billing) for upgrade instructions and a full plan comparison.
</Note>

## Supported Identity Providers

Chevre works with any standards-compliant IdP. The following providers are tested and officially supported with step-by-step instructions:

* **Okta**
* **Azure Active Directory / Microsoft Entra ID**
* **Google Workspace**
* **OneLogin**
* Any **SAML 2.0** or **OIDC**-compatible identity provider

## Before You Begin

Gather the following before starting the SSO configuration:

* **Admin access to your IdP** — you must be able to create and configure new application integrations.
* **Owner or Admin role in Chevre** — only Owners and Admins can modify SSO settings.
* **Enterprise plan active** on your Chevre workspace.

## Configuring SSO

<Tabs>
  <Tab title="Okta">
    Follow these steps to configure SAML SSO between Chevre and Okta.

    <Steps>
      <Step title="Open SSO Settings in Chevre">
        In Chevre, go to **Settings → Security → SSO**. Click **Configure SAML**. A configuration panel will open displaying your workspace's SAML service-provider details.
      </Step>

      <Step title="Copy the ACS URL and Entity ID">
        From the Chevre SSO panel, copy both values:

        * **ACS URL** (Assertion Consumer Service URL) — e.g., `https://app.chevre.io/auth/saml/your-slug/acs`
        * **Entity ID** (SP Entity ID / Audience URI) — e.g., `https://app.chevre.io/auth/saml/your-slug`

        Keep this panel open; you will return to it later.
      </Step>

      <Step title="Create a SAML App in Okta">
        Log in to your Okta admin console. Navigate to **Applications → Applications** and click **Create App Integration**. Select **SAML 2.0** and click **Next**. Give the app a name such as `Chevre` and upload a logo if desired, then click **Next**.
      </Step>

      <Step title="Paste the ACS URL and Entity ID into Okta">
        In the **SAML Settings** step:

        * Paste the **ACS URL** into the **Single sign-on URL** field.
        * Paste the **Entity ID** into the **Audience URI (SP Entity ID)** field.
        * Set **Name ID format** to `EmailAddress`.
        * Set **Application username** to `Email`.
      </Step>

      <Step title="Map User Attributes">
        Scroll down to **Attribute Statements** and add the following mappings:

        | Name (sent to Chevre) | Value (Okta user profile field) |
        | --------------------- | ------------------------------- |
        | `email`               | `user.email`                    |
        | `first_name`          | `user.firstName`                |
        | `last_name`           | `user.lastName`                 |

        Click **Next**, complete the feedback step, then click **Finish**.
      </Step>

      <Step title="Copy the IdP Metadata from Okta">
        On your new Okta app's **Sign On** tab, find the **SAML Setup Instructions** section and click **View SAML setup instructions**. Copy the **Identity Provider metadata URL**, or download the **metadata XML** if you prefer to upload a file.
      </Step>

      <Step title="Paste Metadata into Chevre and Test">
        Return to the Chevre SSO configuration panel. Paste the **metadata URL** into the **IdP Metadata URL** field, or click **Upload XML** to upload the metadata file. Click **Save & Test**. Chevre will perform a test authentication flow and display a success confirmation if everything is configured correctly.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Azure AD / Entra ID">
    Follow these condensed steps to configure SAML SSO with Microsoft Azure Active Directory (now Microsoft Entra ID).

    <Steps>
      <Step title="Get Your SP Details from Chevre">
        In Chevre, go to **Settings → Security → SSO → Configure SAML**. Copy the **ACS URL** and **Entity ID**.
      </Step>

      <Step title="Create an Enterprise Application in Azure">
        In the Azure portal, navigate to **Azure Active Directory → Enterprise Applications → New Application → Create your own application**. Name it `Chevre`, select **Integrate any other application you don't find in the gallery**, and click **Create**.
      </Step>

      <Step title="Configure SAML in Azure">
        Open the new application and go to **Single sign-on → SAML**. In the **Basic SAML Configuration** section, set:

        * **Identifier (Entity ID):** paste the Entity ID from Chevre.
        * **Reply URL (ACS URL):** paste the ACS URL from Chevre.

        Save the configuration.
      </Step>

      <Step title="Map Attributes">
        In the **Attributes & Claims** section, ensure the following claims are present:

        | Claim name   | Source attribute |
        | ------------ | ---------------- |
        | `email`      | `user.mail`      |
        | `first_name` | `user.givenname` |
        | `last_name`  | `user.surname`   |
      </Step>

      <Step title="Paste Metadata into Chevre and Test">
        In the **SAML Certificates** section, copy the **App Federation Metadata URL**. Paste it into the **IdP Metadata URL** field in Chevre's SSO panel and click **Save & Test**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Google Workspace">
    Follow these condensed steps to configure SAML SSO with Google Workspace.

    <Steps>
      <Step title="Get Your SP Details from Chevre">
        In Chevre, go to **Settings → Security → SSO → Configure SAML**. Copy the **ACS URL** and **Entity ID**.
      </Step>

      <Step title="Create a Custom SAML App in Google Admin">
        In the Google Admin console, navigate to **Apps → Web and mobile apps → Add app → Add custom SAML app**. Name the app `Chevre` and click **Continue**.
      </Step>

      <Step title="Download Google IdP Metadata">
        On the **Google Identity Provider details** screen, click **Download Metadata** to save the IdP XML file. Click **Continue**.
      </Step>

      <Step title="Configure the Service Provider Details">
        On the **Service Provider Details** screen, enter:

        * **ACS URL:** paste the ACS URL from Chevre.
        * **Entity ID:** paste the Entity ID from Chevre.
        * **Name ID format:** `EMAIL`
        * **Name ID:** Basic information → Primary email

        Click **Continue**.
      </Step>

      <Step title="Map Attributes">
        Add the following attribute mappings:

        | Google Directory attribute | App attribute |
        | -------------------------- | ------------- |
        | Primary email              | `email`       |
        | First name                 | `first_name`  |
        | Last name                  | `last_name`   |

        Click **Finish**. Enable the app for the appropriate organizational units in Google Admin.
      </Step>

      <Step title="Upload Metadata to Chevre and Test">
        In Chevre's SSO panel, click **Upload XML** and select the metadata file you downloaded from Google. Click **Save & Test**.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## JIT Provisioning

Just-in-Time (JIT) provisioning automatically creates a Chevre account for a user the first time they successfully authenticate via SSO — no manual invitation required.

When JIT provisioning is enabled:

* Chevre creates a new member account using the `email`, `first_name`, and `last_name` attributes sent by your IdP.
* The new member is assigned the default **Member** role. Admins can change roles after the first login.
* If an account already exists with the same email address, JIT provisioning links the SSO identity to that existing account instead of creating a duplicate.

To enable JIT provisioning, go to **Settings → Security → SSO** and toggle **Just-in-Time Provisioning** to **On**, then click **Save**.

## Enforcing SSO

Once SSO is configured and tested, you can make it mandatory for all workspace members. When SSO is enforced:

* Password-based login is disabled for all members except accounts that explicitly retain it (see the warning below).
* Members who try to log in with a password are redirected to your IdP login page.
* New members joining via JIT provisioning can only log in through SSO.

To enforce SSO, go to **Settings → Security → SSO** and toggle **Enforce SSO for all members** to **On**, then click **Save Policy**.

<Warning>
  Before enforcing SSO, ensure at least one **Owner** account has password login explicitly preserved as a break-glass fallback. If your IdP goes down and SSO is enforced without a fallback, no one will be able to access the workspace. To preserve password login for an account, go to **Settings → Security → SSO → Exceptions** and add that user's email address before enabling enforcement.
</Warning>

## Troubleshooting SSO

<Accordion title="Attribute mapping failure: email or name fields are blank">
  Chevre requires the `email`, `first_name`, and `last_name` attributes to be present in every SAML assertion. If any of these are missing, the login will fail with an attribute mapping error.

  Check your IdP's attribute statement configuration and verify that each attribute name exactly matches what Chevre expects (case-sensitive). In Okta, re-open the SAML app settings and confirm the **Attribute Statements** section contains all three mappings. In Azure, check the **Attributes & Claims** section. In Google Workspace, review the **Attribute Mapping** step of your custom SAML app.

  After saving changes in your IdP, click **Save & Test** again in Chevre to re-run the authentication flow.
</Accordion>

<Accordion title="Invalid ACS URL or 'Destination' mismatch error">
  This error typically means the ACS URL entered in your IdP does not exactly match the one Chevre expects. Even a trailing slash or `http` vs `https` difference will cause this failure.

  In Chevre, go to **Settings → Security → SSO → Configure SAML** and re-copy the ACS URL. Paste it freshly into your IdP's configuration, replacing the previous value. Make sure there are no extra spaces or line breaks.
</Accordion>

<Accordion title="Clock skew: 'Assertion is not yet valid' or 'Assertion has expired'">
  SAML assertions include a validity window tied to the server clock. If the clock on your IdP server and the clock on Chevre's servers differ by more than **five minutes**, assertions will be rejected.

  Most cloud-hosted IdPs (Okta, Azure AD, Google Workspace) sync their clocks automatically, so this issue is uncommon with those providers. If you are using a self-hosted or on-premises IdP, ensure it is configured to use NTP for time synchronization. Contact your system administrator to verify and correct the server clock.
</Accordion>

<Accordion title="SSO login redirects correctly but returns to the login page">
  This usually indicates a session cookie issue or a misconfigured RelayState. Ensure that:

  * Third-party cookies are not blocked in the user's browser for `app.chevre.io`.
  * The RelayState value set in your IdP (if any) matches a valid destination URL within Chevre.
  * The user's browser is not in a private/incognito mode that strips cookies between the IdP redirect and the Chevre callback.

  If the issue persists for a specific user, ask them to clear their browser cookies for `chevre.io` and try again.
</Accordion>