7.5 KiB

Raw Blame History

DocuSeal Omniauth Implementation Guide

This document describes the complete implementation of omniauth/SSO functionality in DocuSeal, restoring the features that were previously gated behind paywall checks.

Overview

We have successfully implemented comprehensive omniauth support with the following providers:

SAML 2.0 - For enterprise SSO integration
Google OAuth2 - For Google account authentication
Microsoft Graph - For Microsoft/Office 365 authentication

What Was Implemented

1. Database Schema Changes

Added provider and uid columns to the users table
Created migration: db/migrate/20250719104801_add_omniauth_to_users.rb
Added unique index on [provider, uid] combination

2. User Model Updates

Added :omniauthable to Devise modules
Configured omniauth providers: %i[saml google_oauth2 microsoft_graph]
Implemented User.from_omniauth(auth) class method for handling authentication callbacks
Added support for both single-tenant and multi-tenant account creation

3. Devise Configuration

Updated config/initializers/devise.rb with omniauth provider configurations
Added environment variable-based configuration for SAML
Configured Google OAuth2 and Microsoft Graph providers
Added proper attribute mapping for SAML assertions

4. Controllers

Created app/controllers/users/omniauth_callbacks_controller.rb
Handles callbacks for all three providers (SAML, Google, Microsoft)
Includes proper error handling and session management
Updated app/controllers/sso_settings_controller.rb with configuration management

5. Views and UI

Replaced SSO paywall placeholder with functional SAML configuration form
Updated login form to include all three authentication providers
Added SSO settings interface for SAML configuration
Removed Docuseal.multitenant? checks that were gating SSO features

6. Routes

Updated routes to include omniauth callbacks
Added update action to SSO settings controller
Enabled SSO settings for all users (removed paywall restrictions)

7. Gemfile Dependencies

Added the following gems:

gem 'omniauth'
gem 'omniauth-rails_csrf_protection'
gem 'omniauth-saml'
gem 'omniauth-google-oauth2'
gem 'omniauth-microsoft_graph'

8. Development Environment

Created Dockerfile.dev for development with mounted codebase
Created docker-compose.dev.yml for local development environment
Configured development environment with PostgreSQL and Redis

Configuration

SAML Configuration

Environment Variables

Set these environment variables for SAML configuration:

SAML_IDP_SSO_SERVICE_URL=https://your-idp.com/sso/saml
SAML_IDP_CERT_FINGERPRINT=AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD
SAML_SP_ENTITY_ID=docuseal
APP_URL=http://localhost:3000

Database Configuration

Alternatively, configure SAML through the web interface at /settings/sso which stores encrypted configuration in the database.

Service Provider URLs

Provide these URLs to your Identity Provider:

Assertion Consumer Service URL: http://localhost:3000/users/auth/saml/callback
SP Metadata URL: http://localhost:3000/users/auth/saml/metadata
SP Entity ID: docuseal (or your custom value)

Google OAuth2 Configuration

Add to Rails credentials or environment variables:

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

Microsoft Graph Configuration

Add to Rails credentials or environment variables:

MICROSOFT_CLIENT_ID=your-microsoft-client-id
MICROSOFT_CLIENT_SECRET=your-microsoft-client-secret

Usage

For Users

Navigate to the login page
Choose from available authentication methods:
- Sign in with Google
- Sign in with Microsoft
- Sign in with SAML SSO (if configured)
Complete authentication with your chosen provider
You'll be automatically signed in or prompted to complete registration

For Administrators

Go to Settings → SSO
Configure SAML settings with your Identity Provider details
Test the configuration using the "Test SAML Login" button
Users can now authenticate using the configured SSO provider

Development Setup

Using Docker (Recommended)

# Build the development environment
docker-compose -f docker-compose.dev.yml build

# Start the development environment
docker-compose -f docker-compose.dev.yml up

# Access the application at http://localhost:3000

Local Development

# Install dependencies
bundle install
yarn install

# Run database migrations
rails db:create db:migrate

# Start the development server
rails server

Testing

SAML Testing

Set up environment variables for SAML configuration
Navigate to /settings/sso to configure SAML
Use the "Test SAML Login" button to verify configuration
Check logs for any authentication errors

OAuth Testing

Configure Google/Microsoft credentials
Navigate to login page
Click "Sign in with Google" or "Sign in with Microsoft"
Complete OAuth flow and verify user creation/authentication

Security Considerations

CSRF Protection: Implemented via omniauth-rails_csrf_protection gem
Secure Credentials: Store sensitive configuration in Rails credentials or environment variables
Certificate Validation: SAML certificate fingerprints are validated
Session Management: Proper session cleanup and management implemented

Troubleshooting

Common Issues

"NameError: uninitialized constant EncryptedConfig"
- This was resolved by moving SAML configuration to environment variables
- Ensure proper initialization order in Devise configuration
"Invalid credentials" errors
- Verify OAuth client IDs and secrets are correct
- Check redirect URIs match exactly
SAML authentication failures
- Verify IdP certificate fingerprint is correct
- Check that assertion consumer service URL matches
- Ensure name identifier format matches IdP configuration

Logs

Check application logs for detailed error messages:

docker-compose -f docker-compose.dev.yml logs app

Files Modified/Created

New Files

db/migrate/20250719104801_add_omniauth_to_users.rb
app/controllers/users/omniauth_callbacks_controller.rb
app/views/sso_settings/_saml_form.html.erb
Dockerfile.dev
docker-compose.dev.yml
OMNIAUTH_IMPLEMENTATION.md

Modified Files

Gemfile - Added omniauth gems
app/models/user.rb - Added omniauthable and from_omniauth method
config/initializers/devise.rb - Added omniauth provider configurations
app/controllers/sso_settings_controller.rb - Added update method
app/views/sso_settings/index.html.erb - Replaced placeholder with form
app/views/devise/sessions/new.html.erb - Added omniauth provider buttons
app/views/shared/_settings_nav.html.erb - Removed paywall check
config/routes.rb - Added update route for SSO settings

Next Steps

Production Deployment: Configure production environment variables
Additional Providers: Add more omniauth providers as needed
Advanced SAML: Implement IdP-initiated SSO and SLO (Single Logout)
User Management: Add admin interface for managing SSO users
Audit Logging: Add logging for SSO authentication events

Support

For issues or questions about this implementation, refer to:

Devise Omniauth Documentation
Omniauth SAML Documentation
DocuSeal application logs and error messages

7.5 KiB Raw Blame History