Role-Based Access Control

Descope allows you to assign roles and permissions to the application's end user. Users with Descope admin privileges can define roles and permissions in the Descope console or using our Management SDKs. Permissions and roles are represented as strings in Descope. Your application must do the interpretation and enforcement of the roles and permissions.

Creating Roles and Permissions

In the Descope console under "Authorization", within the RBAC tab, you can create and manage your project-level roles and permissions.

Clicking the + Permission Button allows you to create a new permission. You can also click the three dots to the right of the permission to delete the permission or change its description.

Clicking the + Role Button allows you to create a new role, with associated permissions. You can also click the three dots to the right of the role to delete the role, change its description, or change its associated permissions.

Configuring User's Roles

Each user that is created in your application can be assigned roles and permissions. The user can have more than one role and will include the role's associated permissions.

Roles and permissions can be assigned manually in the console in the users table, assigned programatically using the management SDK, or can be mapped from a SAML SSO provider.

Tenants and Roles

Roles can be created and assigned on a Tenant and/or Project level. This flexibility allows you to implement different access control strategies based on your application's needs.

Project-Level Roles

Project-level roles are available to all users across all tenants in your project. These roles are useful for defining global permissions that should be consistent throughout your application.

Tenant-Level Roles

Tenant-level roles are specific to individual tenants and can be used to implement tenant-specific access control policies. To create a tenant-level role:

Select a tenant from the Tenants Page of the Descope Console
Select the Authorization tab on the left
Define the roles and permissions

If you are using tenants for user management, the same user can be assigned:

The same role across different tenants
Different roles for different tenants
A combination of project-level and tenant-level roles

This multi-tenant role management capability enables you to:

Implement tenant-specific access control policies
Maintain consistent permissions across tenants when needed
Provide different levels of access to the same user in different tenant contexts

JWT Example

After successful end-user authentication, the roles and permissions are delivered to your application as part of the JWT token. Below is a sample JWT token that contains roles and permissions with a user logged into a tenant.

{
  "amr": [
    "email"
  ],
  "drn": "DS",
  "exp": 1692304651,
  "iat": 1692304051,
  "iss": "P2RFvFexVaxxNFK6rhP0ePtaGfTK",
  "sub": "U2RG6grrbT3REKYqk5yC4SjkMqzA",
  "tenants": {
    "T2U7vUH1NPy4JzWHruoOVIGyzYlu": {
      "permissions": [
        "AppSecEngineer",
        "Marketing",
        "Support"
      ],
      "roles": [
        "Engineering",
        "Product Manager"
      ]
    },
    "T2U7vVBqyZv6HdGtGLdnkgCbNxrC": {
      "permissions": [
        "AppSecEngineer",
        "Support"
      ],
      "roles": [
        "Support"
      ]
    }
  }
}

Validating Roles and Permissions

For examples of how to validate roles and permissions using the backend SDK, refer to our Session Validation articles.

Was this helpful?

On this page