Installation
Prerequisites
A Django project set up and running.
django-tenants
installed and configured. If you haven’t done this yet, refer to the django-tenants documentation for guidance.
Installing django-tenant-users
To install django-tenant-users
, use your favorite package manager:
pip install django-tenant-users
Configuring Your Django Project
Modifying the Tenant Model
Your existing TenantModel
, which should be configured in settings.py
, needs to
be updated to inherit from our TenantBase
instead of TenantMixin
.
Here’s an example of how to modify your existing TenantModel:
from tenant_users.tenants.models import TenantBase
class Company(TenantBase):
name = models.CharField(max_length=100)
description = models.TextField(max_length=200)
Creating the User Model
If you haven’t already defined a custom user model in your project, you’ll need to
create one and have it inherit from UserProfile
. See the
Django User Model documentation for more information.
In the example below, we define a TenantUser
model within the users
application:
from tenant_users.tenants.models import UserProfile
class TenantUser(UserProfile):
name = models.CharField(max_length=100)
Updating Settings
Add the tenant_users
apps to SHARED_APPS
and TENANT_APPS
.
SHARED_APPS = [
...
"django.contrib.auth",
"django.contrib.contenttypes",
"tenant_users.permissions",
"tenant_users.tenants",
"companies",
"users",
...
]
TENANT_APPS = [
...
"django.contrib.auth",
"django.contrib.contenttypes",
"tenant_users.permissions",
...
]
Important
Ensure the app containing your TenantBase
(companies
) and TenantUser
(users
), are only in the SHARED_APPS
list.
User Authentication
Switch to the custom authentication backend:
AUTHENTICATION_BACKENDS = (
"tenant_users.permissions.backend.UserBackend",
)
Tenant Domain
When provisioning new tenants, we need to know what domain to when provisioning new tenants.
TENANT_USERS_DOMAIN = "domain.com"
Custom Auth User Model
Finally, ensure that you define or update the AUTH_USER_MODEL
to point to the model
inherting TenantUser
.
AUTH_USER_MODEL = "users.TenantUser"
Note
Ensure that settings.TENANT_MODEL
is set correctly from your django-tenant
installation.
Optional Settings
Setting up Cross Domain Cookies:
To allow single sign-on across tenants:
SESSION_COOKIE_DOMAIN = ".domain.com"
Warning
Ensure you understand the implications of using SESSION_COOKIE_DOMAIN
.
Note
If using Django admin, consider admin multisite
. You should ensure the
configuration is correct to avoid unauthorized model access.
Provision Public Tenant
When working with django-tenants, it’s essential to have a public tenant created using
migrate_schemas
. If you haven’t set up the public tenant during the django-tenants
installation, no problem. django-tenant-users
provides a
utils.create_public_tenant()
,
which takes care of this for you.
from tenant_users.tenants.utils import create_public_tenant
create_public_tenant(domain_url="public.domain.com", owner_email="admin@domain.com")
Fin!
Congratulations on successfully setting up django-tenant-users
! With the
installation complete, you’re now equipped to harness the power of global
authentication and authorization for your multi-tenancy Django projects.
As you move forward, we recommend diving into the following sections to gain a deeper
understanding and make the most of django-tenant-users
:
Using django-tenant-users: Explore how get started with the core functionalities.
Core Concepts: Enhance your understanding of the foundational principles behind
django-tenant-users
.
Happy coding!