Widgets

Descope Widgets are embeddable components designed to facilitate the delegation of operations to your application's users. These widgets can be utilized in both B2B and B2C contexts, allowing your users to perform various tenant, user management, and project level operations from within the application itself.

This may include management tasks intended for delegation to tenant administrators within a tenant-based framework or other self-service widgets tailored to user needs. Widgets are only able to be used with our client side SDKs.

Descope UI

Navigating to the widget page lets you preview the widgets that are available:

• You can click on the widgets to preview them and all of their functionalities.
• To work with widgets you will first have to click on "Sync" and upgrade your frontend SDK. This update may affect your flows' screens, as it uses the same components. We advise validating they work as designed.

Inside preview mode you can see how the widget will look like on the client side, including actions and light/dark mode:

SDKs

You can use the below SDKs to implement widgets in your app. Read more about each widget here.

Prerequisites: Management Widgets

In order for your customer to use the management widgets they must:

• Be logged into a session
• Have a role with the "User Admin" permission for the specific tenant (you can use the built-in "Tenant Admin" role)

Customization

You can customize the Widget Component by passing in the following props. These customizations can be applied to any of the available widgets:

• theme: theme can be "light", "dark" or "os", which auto selects a theme based on the OS theme. Default is "light"
• styleId: style Id can be the id of the style you wish to run your widget with
• debug: debug can be set to true to enable debug mode

For example, this is how you would customize the User Management Widget:

import { UserManagement } from '@descope/react-sdk';
...
  <UserManagement
    widgetId="user-management-widget"
    tenant="tenant-id"
    theme="dark"
    styleId="my-style-id"
    debug="true"
  />

Available Widgets

User Management Widget

If you would like to allow admins to manage users from within your application, you can use this widget. This widget not only presents user data, but also enables the execution of various tasks by the customer, including:

• Create a new user
• Edit an existing user
• Activate / disable an existing user
• Reset an existing user's password
• Remove an existing user's passkey
• Delete an existing user

Examples

import { UserManagement } from '@descope/react-sdk';
...
  <UserManagement
    widgetId="user-management-widget"
    tenant="tenant-id"
  />

Widget Permissions

When creating a custom attribute in the Users Tab, widget permissions are optional to set:

When provided, viewing and editing the attribute values will be restricted to users with the specified permission in their roles.

Role Management Widget

If you would like to manage roles from within your application, you can use this widget. This widget not only presents information about existing roles but also enables the execution of various tasks by the customer, including:

• Create a new role
• Change an existing role's fields
• Delete an existing role

Notes

• The Editable field is determined by the user's access to the role - meaning that project-level roles are not editable by tenant level users.
• You need to pre-define the permissions that the user can use, which are not editable in the widget.

Examples

import { RoleManagement } from '@descope/react-sdk';
...
  <RoleManagement
    widgetId="role-management-widget"
    tenant="tenant-id"
  />

Access Key Management Widget

If you would like to manage Access Keys from within your application, you can use this widget. This widget not only presents information about existing access keys but also enables the execution of various tasks, including:

• Create a new access key
• Activate / deactivate an existing access key
• Delete an existing access key

Examples

import { AccessKeyManagement } from '@descope/react-sdk';
...
  <AccessKeyManagement
    widgetId="access-key-management-widget"
    tenant="tenant-id"
  />

Audit Widget

Some customers need an audit trail to monitor their users and check who performed a specific action. Embedding the audit table widget on your site automates the process of exposing that audit trail to your customers. The widget includes all tenant authentication events and custom audit events you might need to create for your customers.

Examples

import { AuditManagement } from '@descope/react-sdk';
...
  <AuditManagement
    widgetId="access-key-management-widget"
    tenant="tenant-id"
  />

Create Audit Events

The tenant authentication events are displayed in the widget by default. At some point in your customer's lifecycle, you will need to add more and more events to support your product's transparency. With Descope, you can create audit events using the management api. Here is a quick example in Node.JS of how you can create an audit event and for it to be reflected in the widget:

await descopeClient.management.audit.createEvent({
  action: 'user.updated',
  type: 'info', // info/warn/error
  actorId: 'UXXX',
  tenantId: 'tenant-id',
  data: {
    some: 'data',
  },
});

User Profile Widget

In most modern applications, the end users tend to have different preferences and settings, such as a profile picture and personal and professional information. It is expected to let your user customize their profile and experience, and that might also include their authentication methods that you should enable your users to use. The widget brings this experience to your users by embedding this component in your application. The widget enables your end users to:

• Update user profile picture
• Update user personal information
• Update authentication methods
• Logout

Examples

import { UserProfile } from '@descope/react-sdk';
...
  <UserProfile
    widgetId="user-profile-widget"
    theme={theme} // light / dark / os (auto detect)
    onLogout={() => {
      // add here you own logout callback
      window.location.href = '/login';
    }}
  />

Applications Portal Widget

When federating customer identities, we can delight users by presenting them all the applications that they are allowed to access. The Applications Portal Widget, is used to present the available applications to the end users. The widget allows the end users to click and access the applications listed.

Examples

import { ApplicationsPortal } from '@descope/react-sdk';
 
<ApplicationsPortal
	widgetId="applications-portal-widget"
	theme="light" // light / dark / os (auto detect)
/>