> For the complete documentation index, see [llms.txt](https://docs.couchdrop.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.couchdrop.io/administration/scim-and-sso/auth0.md).

# SCIM & SSO with Auth0

Learn how to configure Couchdrop to sync with Auth0

## Overview

Couchdrop supports integration with Auth0 for automated user provisioning and Single Sign-On (SSO).

You can use **SCIM** to manage Couchdrop users directly from Auth0 and **SAML SSO** to allow users to authenticate using their Auth0 credentials.

These are separate configurations that can be used together to centralize user management and authentication.

## Configure SCIM Provisioning

SCIM allows Auth0 to automatically provision and manage Couchdrop users when accounts are created, updated, or deleted.

Couchdrop uses Auth0's outbound SCIM integration through Event Streams and Actions.

{% hint style="warning" %}

### Before you start

To configure Auth0 with Couchdrop, you will need:

* Administrator access to Couchdrop
* Administrator access to your Auth0 tenant
* A Couchdrop SCIM token
* Auth0 Events and Actions enabled
* Access to configure SAML SSO in Couchdrop
  {% endhint %}

{% stepper %}
{% step %}

### Create an Event Stream in Auth0

In Auth0, navigate to **Event Streams** and select **+ Create Event Stream**.

1. Under **Destinations**, select **Auth0 Actions**.
2. Enter a name such as `Couchdrop SCIM`.
3. Under **Select Events**, enable:
   * `user.created`
   * `user.updated`
   * `user.deleted`

These events are used to synchronize changes from Auth0 to Couchdrop.
{% endstep %}

{% step %}

### Configure the Couchdrop SCIM connection

In the Auth0 Actions Editor, open **Secrets** and configure the following values:

| Setting             | Value                              |
| ------------------- | ---------------------------------- |
| `SCIM_BASE_URL`     | `https://api.couchdrop.io/scim/v2` |
| `SCIM_BEARER_TOKEN` | Your Couchdrop SCIM token          |

The SCIM token is used to authenticate provisioning requests from Auth0 to Couchdrop.

{% hint style="info" %}
Use your **SCIM token** from Couchdrop, not a standard Couchdrop API token.
{% endhint %}
{% endstep %}

{% step %}

### Configure and deploy the SCIM Action

Follow Auth0's [Outbound SCIM Provisioning Guide](https://auth0.com/docs/customize/events/send-outbound-scim) to configure the provisioning Action.

1. Copy the outbound SCIM 2.0 user provisioning Action template.
2. Paste the template into the Auth0 Actions Editor.
3. Review the user attribute mappings.
4. Save and deploy the Action.

The default template maps the Auth0 user's email address to the SCIM `userName` attribute.
{% endstep %}

{% step %}

### Test SCIM Provisioning

Create a test user in Auth0 and verify that the user is provisioned in Couchdrop.

You can also test updating and deleting a user in Auth0 to verify that the corresponding changes are synchronized with Couchdrop.

{% hint style="info" %}
Auth0's outbound SCIM Action handles user provisioning. Group provisioning is not included in the default Action template.

Existing Auth0 users must also be accounted for when enabling provisioning, as Event Streams do not automatically synchronize historical user creation events.
{% endhint %}
{% endstep %}
{% endstepper %}

## Configure SAML SSO

SAML SSO allows Couchdrop users to authenticate using Auth0 as their Identity Provider (IdP).

{% stepper %}
{% step %}

### Enable SAML in Auth0

In your Auth0 Dashboard:

1. Navigate to **Applications > Applications**.
2. Select the application you want to configure.
3. Open **Addons**.
4. Select **SAML2 Web App**.
5. Enable and configure the SAML add-on using the service provider details from Couchdrop.
   {% endstep %}

{% step %}

### Retrieve the SAML configuration

From the Auth0 SAML2 Web App configuration, retrieve the following values:

| Auth0                           | Couchdrop                         |
| ------------------------------- | --------------------------------- |
| **Issuer**                      | **IDP ENTITY ID**                 |
| **Identity Provider Login URL** | **SAML IDP SSO Url**              |
| **Download Certificate**        | **Identity Provider Certificate** |

These values are required to establish the SAML connection between Auth0 and Couchdrop.
{% endstep %}

{% step %}

### Configure SAML in Couchdrop

Open your Couchdrop SAML SSO settings and provide the details collected from Auth0.

Configure the following fields:

* **IDP ENTITY ID:** Enter the Auth0 Issuer.
* **SAML IDP SSO Url:** Enter the Auth0 Identity Provider Login URL.
* **Identity Provider Certificate:** Provide the certificate downloaded from Auth0.

For the email attribute, use:

`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`

This identifies the email address attribute used to match the Auth0 identity with the corresponding Couchdrop user.

Save the configuration.
{% endstep %}

{% step %}

### Test SAML Authentication

Once configured, test the integration using an existing user.

1. Open the Couchdrop login page.
2. Select the SSO login option.
3. Authenticate using Auth0.
4. Verify that the user can access Couchdrop.

If authentication fails, check the SAML Issuer, SSO URL, Identity Provider Certificate, and email attribute configuration.
{% endstep %}
{% endstepper %}

## How SCIM and SAML work together

When SCIM and SAML are both enabled, Auth0 manages user provisioning and authentication for Couchdrop.

* **SCIM** manages the creation, updating, and removal of user accounts.
* **SAML SSO** authenticates users when they sign in.

This allows organizations to manage Couchdrop user identities through Auth0 while keeping file access and permissions controlled within Couchdrop.

For more information, refer to [Auth0's Outbound SCIM documentation](https://auth0.com/docs/customize/events/send-outbound-scim).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.couchdrop.io/administration/scim-and-sso/auth0.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
