528 | ```
529 |
530 | ### Invitation Handling
531 |
532 | For the single-organization model, invitation handling needs careful consideration since accepting an invitation would mean leaving the user's current organization:
533 |
534 | ```elixir
535 | def accept_invitation(token) do
536 | with {:ok, invitation} <- get_valid_invitation(token),
537 | {:ok, user} <- get_or_create_user(invitation) do
538 |
539 | # If user already belongs to another organization,
540 | # we need to move them to the new one
541 | if user.organization_id && user.organization_id != invitation.organization_id do
542 | # Update the user to join the new organization with the invited role
543 | user
544 | |> User.organization_changeset(%{
545 | organization_id: invitation.organization_id,
546 | role: invitation.role
547 | })
548 | |> Repo.update()
549 | else
550 | # First-time organization assignment
551 | user
552 | |> User.organization_changeset(%{
553 | organization_id: invitation.organization_id,
554 | role: invitation.role
555 | })
556 | |> Repo.update()
557 | end
558 | |> case do
559 | {:ok, updated_user} ->
560 | mark_invitation_accepted(invitation)
561 | {:ok, updated_user}
562 | error ->
563 | error
564 | end
565 | end
566 | end
567 | ```
568 |
569 | ## Development Phases Checklist
570 |
571 | Here's a concise checklist for implementing the single-organization multi-tenant system:
572 |
573 | 1. **Database Setup**:
574 | - Create organizations table with name, slug, etc.
575 | - Add organization_id and role directly to the users table
576 | - Add is_sysadmin boolean field to users table for cross-organization admin functionality
577 |
578 | 2. **Schema Definitions**:
579 | - Define Organization schema with has_many relationship to users
580 | - Update User schema with belongs_to relationship to organization and role field
581 |
582 | 3. **Authentication Integration**:
583 | - Modify registration flow to create or join an organization
584 | - Update login flow to redirect to the user's organization
585 |
586 | 4. **Configure Phoenix Scopes**:
587 | - Extend Scope to automatically include the user's organization
588 | - Set up organization scope configuration
589 |
590 | 5. **Authorization (Bodyguard) Setup**:
591 | - Implement policies using user.role directly
592 | - Add sysadmin checks as a first rule in policies
593 |
594 | 6. **Context Functions with Scope**:
595 | - Generate organization and domain-specific context functions
596 | - Add role management with "last admin" protection
597 |
598 | 7. **UI Implementation**:
599 | - Create organization settings and user management LiveViews
600 | - Add conditional UI elements based on user's role
601 | - Implement invitation workflow with clear organization transfer warnings
602 |
603 | 8. **Testing**:
604 | - Test data isolation between organizations
605 | - Test role-based access control
606 | - Test sysadmin functionality
607 |
608 | By following these steps, you will have a secure, maintainable foundation for your single-organization multi-tenant system.
609 |
--------------------------------------------------------------------------------
/multi_org/authorization_strategy.md:
--------------------------------------------------------------------------------
1 | # Multi-Tenant Phoenix 1.8 Guide: Shared Schema, Scoped Auth, and Role-Based Authorization
2 |
3 | ## Overview of Multi-Tenancy and Shared Schema Approach
4 |
5 | Multi-tenancy means a single application instance serves multiple tenants (e.g. organizations or teams), isolating each tenant's data. In a shared schema approach, all tenants share the same database tables, distinguished by a tenant identifier (such as an organization_id foreign key on records). This approach simplifies migrations and code (versus maintaining separate schemas or databases per tenant) but requires vigilant scoping of queries to avoid data leakage between tenants. Phoenix 1.8's new Scopes feature is designed to help enforce that all database operations are properly scoped to the current tenant/user by default.
6 |
7 | In this guide, we will build a multi-tenant system using Phoenix 1.8 with a shared schema, covering these components:
8 |
9 | - **Tenants (Organizations)**: Companies or groups using the app. All data rows are tagged with an organization ID.
10 | - **Users**: Individuals who belong to multiple organizations simultaneously. Authentication is handled at the user level, with organization context determined after login.
11 | - **Roles**: Global roles (e.g. Admin, Manager, Member) that define what actions a user can perform. Roles are assigned to users in the context of each organization via a membership.
12 | - **Permissions**: The allowed actions for each role. Enforced via an authorization library (Bodyguard) in context of the current user + org.
13 |
14 | By the end, you will have a clear architecture for organizing tenants and users, configuring Phoenix authentication with multi-organization support, and enforcing role-based access control on top of Phoenix LiveView 1.0.
15 |
16 | ## System Architecture: Tenants, Users, Roles, Permissions
17 |
18 | **Tenants (Organizations)**: Each tenant is represented by an Organization record. An organization will have many users through memberships. We use a single organizations table for all tenants, with fields like name and a unique slug (for use in URLs or subdomains).
19 |
20 | **Users**: A user can belong to multiple organizations simultaneously. This is implemented through a join table (OrganizationMembership) rather than placing an organization_id directly on the users table. Users are stored in a shared users table with fields such as email, hashed_password, etc., as generated by phx.gen.auth.
21 |
22 | **Organization Memberships**: The core of our multi-organization approach is the organization_memberships join table connecting users to organizations. Each membership record includes:
23 |
24 | - user_id: References the user
25 | - organization_id: References the organization
26 | - role: The user's role within that specific organization
27 |
28 | This approach allows a user to have different roles in different organizations (e.g., admin in one org, member in another).
29 |
30 | **Roles**: Roles are defined globally (not created per tenant). For example, we might have roles like :admin, :manager, and :member that apply to all organizations. This means the set of roles is fixed application-wide, but each user can have different role assignments in different organizations via their membership records. Typical role semantics could be:
31 |
32 | - Admin: Full access within their organization (can manage org settings, manage users, etc.).
33 | - Manager: Limited management (e.g. can manage certain resources but not org-level settings).
34 | - Member: Regular user who can only access their own data or non-administrative features.
35 |
36 | **Permissions**: Permissions are the actions allowed or denied based on role. Rather than define a complex permission matrix per tenant, we implement permission checks in code (using Bodyguard policies) that consider the user's role within the current organization context. For example, an Admin user can access all records in their org, whereas a Member might only access records they own. These rules will be encoded in policy modules.
37 |
38 | **Data Isolation**: With a shared schema, every relevant table (domain-specific tables like projects, posts, etc.) includes an org_id foreign key referencing the organization. All queries will filter by org_id to fetch only data for the current tenant. Phoenix 1.8 scopes help pass the current org_id (and user) around so that context functions automatically enforce this isolation. This prevents the #1 OWASP vulnerability, broken access control, by ensuring queries/inserts/updates always stay within the proper tenant.
39 |
40 | Below is a high-level relationship summary:
41 |
42 | - Organization - has many Users through OrganizationMemberships
43 | - User - has many Organizations through OrganizationMemberships
44 | - OrganizationMembership - belongs to User and Organization, includes role field
45 | - Role - a global set of roles; each membership record includes a role value
46 |
47 | With the conceptual overview in place, let's move on to implementing the database schema and associations.
48 |
49 | ## Database Schema and Associations
50 |
51 | First, we set up the database tables for organizations, users, and organization memberships. We use Ecto migrations and schema definitions in our Phoenix project.
52 |
53 | ### Organizations Migration and Schema
54 |
55 | Create an organizations table with a primary key, name, slug, and any other fields your app needs (e.g., industry, inserted_at/updated_at timestamps). Ensure the slug or name is unique if you plan to use it in URLs or subdomains.
56 |
57 | ```elixir
58 | # priv/repo/migrations/XXXX_create_organizations.exs
59 |
60 | def change do
61 | create table(:organizations) do
62 | add :name, :string, null: false
63 | add :slug, :string, null: false
64 | add :active, :boolean, default: true
65 | timestamps()
66 | end
67 |
68 | create unique_index(:organizations, [:slug])
69 | end
70 | ```
71 |
72 | The corresponding Ecto schema:
73 |
74 | ```elixir
75 | # lib/catalyst/accounts/organization.ex
76 |
77 | defmodule Catalyst.Accounts.Organization do
78 | use Ecto.Schema
79 | import Ecto.Changeset
80 |
81 | @derive {Phoenix.Param, key: :slug}
82 |
83 | schema "organizations" do
84 | field :name, :string
85 | field :slug, :string
86 | field :active, :boolean, default: true
87 |
88 | many_to_many :users, Catalyst.Accounts.User, join_through: Catalyst.Accounts.OrganizationMembership
89 |
90 | timestamps()
91 | end
92 |
93 | def changeset(org, attrs) do
94 | org
95 | |> cast(attrs, [:name, :slug, :active])
96 | |> validate_required([:name, :slug])
97 | |> unique_constraint(:slug)
98 | end
99 | end
100 | ```
101 |
102 | Here, each organization is connected to users through a many-to-many relationship using the organization_memberships join table. We will use the slug for friendly URLs like /orgs/my-org/... and to look up the org in requests.
103 |
104 | ### Organization Memberships Migration and Schema
105 |
106 | We need to create a join table to manage the many-to-many relationship between users and organizations, including the role information:
107 |
108 | ```elixir
109 | # priv/repo/migrations/XXXX_create_organization_memberships.exs
110 |
111 | def change do
112 | create table(:organization_memberships) do
113 | add :user_id, references(:users, on_delete: :delete_all), null: false
114 | add :organization_id, references(:organizations, on_delete: :delete_all), null: false
115 | add :role, :string, null: false, default: "member"
116 | timestamps()
117 | end
118 |
119 | create unique_index(:organization_memberships, [:user_id, :organization_id])
120 | create index(:organization_memberships, [:organization_id])
121 | create index(:organization_memberships, [:user_id])
122 | end
123 | ```
124 |
125 | The corresponding Ecto schema:
126 |
127 | ```elixir
128 | # lib/catalyst/accounts/organization_membership.ex
129 |
130 | defmodule Catalyst.Accounts.OrganizationMembership do
131 | use Ecto.Schema
132 | import Ecto.Changeset
133 |
134 | @roles ~w(admin manager member)a
135 |
136 | schema "organization_memberships" do
137 | field :role, :string, default: "member"
138 |
139 | belongs_to :user, Catalyst.Accounts.User
140 | belongs_to :organization, Catalyst.Accounts.Organization
141 |
142 | timestamps()
143 | end
144 |
145 | def changeset(membership, attrs) do
146 | membership
147 | |> cast(attrs, [:role, :user_id, :organization_id])
148 | |> validate_required([:role, :user_id, :organization_id])
149 | |> validate_inclusion(:role, Enum.map(@roles, &Atom.to_string/1))
150 | |> unique_constraint([:user_id, :organization_id])
151 | end
152 | end
153 | ```
154 |
155 | ### Users Schema
156 |
157 | The users schema generated by mix phx.gen.auth needs to be updated to reflect the many-to-many relationship with organizations:
158 |
159 | ```elixir
160 | # lib/catalyst/accounts/user.ex
161 |
162 | defmodule Catalyst.Accounts.User do
163 | use Ecto.Schema
164 | import Ecto.Changeset
165 |
166 | schema "users" do
167 | field :email, :string
168 | field :hashed_password, :string
169 | field :confirmed_at, :utc_datetime
170 | # Virtual fields for password (from phx.gen.auth)
171 | field :password, :string, virtual: true
172 | field :current_password, :string, virtual: true
173 |
174 | many_to_many :organizations, Catalyst.Accounts.Organization, join_through: Catalyst.Accounts.OrganizationMembership
175 | has_many :organization_memberships, Catalyst.Accounts.OrganizationMembership
176 |
177 | timestamps()
178 | end
179 |
180 | # Registration changeset
181 | def registration_changeset(user, attrs) do
182 | user
183 | |> cast(attrs, [:email, :password])
184 | |> validate_email()
185 | |> validate_password()
186 | end
187 |
188 | # ... (phx.gen.auth typically also provides functions like validate_email, validate_password)
189 | end
190 | ```
191 |
192 | ### Roles Definition
193 |
194 | Since roles are global, we define them in the OrganizationMembership schema as shown above. We use an @roles module attribute to list the allowed roles, which we can reference throughout the application. For simplicity, we're using string values for roles, but you could also use Ecto.Enum if preferred.
195 |
196 | With our schemas in place, let's integrate Phoenix authentication and ensure it's tenant-aware.
197 |
198 | ## Authentication with phx.gen.auth for Multi-Organization Support
199 |
200 | Phoenix 1.8 provides the mix phx.gen.auth generator to scaffold out authentication (registration, login, password reset, etc.). When you run this generator, it will by default create an Accounts context, a User schema, and all the necessary routes and LiveViews/controllers for user authentication. Importantly, Phoenix 1.8's auth generator also sets up a default Scope for the user.
201 |
202 | To generate auth, run (if not already done):
203 |
204 | ```bash
205 | $ mix phx.gen.auth Accounts User users --live
206 | ```
207 |
208 | This creates files like lib/catalyst/accounts/user.ex, user_auth.ex, and related LiveViews or controllers for authentication. It will inject routes under the :browser pipeline for registration, login, etc.
209 |
210 | After running the generator, perform these modifications to make it multi-organization aware:
211 |
212 | - Add organization creation during user registration: When a new user signs up, they typically either:
213 | - Create their first organization (becoming an admin of that org)
214 | - Accept an invitation to join an existing organization
215 |
216 | For the first case (creating a new organization during registration), you would extend the registration form (in the generated user_registration_live.ex) to include organization name and slug fields. Then modify the registration action:
217 |
218 | ```elixir
219 | def handle_event("save", %{"user" => user_params, "organization" => org_params}, socket) do
220 | case Accounts.register_user_with_organization(user_params, org_params) do
221 | {:ok, user} ->
222 | # Handle successful registration...
223 | {:error, %Ecto.Changeset{} = changeset} ->
224 | # Handle errors...
225 | end
226 | end
227 | ```
228 |
229 | This means implementing a new Accounts function to handle user registration with organization creation:
230 |
231 | ```elixir
232 | def register_user_with_organization(user_attrs, org_attrs) do
233 | Repo.transaction(fn ->
234 | # Create user
235 | {:ok, user} = register_user(user_attrs)
236 |
237 | # Create organization
238 | {:ok, organization} = create_organization(org_attrs)
239 |
240 | # Create membership with admin role
241 | {:ok, _membership} = create_membership(%{
242 | user_id: user.id,
243 | organization_id: organization.id,
244 | role: "admin"
245 | })
246 |
247 | user
248 | end)
249 | end
250 | ```
251 |
252 | - Add organization selection after login: Since users can belong to multiple organizations, after login you'll need to:
253 |
254 | 1. Fetch all organizations the user belongs to
255 | 2. Either redirect to the last used organization, prompt for selection, or redirect to create a new organization if none exist
256 |
257 | This would be handled in the user_session_controller.ex or user_session_live.ex created by phx.gen.auth:
258 |
259 | ```elixir
260 | def create(conn, %{"user" => user_params}) do
261 | %{"email" => email, "password" => password} = user_params
262 |
263 | if user = Accounts.get_user_by_email_and_password(email, password) do
264 | conn = log_in_user(conn, user)
265 |
266 | # Fetch user's organizations
267 | organizations = Accounts.list_user_organizations(user)
268 |
269 | case organizations do
270 | [] ->
271 | # No organizations, redirect to create one
272 | redirect(conn, to: ~p"/organizations/new")
273 | [organization] ->
274 | # Only one organization, redirect directly
275 | redirect(conn, to: ~p"/orgs/#{organization.slug}/dashboard")
276 | _multiple ->
277 | # Multiple organizations, let user choose
278 | redirect(conn, to: ~p"/organizations")
279 | end
280 | else
281 | # Handle login failure...
282 | end
283 | end
284 | ```
285 |
286 | - Extend Scope for organization context: We'll need to modify the generated Scope struct to support the current organization and membership context, but that's covered in the next section.
287 |
288 | With these changes, our authentication system now supports users belonging to multiple organizations, with organization selection happening after successful login.
289 |
290 | ## Using Phoenix 1.8 Scopes for Tenant-Specific Context and Routing
291 |
292 | Phoenix 1.8 introduces Scopes as a first-class mechanism for multi-tenant data isolation and authorization. A scope is a simple struct that contains information about the current request context (like current user, and now, current organization). By passing this struct to all your context functions, you ensure those functions can filter data appropriately. The Phoenix generators automatically utilize the scope in generated code when a default scope is configured.
293 |
294 | ### Extending the Generated Scope Struct
295 |
296 | After running phx.gen.auth, you will have a scope module (e.g. lib/catalyst/accounts/scope.ex) similar to:
297 |
298 | ```elixir
299 | defmodule Catalyst.Accounts.Scope do
300 | alias Catalyst.Accounts.User
301 | defstruct user: nil
302 |
303 | def for_user(%User{} = user), do: %__MODULE__{user: user}
304 | def for_user(nil), do: nil
305 | end
306 | ```
307 |
308 | We need to include the organization and membership in this scope. We need to add both organization and membership fields to the struct and provide helpers to set them:
309 |
310 | ```elixir
311 | defmodule Catalyst.Accounts.Scope do
312 | alias Catalyst.Accounts.{User, Organization, OrganizationMembership}
313 | defstruct user: nil, organization: nil, membership: nil
314 |
315 | def for_user(%User{} = user) do
316 | %__MODULE__{user: user}
317 | end
318 | def for_user(nil), do: nil
319 |
320 | # Put an organization into an existing scope and find the associated membership
321 | def put_organization(%__MODULE__{user: user} = scope, %Organization{} = org) do
322 | membership = get_membership(user, org)
323 | %{scope | organization: org, membership: membership}
324 | end
325 |
326 | # Add a helper to directly set membership
327 | def put_membership(%__MODULE__{} = scope, %OrganizationMembership{} = membership) do
328 | %{scope | membership: membership}
329 | end
330 |
331 | # Find membership between user and organization
332 | defp get_membership(%User{id: user_id}, %Organization{id: org_id}) do
333 | Catalyst.Repo.get_by(OrganizationMembership, user_id: user_id, organization_id: org_id)
334 | end
335 | end
336 | ```
337 |
338 | Now the scope can carry the current user, their organization, and the specific membership that connects them (which includes the user's role in that organization). The for_user/1 function no longer sets an organization automatically since a user can belong to multiple organizations.
339 |
340 | ### Assigning Current Organization in the Router
341 |
342 | Phoenix 1.8's auth generator sets up a plug :fetch_current_scope_for_user in the browser pipeline that populates conn.assigns.current_scope with the user scope. We will add another plug to find the organization from the request and attach it to the scope. There are two common patterns for identifying the current org in requests:
343 |
344 | - Subdomain: e.g. tenant.catalyst.com → parse subdomain to find org.
345 | - Path segment: e.g. catalyst.com/orgs/:org_slug/... → parse URL param.
346 |
347 | For illustration, we'll use the path approach with an :org URL param (slug). Update your router pipeline and add an assign_org_to_scope plug:
348 |
349 | ```elixir
350 | # lib/catalyst_web/router.ex
351 |
352 | pipeline :browser do
353 | # ...
354 | plug :fetch_current_user # from phx.gen.auth (fetches current_user if any)
355 | plug :fetch_current_scope_for_user # from phx.gen.auth (assigns current_scope with user)
356 | plug :assign_org_to_scope # our custom plug
357 | end
358 | ```
359 |
360 | Define the plug in your CatalystWeb.UserAuth module (which already contains auth plugs):
361 |
362 | ```elixir
363 | # lib/catalyst_web/controllers/user_auth.ex
364 |
365 | def assign_org_to_scope(conn, _opts) do
366 | if slug = conn.params["org"] do
367 | current_scope = conn.assigns.current_scope
368 | case Catalyst.Accounts.get_organization_by_slug(slug) do
369 | %Catalyst.Accounts.Organization{} = org ->
370 | # Ensure user has membership in this organization
371 | if membership = Catalyst.Accounts.get_membership(current_scope.user, org) do
372 | assign(conn, :current_scope,
373 | Catalyst.Accounts.Scope.put_organization(current_scope, org))
374 | else
375 | conn
376 | |> put_flash(:error, "You don't have access to that organization")
377 | |> redirect(to: ~p"/organizations")
378 | |> halt()
379 | end
380 | _ ->
381 | conn
382 | |> put_flash(:error, "Organization not found")
383 | |> redirect(to: ~p"/organizations")
384 | |> halt()
385 | end
386 | else
387 | conn
388 | end
389 | end
390 | ```
391 |
392 | Here we look up the organization by the slug from the URL. If the organization exists, we verify the user has a membership in it. If both checks pass, we update the scope with both the organization and the user's membership in that organization. If either fails, we redirect with an error message. This ensures a user can only access organizations they are a member of.
393 |
394 | LiveView considerations: For LiveViews, the above plug runs only on the initial HTTP request to mount the LiveView. To ensure the scope (with org) is available on mounting and live navigation, Phoenix provides an on_mount hook in the generator. We need to add our own for org. For example, in user_auth.ex we can add:
395 |
396 | ```elixir
397 | def on_mount(:assign_org_to_scope, %{"org" => slug}, _session, socket) do
398 | current_scope = socket.assigns.current_scope
399 |
400 | case Catalyst.Accounts.get_organization_by_slug!(slug) do
401 | %Catalyst.Accounts.Organization{} = org ->
402 | # Ensure user has membership in this organization
403 | if membership = Catalyst.Accounts.get_membership(current_scope.user, org) do
404 | new_scope = current_scope
405 | |> Catalyst.Accounts.Scope.put_organization(org)
406 | |> Catalyst.Accounts.Scope.put_membership(membership)
407 |
408 | {:cont, Phoenix.Component.assign(socket, :current_scope, new_scope)}
409 | else
410 | {:halt, socket
411 | |> put_flash(:error, "You don't have access to that organization")
412 | |> redirect(to: ~p"/organizations")}
413 | end
414 | _ ->
415 | {:halt, socket
416 | |> put_flash(:error, "Organization not found")
417 | |> redirect(to: ~p"/organizations")}
418 | end
419 | end
420 |
421 | def on_mount(:assign_org_to_scope, _params, _session, socket) do
422 | {:cont, socket}
423 | end
424 | ```
425 |
426 | We will use this in our LiveView routing next. (Notice we used a bang version get_organization_by_slug! which will raise Ecto.NoResultsError if not found, automatically translating to a 404 if not caught.)
427 |
428 | ### Scoped Routes with Organization Prefix
429 |
430 | Now, define your application routes to include the organization context. Using Phoenix LiveView's live_session is a good way to ensure certain mounts have the necessary on_mount hooks. For example:
431 |
432 | ```elixir
433 | scope "/", CatalystWeb do
434 | pipe_through [:browser, :require_authenticated_user]
435 |
436 | live_session :org_app, on_mount: [
437 | {CatalystWeb.UserAuth, :ensure_authenticated},
438 | {CatalystWeb.UserAuth, :mount_current_scope},
439 | {CatalystWeb.UserAuth, :assign_org_to_scope}
440 | ] do
441 | live "/orgs/:org/dashboard", DashboardLive, :index
442 | live "/orgs/:org/projects", ProjectLive.Index, :index
443 | live "/orgs/:org/projects/new", ProjectLive.Form, :new
444 | live "/orgs/:org/projects/:id", ProjectLive.Show, :show
445 | # ... other org-scoped live routes
446 | end
447 | end
448 | ```
449 |
450 | In the above:
451 |
452 | - We nest routes under /orgs/:org/ where :org is the organization slug.
453 | - We require authentication and mount the current user scope (mount_current_scope hook provided by auth generator) and then our assign_org_to_scope on each LiveView in this session. This guarantees socket.assigns.current_scope has both user and org for all LiveViews under this route.
454 | - Controllers (if any) under this scope would also get the org via the plug in the pipeline.
455 |
456 | Now all incoming requests under /orgs/:org/... will have conn.assigns.current_scope containing the user, organization, and membership. Phoenix contexts can leverage this scope.
457 |
458 | ### Automatic Scope in Context Functions and Migrations
459 |
460 | Phoenix generators can use the scope to generate context functions that automatically filter by org. In config/config.exs, set up scope configurations. Since phx.gen.auth already set up a default :user scope, we'll augment with an :organization scope for resource generators:
461 |
462 | ```elixir
463 | # config/config.exs
464 |
465 | config :catalyst, :scopes,
466 | user: [
467 | default: true,
468 | module: Catalyst.Accounts.Scope,
469 | assign_key: :current_scope,
470 | access_path: [:user, :id] # identifies user by user.id
471 | ],
472 | organization: [
473 | module: Catalyst.Accounts.Scope,
474 | assign_key: :current_scope,
475 | access_path: [:organization, :id], # identifies org by org.id
476 | route_prefix: "/orgs/:org", # nest generated routes under this prefix
477 | schema_key: :organization_id,
478 | schema_type: :binary_id,
479 | schema_table: :organizations
480 | ]
481 | ```
482 |
483 | This configuration tells Phoenix's code generators how to incorporate the organization scope. For example, if you run mix phx.gen.live Projects Project projects name:string ... --scope organization, it will generate context functions like list_projects(scope) that automatically include where: p.organization_id == ^scope.organization.id in queries, migrations that add organization_id foreign key, and routes prefixed with /orgs/:org. The route_prefix with :org param ties into our router setup, and the access_path [:organization, :id] combined with route_prefix means the generator will use the org slug (since Phoenix.Param protocol on Organization can be set to use slug) for URL helpers and capturing that param.
484 |
485 | Example Context Function: If we had a Project schema with an organization_id field, a generated function might look like:
486 |
487 | ```elixir
488 | def list_projects(%Accounts.Scope{} = scope) do
489 | from(proj in Project,
490 | where: proj.organization_id == ^scope.organization.id)
491 | |> Repo.all()
492 | end
493 | ```
494 |
495 | All such functions require passing the current scope. You can obtain the scope in controllers as conn.assigns.current_scope and in LiveViews as @current_scope (assigned via our on_mount). This pattern ensures all data access is automatically tenant-filtered, aligning with Phoenix's goal of making secure data access the default.
496 |
497 | ### Context Associations and Preloading
498 |
499 | When working with the multi-organization approach, we need to be careful about preloading associations. Since a user can belong to multiple organizations, we need to ensure we're preloading the right memberships and organizations.
500 |
501 | For instance, when viewing a specific organization, we might want to preload all members:
502 |
503 | ```elixir
504 | def get_organization_with_members!(%Accounts.Scope{} = scope, id) do
505 | Repo.get_by!(Organization, id: id, id: scope.organization.id)
506 | |> Repo.preload([organization_memberships: [user: []]])
507 | end
508 | ```
509 |
510 | Similarly, when listing a user's organizations, we would:
511 |
512 | ```elixir
513 | def list_user_organizations(%User{} = user) do
514 | user = Repo.preload(user, :organizations)
515 | user.organizations
516 | end
517 | ```
518 |
519 | At this stage, we have a robust setup where:
520 |
521 | - Each request knows the current %Organization{}, %User{}, and %OrganizationMembership{} (all in current_scope).
522 | - All queries and resource routes are naturally scoped by org.
523 | - Users can belong to multiple organizations with different roles in each.
524 |
525 | Next, we will enforce authorization rules on top of this using Bodyguard, to manage what roles can do within the tenant.
526 |
527 | ## Role-Based Authorization with Bodyguard
528 |
529 | Authentication (identity verification) is in place, and scopes ensure tenants' data is isolated. Now we layer authorization: determining if a given user can perform a given action. We'll use the Bodyguard library, which provides a convenient way to define and check authorization policies.
530 |
531 | Bodyguard works by defining an authorize/3 callback in your context modules (or dedicated policy modules) that decides if a user (and optionally other params) can perform a certain action. We then call Bodyguard.permit/4 to enforce these rules at runtime.
532 |
533 | ### Defining Roles and Permissions
534 |
535 | We decided on global roles (admin, manager, member) that are assigned at the membership level. This means a user can be an admin in one organization but just a member in another. We'll enforce permissions such as:
536 |
537 | - Org-level actions (e.g. editing organization settings, inviting users) – only Admins (and maybe Managers) of that org can do these.
538 | - Resource actions (e.g. editing a project or post) – perhaps Admin or Manager can edit any within the org, whereas a Member can only edit ones they own.
539 |
540 | Let's codify some rules using Bodyguard. For our multi-organization approach, it's cleaner to implement the Bodyguard.Policy behaviour in dedicated policy modules rather than directly in the context. Here's an example for organization management:
541 |
542 | ```elixir
543 | defmodule Catalyst.Accounts.Policy do
544 | @behaviour Bodyguard.Policy
545 |
546 | alias Catalyst.Accounts.{User, Organization, OrganizationMembership, Scope}
547 | alias Catalyst.Repo
548 |
549 | # Only admins can update organization details
550 | def authorize(:update_organization, %User{} = user, %Organization{} = org) do
551 | case get_membership(user, org) do
552 | %OrganizationMembership{role: "admin"} -> :ok
553 | _ -> :error
554 | end
555 | end
556 |
557 | # Only admins can invite new users to their org
558 | def authorize(:invite_user, %User{} = user, %Organization{} = org) do
559 | case get_membership(user, org) do
560 | %OrganizationMembership{role: "admin"} -> :ok
561 | _ -> :error
562 | end
563 | end
564 |
565 | # Managers can view member list
566 | def authorize(:view_members, %User{} = user, %Organization{} = org) do
567 | case get_membership(user, org) do
568 | %OrganizationMembership{role: role} when role in ["admin", "manager"] -> :ok
569 | _ -> :error
570 | end
571 | end
572 |
573 | # Fallback for undefined rules
574 | def authorize(_action, _user, _params), do: :error
575 |
576 | # Helper to get membership
577 | defp get_membership(%User{id: user_id}, %Organization{id: org_id}) do
578 | Repo.get_by(OrganizationMembership, user_id: user_id, organization_id: org_id)
579 | end
580 | end
581 | ```
582 |
583 | In the above policy examples:
584 |
585 | - We check the user's role for the specific organization by looking up their membership.
586 | - We return :ok to permit or :error (or {:error, :reason}) to deny. Bodyguard will interpret :error as an unauthorized attempt by default.
587 |
588 | We use this policy module in our context:
589 |
590 | ```elixir
591 | defmodule Catalyst.Accounts do
592 | use Bodyguard.Policy, policy: Catalyst.Accounts.Policy
593 |
594 | # Context functions...
595 | end
596 | ```
597 |
598 | We can also define policies in other contexts. For example, suppose we have a Projects context for a project management feature:
599 |
600 | ```elixir
601 | defmodule Catalyst.Projects.Policy do
602 | @behaviour Bodyguard.Policy
603 |
604 | alias Catalyst.Accounts.{User, Organization, OrganizationMembership}
605 | alias Catalyst.Projects.Project
606 | alias Catalyst.Repo
607 |
608 | # Admin or Manager can delete any project in their org; Members can delete only their own
609 | def authorize(:delete_project, %User{} = user, %Project{} = project) do
610 | case get_membership(user, %Organization{id: project.organization_id}) do
611 | %OrganizationMembership{role: role} when role in ["admin", "manager"] -> :ok
612 | %OrganizationMembership{} when user.id == project.owner_id -> :ok
613 | _ -> :error
614 | end
615 | end
616 |
617 | # Only Admin can mark project as archived
618 | def authorize(:archive_project, %User{} = user, %Project{} = project) do
619 | case get_membership(user, %Organization{id: project.organization_id}) do
620 | %OrganizationMembership{role: "admin"} -> :ok
621 | _ -> :error
622 | end
623 | end
624 |
625 | def authorize(_action, _user, _params), do: :error
626 |
627 | # Helper to get membership
628 | defp get_membership(%User{id: user_id}, %Organization{id: org_id}) do
629 | Repo.get_by(OrganizationMembership, user_id: user_id, organization_id: org_id)
630 | end
631 | end
632 |
633 | defmodule Catalyst.Projects do
634 | use Bodyguard.Policy, policy: Catalyst.Projects.Policy
635 |
636 | # Context functions...
637 | end
638 | ```
639 |
640 | This illustrates a mix of role-based and ownership-based rules. In Bodyguard's philosophy, simple pattern matching or guard clauses can express most rules. The example above says:
641 |
642 | - To :delete_project, allow if the user is admin/manager of that org, or if the user is the project owner.
643 | - To :archive_project, only org admins can do it.
644 |
645 | Note how these policy functions explicitly look up the membership for the specific organization-user combination, reinforcing our multi-organization model. A user's permission for an action depends on their role in the organization that owns the resource.
646 |
647 | ### Enforcing Authorization in Controllers and LiveViews
648 |
649 | With policies defined, the next step is to actually enforce them when actions are attempted. Bodyguard provides the Bodyguard.permit/4 function to check authorization and return :ok or an error. There is also Bodyguard.permit!/4 which raises on unauthorized, and a convenience boolean permit?/4. Additionally, Bodyguard offers a plug for controllers and guidance for LiveView usage.
650 |
651 | In Controllers (if using non-LiveView): You might use the Bodyguard.Plug.Authorize in a pipeline or call Bodyguard.permit manually. For example, in a controller action:
652 |
653 | ```elixir
654 | def update(conn, %{"id" => org_id, "organization" => org_params}) do
655 | org = Accounts.get_organization!(conn.assigns.current_scope, org_id)
656 |
657 | # Authorize that current user can update this organization:
658 | with :ok <- Bodyguard.permit(Catalyst.Accounts, :update_organization, conn.assigns.current_scope.user, org),
659 | {:ok, %Organization{} = org} <- Accounts.update_organization(conn.assigns.current_scope, org, org_params) do
660 | redirect(conn, to: ~p"/orgs/#{org.slug}/settings")
661 | else
662 | {:error, :unauthorized} ->
663 | conn |> put_flash(:error, "You are not authorized to do that.") |> redirect(to: ~p"/organizations")
664 | {:error, %Ecto.Changeset{} = changeset} ->
665 | render(conn, :edit, changeset: changeset, organization: org)
666 | end
667 | end
668 | ```
669 |
670 | We pass Catalyst.Accounts as the module (since we configured it to use our policy module), the action atom, the current user, and the organization struct. If it's not :ok, we handle it appropriately.
671 |
672 | Alternatively, using the plug approach at the controller module level:
673 |
674 | ```elixir
675 | plug Bodyguard.Plug.Authorize,
676 | policy: Catalyst.Accounts,
677 | action: :update_organization,
678 | user: &__MODULE__.current_user/1,
679 | params: &__MODULE__.get_org_from_params/1,
680 | fallback: CatalystWeb.FallbackController
681 | when action in [:update]
682 | ```
683 |
684 | This example would call a get_org_from_params(conn) function that fetches the org, then Bodyguard will invoke the policy.
685 |
686 | In LiveViews: In LiveView, you typically perform authorization in the mount/3 or in event handlers (handle_event). For instance, in mount, if a user is not authorized to view the page, you can redirect away:
687 |
688 | ```elixir
689 | def mount(params, _session, socket) do
690 | scope = socket.assigns.current_scope
691 | project = Projects.get_project!(scope, params["id"])
692 |
693 | case Bodyguard.permit(Catalyst.Projects, :view_project, scope.user, project) do
694 | :ok ->
695 | {:ok, assign(socket, project: project)}
696 | {:error, _reason} ->
697 | {:halt, socket
698 | |> put_flash(:error, "You don't have permission to view this project")
699 | |> redirect(to: ~p"/orgs/#{scope.organization.slug}/projects")}
700 | end
701 | end
702 | ```
703 |
704 | For button actions or forms, in handle_event you can similarly check with Bodyguard.permit before proceeding:
705 |
706 | ```elixir
707 | def handle_event("delete", %{"id" => id}, socket) do
708 | scope = socket.assigns.current_scope
709 | project = Projects.get_project!(scope, id)
710 |
711 | case Bodyguard.permit(Catalyst.Projects, :delete_project, scope.user, project) do
712 | :ok ->
713 | {:ok, _} = Projects.delete_project(scope, project)
714 | {:noreply, socket
715 | |> put_flash(:info, "Project deleted successfully")
716 | |> push_navigate(to: ~p"/orgs/#{scope.organization.slug}/projects")}
717 | _ ->
718 | {:noreply, socket
719 | |> put_flash(:error, "You don't have permission to delete this project")}
720 | end
721 | end
722 | ```
723 |
724 | Because we have the current scope (with user, organization, and membership) readily available in LiveViews (thanks to on_mount hooks), we can always retrieve this context for authorization checks.
725 |
726 | ### Using Bodyguard Schema for Query Filtering (Optional)
727 |
728 | Bodyguard also provides Bodyguard.Schema for defining query scopes (similar to Phoenix scopes, but at the Ecto level). For example, you could implement c:Bodyguard.Schema.scope/3 on the Project schema to return only projects a given user should see based on role. This could be useful if you had more complex per-user filtering on top of tenant (e.g., an admin can see all within org, a member only their own records).
729 |
730 | For example:
731 |
732 | ```elixir
733 | defmodule Catalyst.Projects.Project do
734 | use Ecto.Schema
735 | use Bodyguard.Schema
736 |
737 | # ... schema definition ...
738 |
739 | def scope(query, %User{} = user, _opts) do
740 | org_id = opts[:organization_id]
741 | membership = Catalyst.Accounts.get_membership(user, %Organization{id: org_id})
742 |
743 | case membership do
744 | %{role: role} when role in ["admin", "manager"] ->
745 | # Admins and managers see all projects in the org
746 | query
747 | %{role: "member"} ->
748 | # Members only see their own projects or public ones
749 | from p in query,
750 | where: p.owner_id == ^user.id or p.public == true
751 | _ ->
752 | # No membership or unknown role - see nothing
753 | from p in query, where: false
754 | end
755 | end
756 | end
757 | ```
758 |
759 | However, with our Phoenix Scope approach, this level of filtering can also be handled in the context functions, making the Bodyguard.Schema approach optional.
760 |
761 | In summary, Bodyguard gives us a flexible way to enforce that even within a tenant's data, certain users can or cannot perform specific actions based on their role within that specific organization. We have set up the basic roles and added checks in the appropriate places (controller actions or LiveView events). Next, let's consider how the UI and LiveView components tie it all together, including using Phoenix LiveView 1.0 syntax like to_form for forms.
762 |
763 | ## LiveView 1.0 Integration and UI Implementation
764 |
765 | Modern Phoenix (1.7 and 1.8) encourages building interactive UI with LiveView and function components. Our multi-tenant system will have LiveViews for organization settings, project management, user management, and organization switching. Here we discuss a few integration points:
766 |
767 | - Using the current_scope in LiveView assigns to filter and display data
768 | - Building forms using LiveView 1.0's to_form/2 and the new component-based form API
769 | - Adding UI elements that respect authorization based on the user's role in the current organization
770 |
771 | ### Mounting with Scope
772 |
773 | As shown, we ensure every LiveView relevant to tenant data is wrapped in live_session with :mount_current_user and :assign_org_to_scope. That means in any LiveView module, we can safely use socket.assigns.current_scope which contains user, organization, and membership. For convenience, you might also assign these separately:
774 |
775 | ```elixir
776 | def mount(_params, _session, socket) do
777 | socket = socket
778 | |> assign(current_user: socket.assigns.current_scope.user)
779 | |> assign(current_org: socket.assigns.current_scope.organization)
780 | |> assign(current_membership: socket.assigns.current_scope.membership)
781 |
782 | # Rest of mount logic...
783 | {:ok, socket}
784 | end
785 | ```
786 |
787 | Now @current_user, @current_org, and @current_membership can be used in the templates directly (for example, to display the org name in a header, or conditionally render admin links if @current_membership.role == "admin").
788 |
789 | ### Organization Switching
790 |
791 | Since users can belong to multiple organizations, we need to implement a way for them to switch between organizations. This could be a dropdown in the header or a separate page:
792 |
793 | ```elixir
794 | # Organization selector component
795 | def organization_selector(assigns) do
796 | ~H"""
797 | <.dropdown id="org-switcher">
798 | <:trigger>
799 |
895 | ```
896 |
897 | Here .form is a function component that expects an @form assign (our to_form output). Each .input component uses the form field, and Phoenix will handle binding and validations. The changeset's errors will be automatically displayed by <.input> if the component is set up to do so (the default ones from Phoenix include error handling).
898 |
899 | ### Conditional UI by Role
900 |
901 | With @current_membership.role available, your templates can conditionally show admin-only links or buttons. For instance, in a team members list LiveView, you might show an "Invite User" button only for organization admins:
902 |
903 | ```heex
904 |
905 |
Team Members
906 |
907 | <%= if @current_membership.role == "admin" do %>
908 | <.button navigate={~p"/orgs/#{@current_org.slug}/invitations/new"}>
909 | Invite New Member
910 |
911 | <% end %>
912 |
913 |
914 |
915 |
916 | <%= for membership <- @memberships do %>
917 |
941 | ```
942 |
943 | Similarly, within a LiveView event handler, you might double-check authorization before performing an action:
944 |
945 | ```elixir
946 | def handle_event("remove", %{"id" => membership_id}, socket) do
947 | scope = socket.assigns.current_scope
948 | membership = Catalyst.Accounts.get_membership!(membership_id)
949 |
950 | case Bodyguard.permit(Catalyst.Accounts, :remove_member, scope.user, scope.organization) do
951 | :ok ->
952 | case Catalyst.Accounts.delete_membership(scope, membership) do
953 | {:ok, _} ->
954 | memberships = Catalyst.Accounts.list_organization_memberships(scope)
955 | {:noreply, socket
956 | |> put_flash(:info, "Member removed successfully")
957 | |> assign(memberships: memberships)}
958 | {:error, :last_admin} ->
959 | {:noreply, socket |> put_flash(:error, "Cannot remove the last admin")}
960 | end
961 | _ ->
962 | {:noreply, socket |> put_flash(:error, "You don't have permission to remove members")}
963 | end
964 | end
965 | ```
966 |
967 | Because we have the current scope (with user, organization, and membership) readily available in LiveViews (thanks to on_mount hooks), we can always retrieve this context for authorization checks.
968 |
969 | ### Navigation and Tenant Context
970 |
971 | Ensure all navigation links include the org scope. Use route helpers or the new ~p sigil with the org in path. For example:
972 |
973 | ```heex
974 |
1011 | ```
1012 |
1013 | This keeps the user in the context of their organization and only shows navigation options appropriate for their role in the current organization.
1014 |
1015 | ## Development Phases Checklist
1016 |
1017 | Here's a checklist of each phase in implementing the multi-tenant system, from database setup to UI integration:
1018 |
1019 | 1. **Database Setup**:
1020 |
1021 | - Create migrations for organizations table with name, slug, etc.
1022 | - Create organization_memberships join table with user_id, organization_id, and role
1023 | - Ensure user schema does NOT have organization_id (no single-org constraint)
1024 |
1025 | 2. **Schema Definitions**:
1026 |
1027 | - Define Organization schema with many_to_many relationship to users
1028 | - Define OrganizationMembership schema with belongs_to relationships
1029 | - Update User schema with many_to_many relationship to organizations
1030 | - Define roles as a constant list (e.g., @roles ~w(admin manager member)a)
1031 |
1032 | 3. **Generate Authentication**:
1033 |
1034 | - Run mix phx.gen.auth Accounts User users --live to scaffold authentication
1035 | - Follow generator instructions to migrate and integrate
1036 | - This gives you user context, schema, and basic sessions management
1037 |
1038 | 4. **Integrate Organization into Auth**:
1039 |
1040 | - Modify registration flow to handle organization creation or selection
1041 | - Extend registration to let new users create their first organization
1042 | - Implement organization invitation system for adding users to existing orgs
1043 | - Adjust login flow to handle multiple organizations per user
1044 |
1045 | 5. **Configure Phoenix Scopes**:
1046 |
1047 | - Extend the generated Accounts.Scope to include organization and membership
1048 | - Add helpers like put_organization/2 and get_membership/2
1049 | - Ensure scope includes access to user's role via membership
1050 | - Update config/config.exs with organization scope configuration
1051 |
1052 | 6. **Router and Plugs**:
1053 |
1054 | - Add assign_org_to_scope plug to browser pipeline
1055 | - Create on_mount callback for LiveViews to handle organization context
1056 | - Define routes nested under /orgs/:org/... with proper live_session setup
1057 | - Add organization switching functionality
1058 |
1059 | 7. **Context Functions with Scope**:
1060 |
1061 | - Refactor or generate context functions to require a scope argument
1062 | - Ensure all queries filter by organization_id using scope.organization.id
1063 | - Add membership management functions (create, update, delete)
1064 | - Implement safeguards like "last admin" protection
1065 |
1066 | 8. **Authorization (Bodyguard) Setup**:
1067 |
1068 | - Add Bodyguard to your project and define policy modules
1069 | - Implement authorization rules that check membership roles
1070 | - Create separate policy modules for different contexts (accounts, projects, etc.)
1071 | - Ensure policies account for multi-org (checking role in specific org)
1072 |
1073 | 9. **Enforce Authorization in Code**:
1074 |
1075 | - Add Bodyguard.permit checks in controllers and LiveViews
1076 | - Implement proper error handling for unauthorized actions
1077 | - Add role-based query filtering where appropriate
1078 | - Ensure all operations that modify data check authorization first
1079 |
1080 | 10. **LiveView Forms and Components**:
1081 |
1082 | - Use to_form/1 for form handling in LiveViews
1083 | - Implement organization management forms (create, edit, invite users)
1084 | - Create an organization switcher component for the header
1085 | - Add appropriate feedback for actions and errors
1086 |
1087 | 11. **Testing**:
1088 |
1089 | - Write tests for multi-tenant data isolation
1090 | - Test authorization rules for different roles
1091 | - Test membership management and organization switching
1092 | - Create fixtures and helpers for organization testing
1093 |
1094 | 12. **UI/UX Polishing**:
1095 | - Add navigation elements for organization switching
1096 | - Display current organization name in the layout
1097 | - Conditionally display UI elements based on user's role
1098 | - Implement organization onboarding flow and invitation handling
1099 |
1100 | By following these steps, you will have a comprehensive multi-tenant Phoenix application that properly supports users belonging to multiple organizations with different roles in each. Phoenix 1.8's scopes feature works in tandem with explicit authorization checks to provide a secure, maintainable foundation for your multi-tenant system.
1101 |
1102 | ## References
1103 |
1104 | - [Phoenix Scopes Documentation](https://hexdocs.pm/phoenix/1.8.0-rc.0/scopes.html)
1105 | - [Phoenix Authentication Generator](https://hexdocs.pm/phoenix/1.8.0-rc.0/Mix.Tasks.Phx.Gen.Auth.html)
1106 | - [Bodyguard GitHub Repository](https://github.com/schrockwell/bodyguard)
1107 |
--------------------------------------------------------------------------------