Descope Widgets

Introduction

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:

Descope widgets in console.

  • You can click on the widgets to preview them and all of their functionalities.
  • To work with widgets you will require 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, indluding actions and light/dark mode:

Descope widgets in preview action.

Descope widgets in preview dark mode.

Prerequisites

Management Widgets

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

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

Implementation

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
  • Note: Custom fields will also appear in the table.

Examples

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

<script setup>
import { UserManagement } from '@descope/vue-sdk';
</script>
import { UserManagement } from '@descope/nextjs-sdk';
...
  <UserManagement
    widgetId="user-management-widget"
    tenant="tenant-id"
  />
<!doctype html>
<html>
  <head>
  </head>
  <body>
  // Change the package version replacing the x.x.x.
  // Release versions can be found here: https://www.npmjs.com/package/@descope/user-management-widget
    <script src="https://static.descope.com/npm/@descope/user-management-widget@x.x.x/dist/index.js"></script>

    <descope-user-management-widget
      tenant="tenant-id"
      project-id="project-id"
      widget-id="user-management-widget"
    ></descope-user-management-widget>
  </body>
</html>

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

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

<script setup>
import { RoleManagement } from '@descope/vue-sdk';
</script>
import { RoleManagement } from '@descope/nextjs-sdk';
...
  <RoleManagement
    widgetId="role-management-widget"
    tenant="tenant-id"
  />
<!doctype html>
<html>
  <head>
  </head>
  <body>
    // Change the package version replacing the x.x.x.
    // Release versions can be found here: https://www.npmjs.com/package/@descope/role-management-widget
    <script src="https://static.descope.com/npm/@descope/role-management-widget@x.x.x/dist/index.js"></script>

    <descope-role-management-widget
      tenant="tenant-id"
      project-id="project-id"
      widget-id="role-management-widget"
    ></descope-role-management-widget>
  </body>
</html>

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 exising access key

Examples

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

<script setup>
import { AccessKeyManagement } from '@descope/vue-sdk';
</script>
import { AccessKeyManagement } from '@descope/nextjs-sdk';
...
  <AccessKeyManagement
    widgetId="access-key-management-widget"
    tenant="tenant-id"
  />
<!doctype html>
<html>
  <head>
  </head>
  <body>
    // Change the package version replacing the x.x.x.
    // Release versions can be found here: https://www.npmjs.com/package/@descope/access-key-management-widget
    <script src="https://static.descope.com/npm/@descope/access-key-management-widget@x.x.x/dist/index.js"></script>

    <descope-access-key-management-widget
      tenant="tenant-id"
      project-id="project-id"
      widget-id="access-key-management-widget"
    ></descope-access-key-management-widget>
  </body>
</html>

User Access Key Management Widget

If you would like to expose Access Keys to your tenant users from within your application, you can use this widget. This widget not only presents information about user-associated access keys but also enables the execution of various tasks by the user, including:

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

Notes

  • Users will see only their own access keys, for the tenant they are logged into.

Examples

Descope user access key management widget.
ReactAngularVue.jsNext.jsHTML 
import { UserAccessKeyManagement } from '@descope/react-sdk';
...
  <UserAccessKeyManagement
    widgetId="user-access-key-management-widget"
    tenant="tenant-id"
  />
<user-access-key-management tenant="tenant-id" widgetId="user-access-key-management-widget" />
<template>
	<UserAccessKeyManagement tenant="tenant-id" widget-id="user-access-key-management-widget" />
</template>

<script setup>
import { UserAccessKeyManagement } from '@descope/vue-sdk';
</script>
import { UserAccessKeyManagement } from '@descope/nextjs-sdk';
...
  <UserAccessKeyManagement
    widgetId="user-access-key-management-widget"
    tenant="tenant-id"
  />
<!doctype html>
<html>
  <head>
  </head>
  <body>
    // Change the package version replacing the x.x.x.
    // Release versions can be found here: https://www.npmjs.com/package/@descope/access-key-management-widget
    <script src="https://static.descope.com/npm/@descope/access-key-management-widget@x.x.xdist/index.js"></script>

    <descope-user-access-key-management-widget
      tenant="tenant-id"
      project-id="project-id"
      widget-id="user-access-key-management-widget"
    ></descope-user-access-key-management-widget>
  </body>
</html>

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

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

<script setup>
import { AuditManagement } from '@descope/vue-sdk';
</script>
import { AuditManagement } from '@descope/nextjs-sdk';
...
  <AuditManagement
    widgetId="audit-management-widget"
    tenant="tenant-id"
  />
<!doctype html>
<html>
  <head>
  </head>
  <body>
  // Change the package version replacing the x.x.x.
  // Release versions can be found here: https://www.npmjs.com/package/@descope/audit-management-widget
  <script src="https://static.descope.com/npm/@descope/audit-management-widget@x.x.x/dist/index.js"></script>
    <descope-audit-management-widget
      tenant="tenant-id"
      project-id="project-id"
      widget-id="audit-management-widget"
  ></descope-audit-management-widget>
  </body>
</html>

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

Descope user profile widget.
ReactAngularVue.jsNext.jsHTML 
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';
    }}
  />
<user-profile
  widgetId="user-profile-widget"
  theme={theme} // light / dark / os (auto detect)
  (logout)="<your_logout_function>"
/>
<template>
<UserProfile
	widget-id="user-profile-widget"
	theme={theme} // light / dark / os (auto detect)
    @logout="onLogout"
/>
</template>

<script setup>
import { UserProfile } from '@descope/vue-sdk';

const onLogout = () => (window.location.href = '/login');
</script>
import { UserProfile } from '@descope/nextjs-sdk';

<UserProfile
	widgetId="user-profile-widget"
	theme={theme} // light / dark / os (auto detect)
  onLogout={() => {
      // add here you own logout callback
      window.location.href = '/login';
  }}
/>
<!doctype html>
<html>
  <head>
  </head>
  <body>
    // Change the package version replacing the x.x.x.
    // Release versions can be found here: https://www.npmjs.com/package/@descope/user-profile-widget
    <script src="https://static.descope.com/npm/@descope/user-profile-widget@0.0.17/dist/index.js" />

    <descope-user-profile-widget
      project-id="{projectId}"
      widget-id="user-profile-widget"
      theme="{theme}" // light / dark / os (auto detect)
    />

    <script>
      function onLogout(error) {
        window.location.reload();
      }
      const descopeWidgetEle = document.getElementsByTagName('descope-user-profile-widget')[0];
      descopeWidgetEle.logout = onLogout;
    </script>
  </body>
</html>