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.

This guide covers the complete SAML integration workflow including Auth0 configuration, Identity Provider setup, and Duro organization settings.

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

User enters their organization identifier on the Duro login page
Duro redirects to Auth0 with the organization's SAML connection
Auth0 redirects to your Identity Provider (Google, Entra ID, etc.)
User authenticates with corporate credentials
IdP sends SAML assertion back to Auth0
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:

Navigate to Applications → Applications in Auth0 Dashboard
Click Create Application
Select Single Page Application type
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

Replace your-duro-domain.com with your actual Duro installation domain.

Phase 2: Create SAML Connection

Duration: 5 minutes

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

Go to Authentication → Enterprise → SAML
Click Create Connection
Choose a descriptive name (e.g., acmecorp-saml)
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

Access Google Admin Console at admin.google.com
Go to Apps → Web and mobile apps → Add App → Add custom SAML app
Set app name (e.g., "Duro") and click Continue
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
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
Attribute Mapping
- You can skip this step and just click Finish
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
Verify App Status
- The app should now show "ON for everyone" (or your selected OUs)
- Changes may take a few minutes to propagate

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.

Microsoft Entra ID (Azure AD)

Duration: 10-15 minutes

Access Entra Admin Center
- Navigate to entra.microsoft.com
- Sign in with your Microsoft admin account
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
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
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
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)
Save Configuration
- Keep these values for the next phase

Phase 4: Complete Auth0 Configuration

Duration: 5 minutes

Return to your SAML connection in Auth0:

Navigate back to Authentication → Enterprise → SAML
Click on your connection name
Enter IdP details:
- Sign In URL: The SSO URL from your IdP
- Upload or paste the X509 Signing Certificate
- Protocol Binding: HTTP-POST (default)
Click Save Changes
Go to the Applications tab within your SAML connection
Find your Duro application (created in Phase 1)
Navigate to the Connections tab
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.

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)
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
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
Save Configuration
- Click Save or Update Settings
- You should see a success message
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

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

SAML configuration changes require Site Admin permissions and are typically managed through the Duro UI for security reasons.

PreviousError Handling NextIntroduction to Duro's Config System

Last updated 11 days ago

Was this helpful?