Skip to main content

Set Up and Manage Multi-Tenancy with Zitadel Dashboard

info

This is an optional feature that allows you to create multiple tenants (organizations) within a single Zitadel instance. Each tenant can have its own users, projects, agents, and settings, enabling you to manage different environments or clients separately. It is not a requirement for the Istari Digital Platform, but it is a useful feature for organizations that need to manage multiple clients or environments.

1. Create a New Tenant (Organization)​

  • Access the Console: Log in to the Zitadel Console as a super admin.
  • Create New Organization: Click on the organization dropdown and select "New Organization." Only super admins can perform this action.

MultiTenancy - Access the Console

MultiTenancy - Create New Organization

  • Assign Organization Manager: Assign yourself or another designated admin as the manager for the new organization.

MultiTenancy - Assign Organization Manager

  • Set Custom Domain (Optional): Provide a custom domain for the tenant (e.g., engineer.example.com) for domain-specific access.

MultiTenancy - Set Custom Domain (Optional)

2. Add Users to Tenant​

  • Navigate to Users: Go to Users in the organization’s menu.
  • Add New User: Click on "+ New" to add a user to the tenant, specifying the necessary roles or permissions for each new user.

MultiTenancy - Add Users to Tenant

3. Set Up Single Sign-On (SSO)​

  • Enable External Identity Providers (IDPs): Under Settings > Identity Providers, add identity providers like Google.

MultiTenancy - Set Up Single Sign-On (SSO)

4. Customize Branding for Tenants​

  • Configure Branding: Under Organization Settings > Branding, customize login pages and themes to match each tenant’s branding.

MultiTenancy - Customize Branding for Tenants

5. Allow Project Access for Other Organizations​

  • Create Project Grant: Go to the default organization. In the Projects section, select a project, and create a grant for the target organization.

MultiTenancy - Create Project Grant

  • Assign Roles for Grant: Choose roles (e.g., agent or admin) for the recipient organization.

MultiTenancy - Assign Roles for Grant

  • The recipient can view the project under "Granted Projects" without modifying its core settings.

MultiTenancy - Granted Projects

Note: (important!)​

  • After creating a new organization and adding users to it, the service user responsible for generating the "FILE_SERVICE_ZITADEL_USER_MANAGER_SECRET" must be assigned as the organization’s Owner (org_OWNER) in Zitadel for each newly created organization. This ensures the service user has the necessary permissions for managing the organization.

MultiTenancy - Granted Projects

(Optional) Configure a dedicated object store for individual tenants​

You can choose to use a non-default object store (only AWS S3 and Azure Blob Storage are supported today) for a tenant. You would do that using nested environment variables, with the NAME field being required and other values not specified will inherit the corresponding values from the default storage configuration.

info

The Istari application will need to be restarted for these changes to take effect.

Please see the Object Store & Credentials documentation for general instructions on the setup of this additional object store.

AWS S3​

Here is an example where we define an additional S3 object store with the label acme_s3 and assign it as the object store to be used for assets created by users in the acme tenant (organization in Zitadel):

# Set the "acme" tenant object store.
# Resources created by members of tenant name "acme" will be stored on the "acme_s3" object store.
FILE_SERVICE_TENANTS__ACME__OBJECT_STORE = "acme_s3"
# Configure the "acme_s3" object store to use the s3 bucket "acme-istari-bucket".
FILE_SERVICE_OBJECT_STORES__ACME_S3__NAME = "acme-istari-bucket"
FILE_SERVICE_OBJECT_STORES__ACME_S3__REGION = "us-west-2"
FILE_SERVICE_OBJECT_STORES__ACME_S3__ACCESS_KEY = "AKIAIOSFODNN7EXAMPLE"
FILE_SERVICE_OBJECT_STORES__ACME_S3__SECRET_KEY = "NOTAREALSECRET123"
FILE_SERVICE_OBJECT_STORES__ACME_S3__ENDPOINT_URL = "https://s3.us-west-2.amazonaws.com"

Azure Blob Storage​

Here is an example where we have a tenant (organization in Zitadel) named acme that is configured to use the object store configured with the label ACME_BLOB_STORAGE and the settings that configure that object store for a Azure Blob Storage container named acme-istari-container in the Azure Storage account named acme with a different key ID (Azure Storage account name) and secret (Azure Storage account access key) than the default object store:

# Set the "acme" tenant object store.
# Resources created by members of tenant name "acme" will be stored on the "acme_blob_storage" object store.
FILE_SERVICE_TENANTS__ACME__OBJECT_STORE = "acme_blob_storage"
# Configure the "acme_blob_storage" object store to use the azure blob storage container "acme-istari-bucket"
FILE_SERVICE_OBJECT_STORES__ACME_BLOB_STORAGE__SCHEME = "wasbs"
FILE_SERVICE_OBJECT_STORES__ACME_BLOB_STORAGE__NAME = "acme-istari-container"
FILE_SERVICE_OBJECT_STORES__ACME_BLOB_STORAGE__ACCESS_KEY = "acme"
FILE_SERVICE_OBJECT_STORES__ACME_BLOB_STORAGE__SECRET_KEY = "QVpVUklURS1JTlNFQ1VSRS10ZXN0LWFjY291bnQta2V5Cg=="
FILE_SERVICE_OBJECT_STORES__ACME_BLOB_STORAGE__ENDPOINT_URL = "https://acme.blob.core.windows.net"

Note on Agents​

When using multiple tenants, agents inherit their tenant assignment from the user who created the Istari Agent API token used to authenticate them. Agents can only process jobs created by users within their assigned tenant.

For detailed information on configuring agents with multiple tenants, see Agent Multi-Tenancy.