🔗 Subdomain-based multi-tenancy in Phoenix: an implementation guide

At Alembic, we recently worked with a client who needed a multi-tenant SaaS platform built with Phoenix and Ash Framework. Their requirements posed several interesting technical challenges:

• The application needed to serve multiple customer organisations (tenants) from a single instance
• Each organisation required its own branded subdomain: <org_slug>.example.com.
• Users could belong to multiple organisations and needed to switch between them easily
• Switching between organisations shouldn't require re-authentication

While multi-tenancy can be implemented in various ways, we determined that a subdomain-per-tenant approach and schema-per-tenant database design would provide the best user experience and clearest separation for our clients’ needs.

However, this approach introduced several technical hurdles that aren't immediately obvious when building Phoenix applications. In this post, we'll share our implementation strategy, focusing on four key aspects:

1. Database setup with tables in the public schema and per-tenant schemas
2. Configuring authentication cookies to work across subdomains
3. Setting up Content Security Policy (CSP) for proper subdomain navigation
4. Implementing tenant resolution and user membership verification

The solution we developed provides a seamless experience for users while maintaining proper security boundaries. We hope this implementation guide helps other Elixir developers facing similar client requirements.