> 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/saml-single-sign-on.md).

# SAML Single Sign-On

Learn how to configure SAML Single Sign-On for Couchdrop

## Overview

Couchdrop supports SAML Single Sign-On for access to the Couchdrop web interface.

You can connect Couchdrop to a SAML identity provider such as Microsoft Entra ID and use your existing organizational identities to sign in to Couchdrop.

{% hint style="info" %}
SAML SSO applies to **web interface authentication only**. It does not replace passwords or SSH keys used for SFTP, SCP, FTP, or other file transfer protocols.

Users must already exist in Couchdrop before they can sign in using SAML.
{% endhint %}

## Configure SAML SSO with Microsoft Entra ID

{% hint style="warning" %}

### Before you start

To configure SAML SSO, you will need:

* Owner access to Couchdrop
* Access to configure an Enterprise Application in Microsoft Entra ID
* Existing Couchdrop users for everyone who will sign in using SAML
* Passwords configured for those users if they also require protocol access such as SFTP or FTP
  {% endhint %}

{% stepper %}
{% step %}

### Create an Enterprise Application

In the Microsoft Entra admin center, navigate to **Enterprise applications** > **New application** > **Create your own application**.

Enter a meaningful name for the application. This name is only used to identify the application within Microsoft Entra.

Select **Integrate any other application you don't find in the gallery (Non-gallery)**, then create the application.
{% endstep %}

{% step %}

### Assign users and groups

In the Enterprise Application, navigate to **Manage** > **Users and groups**.

Select **Add user/group**, choose the users or groups that should be able to access Couchdrop, then select **Assign**.
{% endstep %}

{% step %}

### Enable SAML in Couchdrop

In Couchdrop, navigate to **Administration** > **SSO** > **SAML SSO**.

Enable **SAML SSO**.

Couchdrop will display two Service Provider values:

* **Couchdrop Entity ID**
* **Couchdrop ACS URL**

These values are unique to your Couchdrop account. You will use them to configure the Microsoft Entra Enterprise Application in the next step.
{% endstep %}

{% step %}

### Configure SAML in Microsoft Entra ID

In your Enterprise Application, navigate to **Manage** > **Single sign-on** and select **SAML**.

Update **Step 1 — Basic SAML Configuration** with the following required fields:

| Microsoft Entra field                          | Couchdrop value         |
| ---------------------------------------------- | ----------------------- |
| **Identifier (Entity ID)**                     | **Couchdrop Entity ID** |
| **Reply URL (Assertion Consumer Service URL)** | **Couchdrop ACS URL**   |

Go to **Step 3 — SAML Certificates**.

Download **Certificate (Base 64)**. You will need to open this in a text editor and copy/paste into the **SAML IDP Certificate in** the next step.

Go to **Step 4 — Set up `<app name>`**.

Microsoft Entra provides the identity provider details Couchdrop requires for the SAML connection.

Copy the following values to use in Couchdrop in the next step:

* **Login URL**
* **Microsoft Entra Identifier**

You will use the **Login URL** and **Microsoft Entra Identifier** when configuring the Couchdrop SAML IDP settings.
{% endstep %}

{% step %}

### Configure the identity provider in Couchdrop

Return to **Administration** > **SSO** > **SAML SSO** and enter the identity provider details from Microsoft Entra ID.

| Couchdrop setting                 | Microsoft Entra value                                                | Description                                                                                                                              |
| --------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **SAML IDP Entity ID**            | Microsoft Entra Identifier                                           | Identifies your SAML identity provider.                                                                                                  |
| **SAML IDP SSO URL**              | Login URL                                                            | The SAML login endpoint Couchdrop sends authentication requests to.                                                                      |
| **SAML IDP Certificate**          | Certificate (Base64)                                                 | The certificate Couchdrop uses to validate SAML responses from your identity provider.                                                   |
| **SAML IDP Email Attribute Flag** | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | Identifies the SAML attribute containing the user's email address. This is the standard value used by Microsoft Entra SAML applications. |

An example configuration is:

<table><thead><tr><th width="241.9609375">Setting</th><th>Example</th></tr></thead><tbody><tr><td><strong>SAML IDP Entity ID</strong></td><td><code>https://sts.windows.net/&#x3C;tenant-id>/</code></td></tr><tr><td><strong>SAML IDP SSO URL</strong></td><td><code>https://login.microsoftonline.com/&#x3C;tenant-id>/saml2</code></td></tr><tr><td><strong>SAML IDP Certificate</strong></td><td><code>-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----</code></td></tr><tr><td><strong>SAML IDP Email Attribute Flag</strong></td><td><code>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress</code></td></tr></tbody></table>
{% endstep %}

{% step %}

### Save and test SAML login

Save the SAML configuration and test signing in to the Couchdrop web interface using a user that:

* Already exists in Couchdrop
* Has been assigned to the Microsoft Entra Enterprise Application
* Has an email address that matches the value provided through the configured SAML email attribute
  {% endstep %}
  {% endstepper %}

## SAML settings

### Login settings

| Setting              | Description                                                                     |
| -------------------- | ------------------------------------------------------------------------------- |
| **Enable SAML SSO**  | Enables SAML authentication for the Couchdrop web interface.                    |
| **Force SAML Login** | Requires web users to authenticate using the configured SAML identity provider. |

### Identity provider configuration

| Setting                           | Description                                                                   |
| --------------------------------- | ----------------------------------------------------------------------------- |
| **SAML IDP Entity ID**            | The Entity ID supplied by your identity provider.                             |
| **SAML IDP SSO URL**              | The SAML Single Sign-On URL supplied by your identity provider.               |
| **SAML IDP Certificate**          | The Base64 certificate used to validate responses from the identity provider. |
| **SAML IDP Email Attribute Flag** | The SAML attribute Couchdrop uses to identify the user's email address.       |

### Couchdrop Service Provider details

Couchdrop displays the values required when configuring Couchdrop as a SAML Service Provider with your identity provider.

| Setting                 | Example                                                    |
| ----------------------- | ---------------------------------------------------------- |
| **Couchdrop Entity ID** | `https://my.couchdrop.io/login/saml/<account-id>`          |
| **Couchdrop ACS URL**   | `https://my.couchdrop.io/login/saml/callback/<account-id>` |