Multi-tenancy

The concepts of tenants and users form the bedrock of Descope's structure. This optimizes the development of business-to-business (B2B) authentication and user management processes to meet your multi-tenant requirements, including organization-specific settings, enterprise onboarding, and more.

Tenants

Tenants represent organizations or businesses that use your application. They serve as a way to group and manage users, permissions, and various other aspects of a business within your application.

Identification

Tenants are identified by name and ID, which can be chosen by admin or auto-generated by Descope.

Creation

Methods to create tenants include:

• Manual: Use the Descope UI to manually create a tenant by filling in the organization's details. This is a preferred method for controlled access, especially before sales discussions.
• Automated: With Descope's robust APIs and SDK tools, developers can automate tenant creation and management, integrating it with backend services.

Controls and Settings

The tenant structure allows Descope to support a variety of controls and settings including:

• Multi-tenant Assignment: Each project can have multiple tenants and end-users can be assigned to none or multiple.
• Domains: Automatically map users to a tenant based on the domain in their email
• Invites: Admins can send out email invites to prospective users.
• SAML SSO and Automatic Provisioning: Streamline login processes by integrating Single Sign-On (SSO) with Identity Providers (IdPs) or setting up approved authentication methods for creating users on the spot.
• SCIM Provisioning: Descope leverages System for Cross-domain Identity Management for dynamic user configuration with an Identity Provider.
• Customized authentication methods: Specify which methods can be used for authentication (eg. Magic Link, OTP, Passkeys, and more).
• Custom metadata: Store organizational details like name, description, or other unique attributes on the Organization object.

Users

Users are individuals within these organizations who interact with your application. Each user is part of a tenant, and their actions within the application can be regulated based on the permissions associated with their tenant. Descope also allows users to be added to multiple tenants with different roles assigned per tenant.

Identification

Users are identified with a unique ID, assigned at creation. Additional attributes exist such as name, phone number, and email. A login ID parameter is used in SDK and API calls to identify a user and can be an email, phone number, or username. Descope also handles user merging if a matching verified email is used during sign up.

Creation

Users can be created via:

• Invite: Admins can send out email invites from the Descope UI, SDK, or API.
• Automatic Provisioning: Users can be created on the fly during the authentication process, such as when signing up via SSO.
• Manual Provisioning: Admins can manually add users within the Descope dashboard.

Roles and Permissions

Descope provides a structured permissions and roles system, allowing for granular access control.

• Permissions are specific actions or operations that a user is allowed to perform.
• Roles are a collection of permissions that can be assigned to a user. For example, an 'Admin' role might include permissions to create, modify, and delete other users.

By grouping permissions into roles, Descope makes it easier to manage and assign access rights, ensuring that users have only the permissions they need to do their jobs.

To create, edit, and assign roles and permissions, use:

• Descope UI: The graphical interface allows for intuitive modification of roles and permissions.
• SDK: Developers can use the provided Software Development Kit to programmatically adjust roles and permissions.

Roles and Permissions can be assigned to users immediately or users can register without being tied to a tenant or organization. Later, once they're onboarded as customers, they can be linked to the appropriate organization.

Custom Attributes

Apart from the standard attributes, Descope allows for the addition of custom attributes to user profiles, giving more flexibility in capturing user-specific data.

Deletion

Descope allows tenant deletion using the Console UI, API, and SDK. In addition, upon tenant deletion there is an option to cascade delete all users and access keys associated with the tenant.

Important Notes

• User Entity at Project Level: In Descope's structure, the user entity is considered at the project level. This means that each user is associated with a project and can interact with various tenants within that project.
• Multiple Tenants per User: A unique aspect of Descope is that it allows a single user to be associated with multiple tenants. This multi-tenancy feature is essential for businesses that operate in a B2B (business-to-business) environment, enabling users to have different roles and permissions across various tenants.
• Roles per Tenant: Each tenant can assign specific roles to users. Roles are essentially collections of permissions that dictate what actions a user can perform within a tenant. This allows for granular control over user access and actions.
• JWT (JSON Web Token) and User Information: Descope utilizes JWTs to store relevant user information, including their roles and permissions across different tenants. This token is crucial for authenticating and authorizing user actions within the application.
• App Responsibility in Data and Action Limitation: The application using Descope's system is responsible for limiting user data and actions based on the information contained in the JWT. This ensures that users only access data and perform actions that their roles and permissions allow.
• Tenant Assignment Process: Users can be assigned to tenants through various methods, including manual assignment via the Descope UI, through automated processes using Descope's APIs and SDK, or via invitation by tenant admins.
• Custom Attributes for Flexibility: Descope allows for the addition of custom attributes to user profiles, which provides additional flexibility in managing user data specific to an organization's needs.