> For the complete documentation index, see [llms.txt](https://docs.durohub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.durohub.com/advanced-topics/saml-sso-setup.md).

# SAML SSO Setup

Enable enterprise Single Sign-On (SSO) for your Duro organization using SAML 2.0 with popular identity providers like Google Workspace, Microsoft Entra ID, Okta, and others.

{% hint style="info" %}
This guide covers the complete SAML integration workflow including Auth0 configuration, Identity Provider setup, and Duro organization settings.
{% endhint %}

## Overview

SAML (Security Assertion Markup Language) allows your users to authenticate using your company's existing identity provider, providing centralized access control and enhanced security through features like multi-factor authentication.

### Authentication Flow

1. User enters their organization identifier on the Duro login page
2. Duro redirects to Auth0 with the organization's SAML connection
3. Auth0 redirects to your Identity Provider (Google, Entra ID, etc.)
4. User authenticates with corporate credentials
5. IdP sends SAML assertion back to Auth0
6. Auth0 returns user to Duro, fully authenticated

### Prerequisites

Before starting, ensure you have:

* Administrative access to your Identity Provider (Google Workspace, Microsoft Entra ID, etc.)
* Auth0 tenant credentials (contact your Duro technical team)
* PostHog access (for Duro internal team to enable feature flag)
* Duro organization admin access (Site Admin role required)

## Quick Start

### Phase 1: Create Auth0 Application

**Duration**: 5-10 minutes

First, create a Single Page Application in your Auth0 tenant:

1. Navigate to **Applications** → **Applications** in Auth0 Dashboard
2. Click **Create Application**
3. Select **Single Page Application** type
4. Configure the allowed URLs:

```
Allowed Callback URLs:
http://localhost:5173/callback,
https://your-duro-domain.com/callback

Allowed Logout URLs:
http://localhost:5173,
https://your-duro-domain.com

Allowed Web Origins:
http://localhost:5173,
https://your-duro-domain.com
```

{% hint style="warning" %}
Replace `your-duro-domain.com` with your actual Duro installation domain.
{% endhint %}

### Phase 2: Create SAML Connection

**Duration**: 5 minutes

Create a SAML connection in Auth0 **before** configuring your Identity Provider:

1. Go to **Authentication** → **Enterprise** → **SAML**
2. Click **Create Connection**
3. Choose a descriptive name (e.g., `acmecorp-saml`)
4. **Copy the Service Provider details** - Auth0 displays:
   * **ACS URL**: `https://{tenant}.auth0.com/login/callback?connection={name}`
   * **Entity ID**: `urn:auth0:{tenant}:{connection-name}`

These values are automatically generated based on your Auth0 tenant and connection name. You'll need them in the next step.

### Phase 3: Configure Your Identity Provider

#### Google Workspace

**Duration**: 10-15 minutes

1. **Access Google Admin Console** at [admin.google.com](https://admin.google.com)
2. Go to **Apps** → **Web and mobile apps** → **Add App** → **Add custom SAML app**
3. Set app name (e.g., "Duro") and click **Continue**
4. **Download IdP Information**

   Google displays your IdP details. You'll use these in Auth0 later.

   * **Download Metadata**: Click to download the XML metadata file

   OR manually note the following values: (protip: these values look nearly identical but are different)

   * **SSO URL**: `https://accounts.google.com/o/saml2/idp?idpid=XXXXXXXXX`
   * **Entity ID**: `https://accounts.google.com/o/saml2?idpid=XXXXXXXXX`
   * **Certificate**: Download the `.pem` or `.crt` file
   * Click **Continue**
5. **Service Provider Details**

   Use the values you copied from Auth0 in Phase 2:

   * **ACS URL**: Paste the ACS URL from Auth0
     * Example: `https://duro-dev.us.auth0.com/login/callback?connection=google-saml`
   * **Entity ID**: Paste the Entity ID from Auth0
     * Example: `urn:auth0:duro-dev:google-saml`
   * **Name ID format**: Select `EMAIL`
   * **Name ID**: Select `Basic Information > Primary email`
   * Click **Continue**
6. **Attribute Mapping**
   * You can skip this step and just click **Finish**
7. **Enable the App**
   * You'll see the app in your Web and mobile apps list with status "OFF for everyone"
   * Click on the app name
   * Click **User access**
   * Select **ON for everyone** (or choose specific organizational units)
   * Click **Save**
8. **Verify App Status**
   * The app should now show "ON for everyone" (or your selected OUs)
   * Changes may take a few minutes to propagate

{% hint style="info" %}
The SSO URL and Entity ID from Google look similar but are different - one has `/idp` and one has just `/saml2`. Make sure to copy the correct values.
{% endhint %}

#### Microsoft Entra ID (Azure AD)

**Duration**: 10-15 minutes

1. **Access Entra Admin Center**
   * Navigate to [entra.microsoft.com](https://entra.microsoft.com)
   * Sign in with your Microsoft admin account
2. **Create Enterprise Application**
   * Go to **Identity** → **Applications** → **Enterprise applications**
   * Click **New application**
   * Click **Create your own application**
   * **Name**: `Duro`
   * Select **Integrate any other application you don't find in the gallery (Non-gallery)**
   * Click **Create**
3. **Assign Users**
   * Go to **Users and groups** in the left sidebar
   * Click **Add user/group**
   * Select users or groups that should have access
   * Click **Assign**
4. **Configure SAML**

   * Go to **Single sign-on** in the left sidebar
   * Select **SAML**
   * Click **Edit** on **Basic SAML Configuration**

   **Enter Service Provider details from Auth0**:

   * **Identifier (Entity ID)**: Paste Entity ID from Auth0
     * Example: `urn:auth0:duro-dev:google-saml`
   * **Reply URL (Assertion Consumer Service URL)**: Paste ACS URL from Auth0
     * Example: `https://duro-dev.us.auth0.com/login/callback?connection=google-saml`
   * **Sign on URL**: Same as Reply URL
   * Click **Save**
5. **Download Certificate and Copy URLs**
   * Go back to the SAML configuration page
   * Under **SAML Certificates**, download **Certificate (Base64)**
   * Under **Set up Duro**, copy:
     * **Login URL** (this is your SSO URL)
     * **Microsoft Entra Identifier** (Entity ID)
     * **Logout URL** (optional)
6. **Save Configuration**
   * Keep these values for the next phase

### Phase 4: Complete Auth0 Configuration

**Duration**: 5 minutes

Return to your SAML connection in Auth0:

1. Navigate back to **Authentication** → **Enterprise** → **SAML**
2. Click on your connection name
3. **Enter IdP details**:
   * Sign In URL: The SSO URL from your IdP
   * Upload or paste the X509 Signing Certificate
   * Protocol Binding: `HTTP-POST` (default)
4. Click **Save Changes**
5. Go to the **Applications** tab within your SAML connection
6. Find your Duro application (created in Phase 1)
7. Navigate to the *Connections* tab
8. **Toggle ON** to enable this connection for the application

### Phase 5: Enable Feature Flag

**Duration**: 2-3 minutes

**Note**: This step is typically performed by the Duro internal technical team.

The Duro technical team (or your on-prem administrator) will enable the `samlAuthentication` feature flag in PostHog for your organization.

### Phase 6: Configure SAML in Duro Organization Settings

**Duration**: 2 minutes

This is the final step, performed by a Duro organization administrator.

1. **Sign In to Duro**
   * Navigate to your Duro installation
   * Sign in with an account that has **SITE Admin** role
   * You must sign in using traditional email/password or Google SSO (not SAML yet)
2. **Navigate to Organization Settings**
   * Go to your organization settings page:
     * Format: `https://{your-duro-domain}/org/@{company-org-slug}/settings/authentication`
     * Example: `https://duro.example.com/org/@acmecorp/settings/authentication`
3. **Enable SAML SSO**

   You should see a "SAML Configuration" section

   * **Toggle ON** the "Enable SAML SSO" switch
   * **Auth0 SAML Connection Name**: Enter the exact connection name from Phase 2
     * Example: `google-saml` or `acmecorp-saml`
     * This MUST match the connection name in Auth0 exactly (case-sensitive)
   * **Enforce SAML** (Optional):
     * Toggle **ON** if you want to require all users to authenticate via SAML
     * Toggle **OFF** to allow both SAML and traditional login methods
     * Recommended: Leave OFF initially for testing
4. **Save Configuration**
   * Click **Save** or **Update Settings**
   * You should see a success message
5. **Verify Configuration**
   * The page should display:
     * ✅ SAML SSO Enabled
     * Connection name: `{your-connection-name}`
     * Enforce SAML: \[Your setting]

## Testing Your Setup

Before announcing to users, thoroughly test the SAML flow:

### Test Checklist

1. **Open incognito/private browser** (ensures clean session)
2. **Navigate to Duro** and click "Sign in with SSO"
3. **Enter organization slug** (e.g., `acmecorp`)
4. **Verify redirect chain**:
   * Redirects to Auth0
   * Redirects to your IdP (Google/Entra)
   * Redirects back to Duro
5. **Authenticate** with test user credentials
6. **Verify user profile**:
   * Name and email populated correctly
   * User is member of correct organization
   * Session persists on page refresh
7. **Test logout** functionality

{% hint style="info" %}
SAML configuration changes require Site Admin permissions and are typically managed through the Duro UI for security reasons.
{% endhint %}


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.durohub.com/advanced-topics/saml-sso-setup.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.