Business to Business (B2B)

This section of Descope's documentation will focus on Descope's business-to-business (B2B) use case for your applications. This page, in particular, will cover the bedrock of Descope's B2B structure: multi-tenancy.

Multi-tenancy

The concepts of tenants and users form the baseline for implementing a business-to-business (B2B) use case with Descope. Descope Tenants allows you to add 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. Descope projects can have multiple tenants, and the end-users can be assigned to either the project or can belong to one or many tenants.

Identification

Tenants are identified by their assigned name or ID when referencing them via the Descope API or SDKs. You can change the name of tenants at any time, but the ID can only be configured when the tenant is first created; if the user doesn't define the ID, Descope automatically generates an ID for the tenant.

Creation

Methods to create tenants include:

• Automated: With Descope's flows or robust APIs and SDKs, developers can automate tenant creation and management, integrating it with backend services.
• Manual: Use the Descope console to manually create a tenant by filling in the organization's details.

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, one, or multiple.
• Domains: Automatically map users to a tenant based on their email domain.
• Invites: Admins can send out email invites to prospective users.
• SSO and Automatic Provisioning: Allow authentication via Single Sign-On (SSO) with external Identity Providers (IdPs) and, optionally, just-in-time user provisioning.
• SCIM Provisioning: Enable System for Cross-domain Identity Management (SCIM) for dynamic user creation with an external Identity Provider.
• Custom Attributes: 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 such as name, phone number, and email exist. A login ID parameter, which can be an email, phone number, or username, is used in SDK and API calls to identify a user. Descope also handles user merging if a matching verified email is used during sign-up.

Creation

Users can be created via:

• Automatic Provisioning: Users can be created on the fly during the authentication process, such as when signing up via any authentication method or even just in-time provisioning via SSO.
• Invite: Admins can send email invites from the Descope UI, SDK, or API.
• Manual Provisioning: Admins can add users via the Descope console, API, or SDK.

Custom Attributes

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

Roles and Permissions

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

• Permissions are specific actions or operations a user can 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 managing and assigning access rights easier, 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 intuitive modification of roles and permissions.
• SDK: Developers can programmatically adjust roles and permissions using the provided Software Development Kit.

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

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 users are associated with a project and can interact with various tenants.
• Multiple Tenants per User: Descope allows a single user to be associated with multiple tenants. This multi-tenancy feature is essential for businesses operating 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 permissions collections that dictate a user' actions 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 limits user data and actions based on the information 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, automated processes using Descope's APIs and SDK, or invitations by tenant admins.
• Custom Attributes for Flexibility: Descope allows custom attributes to be added to user profiles, which provides additional flexibility in managing user data specific to an organization's needs.