Tenant Isolation
Wristband enforces tenant isolation across both its entity model and authentication flows.
In multi-tenant applications, enforcing clear boundaries between tenants is critical. In Wristband, all data associated with a tenant is logically separated from other tenants, and operations within one tenant are sandboxed to prevent unintended side effects on other tenants. In the following sections, we'll dive deeper into how Wristband's entity model and authentication flows are designed to support tenant isolation.
Entity Model and Data Scoping
Tenants are first-class entities within Wristband's model. When you create an application in Wristband, one of the first things you'll need to do is create a tenant under that application. Once you've created a tenant, you can then start provisioning other entities associated with that tenant. Entities created under one tenant are logically isolated from those belonging to other tenants. Therefore, entities can be created freely for each tenant without worrying about cross-tenant conflicts. For example, two distinct users can exist with the same email address as long as they belong to different tenants.
Figure 1. Model showing users with the same email address co-existing in different tenants.
However, attempting to create two users with identical email addresses under the same tenant and identity provider will fail, as a user's email address must be unique within a single tenant and identity provider.
Figure 2. Two users with duplicate emails can't exist under the same tenant and IdP.
One important caveat is that you can have two users with the same email address under a single tenant if they belong to different IdPs. This is because users are scoped by both the identity provider and the tenant.
Figure 3. Two users can exist under the same tenant with duplicate emails if they belong to different IdPs.
In addition to users, the following entities can also be created under a tenant:
- Identity Providers (IdPs): IdPs are services that authenticate users and issue identity information to other applications or services. Identity providers associated with tenants are typically enterprise IdPs (such as Okta or Microsoft Entra), which are used to facilitate SSO.
- Roles: Roles are groups of permissions that can be assigned to users or clients to grant them privileges within your application. In Wristband, each tenant can define their own set of roles.
- Machine-To-Machine Clients: Machine-to-machine clients can be created for tenants to provide them with programmatic access to your application's APIs.
Authentication and Session Isolation
Tenant isolation has a significant impact on user authentication. In a multi-tenant application, a global login page is no longer sufficient, as each tenant may require a distinct login experience. Additionally, because users can share the same login identifiers (e.g., email addresses) across tenants, the login process must include a tenant identifier to accurately locate the user attempting to authenticate.
To handle these requirements, Wristband provides dedicated login pages for each tenant. Users initiate the login flow by navigating to their tenant’s login page, which is accessible via a globally unique vanity domain. After submitting their credentials, Wristband authenticates the user against the set of users associated with that specific tenant.
Figure 4. Illustration showing how each tenant has its own login page for authenticating its users.
Since users may not always know or remember which tenants they belong to, Wristband also offers an application login flow that helps users identify and navigate to their associated tenant login pages. The application login page is accessed using your application's vanity domain. When a user lands on the application login page, the screen that will be presented depends on the tenant discovery strategy that is enabled. The complete list of tenant discovery strategies that Wristband supports is:
- Email Resolution: Users provide their email address, and an email will be sent containing a link or a one-time password (OTP), depending on the email verification configuration. After the link is clicked or the OTP is entered, the user will be taken to a page showing all the tenants they are associated with. The user can then navigate to their tenant login page by selecting a tenant from the list. As a shortcut, if the user is associated with only a single tenant, they will be automatically redirected to that tenant's login page without needing to complete the email verification step.
- Tenant Domain Name Resolution: Users provide their tenant's unique domain name and are then redirected to their tenant's login page.
To improve the UX of the application login flow, Wristband can also be configured to remember the tenants that a user has logged in to. If 'Remember tenants' is enabled, when a user lands on the application login page, they will first be shown a list of all the tenants they have successfully logged into. The user can then select a tenant from the list to navigate directly to that tenant's login page, eliminating the need to go through the tenant discovery process.
Figure 5. Illustration showing the application login page with 'Remember tenants' enabled.
After a user successfully authenticates, Wristband creates a session cookie to persist their authenticated state. To maintain tenant isolation, these cookies are scoped to each tenant’s vanity domain, ensuring that sessions from different tenants don’t interfere with one another. As a result, a user can be logged in to multiple tenants simultaneously from the same device. This is especially useful when a single person belongs to multiple tenants and wants to switch between them seamlessly without needing to re-authenticate.
Figure 6. Illustration showing how Wristband auth session cookies are associated with tenant vanity domains, allowing for users to be simultaneously logged in to multiple tenants.
Updated about 19 hours ago