节点的SDK望远镜
用于节点.js的 Descope SDK 为 Descope 用户管理和认证 API 提供方便访问 用于以 Node.js 写的后端。 你可以读更多关于 望远镜网站。 。 。 .
所需资源
SDK支持节点版本18及以上.
SDK使用运行时间的原生 fetch 而不是节点 HTTP 客户端,所以它也运行在
Cloudflare工人和其他边缘运行时间(工人要求 nodejs_compat 旗帜为 crypto编号 :Buffer) (中文(简体) ).
安装 SDK
以 :
npm i --save @descope/node-sdk
认证函数
设置
在使用下列认证功能之前,必须初始化 descopeClient 以使用所有内置的 SDK 函数.
你需要你的望远镜 Project ID 来创建它,你可以在 项目页面 在望远镜控制台.
import DescopeClient from '@descope/node-sdk';
const descopeClient = DescopeClient({ projectId: 'my-project-ID' });
一旦你创造了一个 descopeClient,您可以使用此功能来工作以下功能:
管理职能
设置
在使用下列管理函数之前,必须初始化 descopeClient。 。 。 .
如果您也想要使用管理功能, 您需要初始化您的新版本 descopeClient但这次是 ManagementKey 还有你 Project ID中创建管理密钥 望远镜控制台。 。 。 .
import DescopeClient from '@descope/node-sdk';
const descopeClient = DescopeClient({
projectId: 'my-project-ID',
managementKey: 'management-key',
});
然后,您可以用它来完成以下功能:
- 管理租户
- 管理家庭
- 管理用户
- 管理访问密钥
- 管理 SSO 设置
- 管理权限
- 管理角色
- 查询 SSO 组
- 管理流程
- 管理 JWTs
- 冒名顶替
- 嵌入式链接
- 审计
- 管理 FGA( 精细授权)
- 管理工程
- 管理 SSO 应用程序
- 管理密钥
- 管理探测器
- 管理引擎
如果你想运行我们的任何代码样本 并玩它们,检查我们 代码示例 节.
如果你正在进行端到端测试, 请检查 用于结束(e2e)测试和整合测试的 Utils 节。 您需要使用 descopeClient 您创建于 管理职能。 。 。 .
认证管理密钥
这个 authManagementKey 是一种替代 managementKey 提供一种在保持认证客户与管理客户分离的同时开展管理业务的方法.
密钥差异
- 目的: 使用
authManagementKey与认证有关的管理业务,同时managementKey用于一般管理业务 - 客户离职: 您可以有一个客户端用于管理操作, 另一个用于认证操作
- 相互排斥: 您不能通过两者
authManagementKey财务报告和审定财务报表managementKey一起 - 根据您的使用大小写选择一个
用法实例
使用认证管理键进行认证操作 :
import DescopeClient from '@descope/node-sdk';
const authClient = DescopeClient({
projectId: 'my-project-ID',
authManagementKey: 'auth-management-key',
});
// This client can be used for authentication-related management operations
不同操作的单独客户端 :
import DescopeClient from '@descope/node-sdk';
// Client for general management operations
const managementClient = DescopeClient({
projectId: 'my-project-ID',
managementKey: 'management-key',
});
// Client for authentication operations
const authClient = DescopeClient({
projectId: 'my-project-ID',
authManagementKey: 'auth-management-key',
});
// Use managementClient for user management, tenant management, etc.
// Use authClient for authentication-related operations
说明: 在 望远镜控制台,类似于您创建常规管理密钥的方式.
处理错误
每个 async 操作可能失败。 如果确实如此,将掌握有关反应对象发生的情况.
一个典型的错误处理案例可能看起来类似:
import DescopeClient, { SdkResponse } from '@descope/node-sdk';
const { DescopeErrors } = DescopeClient;
// ...
try {
const resp = await sdk.otp.signIn.email(loginId);
if (resp.error) {
switch (resp.error.errorCode) {
case DescopeErrors.userNotFound:
// Handle specifically
break;
default:
// Handle generally
// `resp.error` will contain `errorCode`, `errorDescription` and sometimes `errorMessage` to
// help understand what went wrong. See SdkResponse for more information.
}
}
} catch (e) {
// Handle technical error
}
检察官办公室认证
使用您喜欢的送出方法向用户发送一次性密码( OTP ) (电子邮件/短信/语音呼叫/WhatsApp) (中文(简体) ). 因此必须提供电子邮件地址或电话号码.
用户也可以 sign up, (中文(简体) ), sign in 或者说 sign up or in
// Every user must have a login ID. All other user information is optional
const loginId = '[email protected]';
const user = {
name: 'Desmond Copland',
phone: '212-555-1234',
email: loginId,
};
await descopeClient.otp.signUp['email'](loginId, user);
用户将使用所选的传送方法接收一个代码. 使用 :
const jwtResponse = await descopeClient.otp.verify['email'](loginId, 'code');
// jwtResponse.data.sessionJwt
// jwtResponse.data.refreshJwt
届会和刷新JWT应交回致电者,并在会中与每一项请求相通。 更多信息 会话验证
魔法链接
使用您首选的送出方法发送一个用户的魔法链接( S)电子邮件/短消息) (中文(简体) ). "魔法链接"会将用户重定向到需要校验其符号的页面. 这种重定向可以在代码中配置,也可以在全球范围配置 望远镜控制台
用户也可以 sign up, (中文(简体) ), sign in 或者说 sign up or in
// If configured globally, the redirect URI is optional. If provided however, it will be used
// instead of any global configuration
const URI = 'http://myapp.com/verify-magic-link';
await descopeClient.magicLink.signUpOrIn['email']('[email protected]', URI);
要校验一个魔法链接, 您的重定向页面必须调用符号上的验证功能 (t)参数(https://your-redirect-address.com/verify?t=<token>:
const jwtResponse = await descopeClient.magicLink.verify('token');
// jwtResponse.data.sessionJwt;
// jwtResponse.data.refreshJwt;
届会和刷新JWT应交回致电者,并在会中与每一项请求相通。 更多信息 会话验证
智能链接
使用 Cnitched Link API 可使用户通过点击链接签名 他们的电子邮件地址。 电子邮件将包括三个不同的链接, 而用户必须点击正确的一个, 以 2 位数字为基础 在启动认证进程时显示.
这种方法类似于 魔法链接 但主要有两种不同:
- 用户必须从三个中选择正确的链接, 而不是只有一个 单链接.
- 这支持交叉设备点击,意味着用户可以尝试在一个设备上登录, 类似计算机,同时点击另一个设备的链接,例如移动电话.
Chanted Link 将把用户重新定向到需要校验其符号的页面 . 这种重定向可以按照请求的代码配置,也可以在全球设置 望远镜控制台。 。 。 .
用户也可以 sign up, (中文(简体) ), sign in 或者说 sign up or in
// If configured globally, the redirect URI is optional. If provided however, it will be used
// instead of any global configuration.
const URI = 'http://myapp.com/verify-enchanted-link';
const enchantedLinkRes = await descopeClient.enchantedLink.signIn('[email protected]', URI);
enchantedLinkRes.data.linkId; // Should be displayed to the user so they can click the corresponding link in the email
enchantedLinkRes.data.pendingRef; // Used to poll for a valid session
发送链接后,您必须使用 pendingRef 从
上一个步骤。 只有在用户点击正确的链接后才会返回有效的会话 .
// Poll for a certain number of tries / time frame. You can control the polling interval and time frame
// with the optional WaitForSessionConfig
const jwtResponse = await descopeClient.enchantedLink.waitForSession(
enchantedLinkRes.data.pendingRef,
);
// jwtResponse.data.sessionJwt;
// jwtResponse.data.refreshJwt;
要验证一个被魔法化的链接, 您的重定向页面必须调用符号上的验证函数( Q)t)参数(https://your-redirect-address.com/verify?t=<token>) (中文(简体) ). 一旦该标志得到核实,会议投票将获得有效答复.
try {
await descopeClient.enchantedLink.verify('token');
// token is invalid
} catch (error) {
// token is valid
}
届会和刷新JWT应交回致电者,并在会中与每一项请求相通。 更多信息 会话验证
奥奥特
用户可以通过OAuth协议,使用他们的社交登录进行认证. 配置您的 OAuth 设置 望远镜控制台。要启动 OAuth 流量呼叫:
// Choose an oauth provider out of the supported providers
// If configured globally, the return URL is optional. If provided however, it will be used
// instead of any global configuration.
const urlRes = await descopeClient.oauth.start['google'](redirectUrl);
urlRes.data.url; // Redirect the user to the returned URL to start the OAuth redirect chain
用户将使用认证提供者进行认证,并将重定向回重定向的 URL,并附有一个附件 code HTTP URL 参数. 用它来验证用户:
const jwtResponse = await descopeClient.oauth.exchange('token');
// jwtResponse.data.sessionJwt;
// jwtResponse.data.refreshJwt;
届会和刷新JWT应交回致电者,并在会中与每一项请求相通。 更多信息 会话验证
证监会/证监会
用户可以使用 SAML 或 Single Sign On 认证给特定租户。 配置您的 SSO/ SAML 设置 望远镜控制台。要启动一个流量呼叫:
// If configured globally, the return URL is optional. If provided however, it will be used
// instead of any global configuration.
const redirectUrl = 'https://my-app.com/handle-saml';
const urlRes = await descopeClient.saml.start('tenant'); // Choose which tenant to log into. An email can also be provided here and the domain will be extracted from it
urlRes.data.url; // Redirect the user to the given returned URL to start the SSO/SAML redirect chain
用户将使用为租户配置的认证提供者进行认证,并将重新定向到重新定向的 URL,并附有一个附件 code HTTP URL 参数. 用它来验证用户:
const jwtResponse = await descopeClient.saml.exchange('token');
// jwtResponse.data.sessionJwt;
// jwtResponse.data.refreshJwt;
届会和刷新JWT应交回致电者,并在会中与每一项请求相通。 更多信息 会话验证
TOTP 认证
用户可以使用Google认证程序等认证程序进行认证.
签字就像你用其他认证方法一样 签到的回复
然后将包含一个 QR 代码 image 可以显示给用户以便使用
或用户可以输入 key 手动或单击
提供的联系 provisioningURL。 。 。 .
现有用户可以使用 update 函数.
// Every user must have a login ID. All other user information is optional
const loginId = '[email protected]';
const user = {
name: 'Desmond Copland',
phone: '212-555-1234',
email: loginId,
};
const totpRes = await descopeClient.totp.signUp(loginId, user);
// Use one of the provided options to have the user add their credentials to the authenticator
totpRes.data.provisioningURL;
totpRes.data.image;
totpRes.data.key;
有三种不同的方式允许用户在 它们的认证程序 - 要么点击提供 URL, 扫描 QR 图像或手动插入密钥。 之后,使用代码签名 应用程序生产.
const jwtResponse = await descopeClient.totp.verify(loginId, 'code');
// jwtResponse.data.sessionJwt;
// jwtResponse.data.refreshJwt;
届会和刷新JWT应交回致电者,并在会中与每一项请求相通。 更多信息 会话验证
删除 TOTP 种子
提供 loginId 到删除用户 TOTP 种子的函数.
const response = await descopeClient.management.user.removeTOTPSeed(loginId);
删除回收代码
为功能提供登录ID或用户ID来删除用户的所有恢复代码.
const response = await descopeClient.management.user.removeRecoveryCodes(loginIdOrUserId);
密码
用户也可以使用密码进行认证,不过建议 如果可能,更倾向于无密码认证方法。 签名需要 调用以提供符合所有配置要求的有效密码 联 合 国 密码认证方法 在望远镜控制台.
// Every user must have a loginId. All other user information is optional
const loginId = '[email protected]';
const password = 'qYlvi65KaX';
const user = {
name: 'Desmond Copeland',
email: loginId,
};
const jwtResponse = await descopeClient.password.signUp(loginId, password, user);
// jwtResponse.data.sessionJwt;
// jwtResponse.data.refreshJwt;
用户以后可以使用相同的登录ID和密码签名.
const jwtResponse = await descopeClient.password.signIn(loginId, password);
// jwtResponse.data.sessionJwt;
// jwtResponse.data.refreshJwt;
届会和刷新JWT应交回致电者,并在会中与每一项请求相通。 更多信息 会话验证
如果用户需要更新密码,有两种方法之一: 重置密码或替换密码
更改密码
注意: 发送重置只有在用户有有效的电子邮件地址时才会工作 。 否则密码重设提示无法发送 .
在那个 密码认证方法 在Descope控制台中,可以定义可以使用哪种替代认证方法来认证用户,以重置并更新他们的密码.
// Start the reset process by sending a password reset prompt. In this example we'll assume
// that magic link is configured as the reset method. The optional redirect URL is used in the
// same way as in regular magic link authentication.
const loginId = '[email protected]';
const redirectURL = 'https://myapp.com/password-reset';
const passwordResetResponse = await descopeClient.password.sendReset(loginId, redirectURL);
在此情况下,必须像其他任何魔法链接一样核实魔法链接(见 魔法链接部分 详情请查阅。 不过,在核实用户后,预期 允许他们提供新的密码,而不是旧密码。 由于用户现已获得认证,因此可以通过下列方式:
// The refresh token is required to make sure the user is authenticated.
await descopeClient.password.update(loginId, newPassword, token);
update() 当用户被认证并具有有效的会话时,总是可以调用.
或者,也可以用新的密码取代现有的有效密码.
// Replaces the user's current password with a new one
const jwtResponse = await descopeClient.password.replace(loginId, oldPassword, newPassword);
// jwtResponse.data.sessionJwt;
// jwtResponse.data.refreshJwt;
会话验证
您的客户端和服务器之间进行的每一个安全请求都需要验证 。 客户端发送 并使用下列方法之一加以验证:
// Validate the session. Will throw if expired
const authInfo = await descopeClient.validateSession('sessionToken');
// If validateSession throws an exception, you will need to refresh the session using
const refreshed = await descopeClient.refreshSession('refreshToken');
// Alternatively, you could combine the two and
// have the session validated and automatically refreshed when expired
const combined = await descopeClient.validateAndRefreshSession('sessionToken', 'refreshToken');
// Optional: Validate audience for backend-only flows
// Provide VerifyOptions with the expected audience(s)
const withAud = await descopeClient.validateSession('sessionToken', { audience: 'my-audience' });
const withAudArray = await descopeClient.validateSession('sessionToken', { audience: ['a', 'b'] });
// Audience is enforced for session JWTs only (including after refresh)
const refreshedWithAud = await descopeClient.refreshSession('refreshToken', { audience: 'api' });
const combinedWithAud = await descopeClient.validateAndRefreshSession(
'sessionToken',
'refreshToken',
{ audience: 'api' },
);
对于访问密钥,您也可以针对一个受众验证返回的会话:
const authInfo = await descopeClient.exchangeAccessKey('access_key', undefined, {
audience: 'api',
});
选择适合您需要的会话验证和刷新组合 . 刷新会话返回与用户首次登录/登录时返回的相同响应, 载有会话和刷新符号以及所有JWT索赔. 如果直接验证了会话符号, 请将响应中的会话符号返回客户端 .
通常,会通过HTTP头或克克来来来去来来来来来去来来来来来来去去去去去去去. 可根据您的执行情况推迟执行。 看我们的 实例 为了几个例子.
如果使用角色和权限, 在验证会话后立即验证它们 。 见 下一节 更多信息.
注意: 如果在 Descope 中启用了刷新符号旋转 - refreshSession 编号 : validateAndRefreshSession 将返回一个新的更新的代号,旧的将失效.
DPoP 发件人-约束托肯斯(RFC 9449)
当会话符号为 DPOP 时( 有 cnf.jkt 将请求的 DPOP 细节传递给
validateSession 或者说 validateAndRefreshSession当 dpop 选项,缺少或
无效证据被拒绝 。 没有它,一个 DPop 标记记录一个警告并被接受;下一个
主要版本将拒绝。 不受约束的符号不受影响.
validateAndRefreshSession 刷新后检查证据,所以被拒绝的证据不会撤销
刷新符号旋转 .
const [authorizationScheme, sessionToken] = (req.headers.authorization ?? '').split(' ');
const authInfo = await descopeClient.validateSession(sessionToken, {
dpop: {
proof: req.headers['dpop'] as string | undefined, // value of the DPoP header
method: req.method,
url: `${req.protocol}://${req.get('host')}${req.path}`, // must match the proof's htu
authorizationScheme, // "Bearer" or "DPoP"
},
});
代理服务器后面 :
url必须与证据相符htu(计相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 节点J可能会看到http当客户端使用时https快捷键trust proxy或者自己重建URL.
重放保护 : 证明:
jti被同一 SDK 案例在最后 120秒被拒绝. 该商店为内存( 最多10万个条目, 新证据被拒绝) ),所以没有检测到服务器实例之间的重放.
使用中间软件进行会话验证
或者,您可以创建一个简单的中间软件功能,在内部使用 validateSession 函数.
此中间软件将自动从请求中解析饼干 .
如果失败,它将以 401 Unauthorized。 。 。 .
const authMiddleware = async (req: Request, res: Response, next: NextFunction) => {
try {
const cookies = parseCookies(req);
const out = await clientAuth.auth.validateSession(
cookies[DescopeClient.SessionTokenCookieName],
cookies[DescopeClient.RefreshTokenCookieName],
);
if (out?.cookies) {
res.set('Set-Cookie', out.cookies);
}
next();
} catch (e) {
res.status(401).json({
error: 'Unauthorized!',
});
}
};
任务授权验证( L)
在使用角色权限时,必须验证用户是否具备所需的权限( L)
在确保会话有效后立即授权。 采取 AuthenticationInfo
收到的文件 会话验证,调用以下函数:
用于多种用途:
// You can validate specific permissions
const validTenantPermissions = descopeClient.validateTenantPermissions(authInfo, 'my-tenant-ID', [
'Permission to validate',
]);
if (!validTenantPermissions) {
// Deny access
}
// Or validate roles directly
const validTenantRoles = descopeClient.validateTenantRoles(authInfo, 'my-tenant-ID', [
'Role to validate',
]);
if (!validTenantRoles) {
// Deny access
}
// Or get the matched roles/permissions
const matchedTenantRoles = descopeClient.getMatchedTenantRoles(authInfo, 'my-tenant-ID', [
'Role to validate',
'Another role to validate',
]);
const matchedTenantPermissions = descopeClient.getMatchedTenantPermissions(
authInfo,
'my-tenant-ID',
['Permission to validate', 'Another permission to validate'],
);
不使用租户时:
// You can validate specific permissions
const validPermissions = descopeClient.validatePermissions(authInfo, ['Permission to validate']);
if (!validPermissions) {
// Deny access
}
// Or validate roles directly
const validRoles = descopeClient.validateRoles(authInfo, ['Role to validate']);
if (!validRoles) {
// Deny access
}
// Or get the matched roles/permissions
const matchedRoles = descopeClient.getMatchedRoles(authInfo, [
'Role to validate',
'Another role to validate',
]);
const matchedPermissions = descopeClient.getMatchedPermissions(authInfo, [
'Permission to validate',
'Another permission to validate',
]);
注销
您可以通过提供用户 refreshToken 参加那届会议.
调用此函数后, 您必须取消或删除您创建的任何 cookie .
await descopeClient.logout(refreshToken);
也可以从目前所签入的所有设备中签出用户. 通话 logoutAll 将
无效所有用户的刷新符号 。 调用此函数后, 您必须取消或删除您创建的任何 cookie .
await descopeClient.logoutAll(refreshToken);
管理职能
通常需要某种形式的管理或自动化。 这些可以执行 使用管理职能。 请注意,这些行动比较敏感,因为它们是行政性的 在自然界中,我们发现 请使用负责任的.
设置
要使用管理API,你需要一个 Management Key 与你的 Project ID。 。 。 .
在 望远镜控制台。 。 。 .
import DescopeClient from '@descope/node-sdk';
const descopeClient = DescopeClient({
projectId: 'my-project-ID',
managementKey: 'management-key',
});
管理租户
您可以创建、更新、删除或加载租户,以及读取和更新租户设置:
// The self provisioning domains or optional. If given they'll be used to associate
// Users logging in to this tenant
await descopeClient.management.tenant.create('My Tenant', ['domain.com'], {
customAttributeName: 'val',
});
// You can optionally set your own ID when creating a tenant
await descopeClient.management.tenant.createWithId('my-custom-id', 'My Tenant', ['domain.com'], {
customAttributeName: 'val',
});
// Update will override all fields as is. Use carefully.
await descopeClient.management.tenant.update(
'my-custom-id',
'My Tenant',
['domain.com', 'another-domain.com'],
{ customAttributeName: 'val' },
);
// Unlike update, patchTenant only changes the fields you provide - everything else
// (domains, customAttributes, enforceSSO, ...) is left untouched.
await descopeClient.management.tenant.patchTenant('my-custom-id', {
name: 'My Tenant',
disabled: true,
});
// Update the tenant's default roles by providing role names.
// These are project-level roles that will be automatically assigned to users in this tenant.
await descopeClient.management.tenant.updateDefaultRoles('my-custom-id', ['role1', 'role2']);
// Tenant deletion cannot be undone. Use carefully.
// Pass true to cascade value, in case you want to delete all users/keys associated only with this tenant
await descopeClient.management.tenant.delete('my-custom-id', false);
// Load tenant by id
const tenant = await descopeClient.management.tenant.load('my-custom-id');
// Load all tenants
const tenantsRes = await descopeClient.management.tenant.loadAll();
tenantsRes.data.forEach((tenant) => {
// do something
});
// Search all tenants according to various parameters
const searchRes = await descopeClient.management.tenant.searchAll(['id']);
searchRes.data.forEach((tenant) => {
// do something
});
// Load tenant settings by id
const tenantSettings = await descopeClient.management.tenant.getSettings('my-tenant-id');
// Update will override all fields as is. Use carefully.
await descopeClient.management.tenant.configureSettings('my-tenant-id', {
domains: ['domain1.com'],
selfProvisioningDomains: ['domain1.com'],
enabled: true,
refreshTokenExpiration: 12,
refreshTokenExpirationUnit: 'days',
sessionTokenExpiration: 10,
sessionTokenExpirationUnit: 'minutes',
enableInactivity: true,
JITDisabled: false,
inactivityTime: 10,
inactivityTimeUnit: 'minutes',
});
// Generate tenant admin self service link for SSO Suite (valid for 24 hours)
// ssoId can be provided for a specific sso configuration
// email can be provided to send the link to (email's templateId can be provided as well)
const res = await descopeClient.management.tenant.generateSSOConfigurationLink(
'my-tenant-id',
60 * 60 * 24,
);
console.log(res.adminSSOConfigurationLink);
// Optionally set an actor id, recorded as the audit actor for actions taken inside the SSO
// Suite (instead of the temporary user). It is used as-is for audit attribution and is not validated.
const resWithActor = await descopeClient.management.tenant.generateSSOConfigurationLink(
'my-tenant-id',
60 * 60 * 24,
undefined, // ssoId
undefined, // email
undefined, // templateId
'my-admin-actor-id', // actorId
);
console.log(resWithActor.adminSSOConfigurationLink);
管理家庭
您可以创建、更新、删除或搜索家庭,管理与其链接的用户,以及 冒充家庭依赖者(一个没有自己登录证书的影子用户):
// Create a family. The family ID is generated automatically.
const family = await descopeClient.management.family.create('My Family', {
customAttributeName: 'val',
});
// Create a family with a caller-supplied ID.
await descopeClient.management.family.createWithId('my-family-id', 'My Other Family');
// Update will override all provided fields as is. Omitted fields are left unchanged.
// customAttributes replaces all of the family's custom attributes, it is not merged.
await descopeClient.management.family.update(family.data.id, 'My Family', {
customAttributeName: 'val2',
});
// Family deletion cannot be undone. Use carefully.
await descopeClient.management.family.delete(family.data.id);
// Search families according to various parameters. Called with no options, returns all families.
const searchRes = await descopeClient.management.family.searchAll({ text: 'My Family' });
searchRes.data.forEach((f) => {
// do something
});
// Create a dependent (shadow profile) user in a family - a user with no login credentials of
// their own. When loginId is omitted it is derived from name; email/phone are never used as the
// login ID since they are not unique - a dependent may share them with their guardian.
const dependent = await descopeClient.management.family.createDependent(family.data.id, {
name: 'My Dependent',
});
// Dependent deletion cannot be undone. The family is inferred from the dependent. Regular
// (non-dependent) family members are removed via user.removeFamilies, not deleted.
await descopeClient.management.family.deleteDependent(dependent.data.userId);
// Add a user to one or more families. Each entry may also set the user's roles and family-scoped
// attributes for that family in the same call; omitting roleNames or familyScopedAttributes on a
// family the user already belongs to leaves them unchanged.
await descopeClient.management.user.addFamilies('user-login-id', [
{ familyId: family.data.id, roleNames: ['role1'] },
]);
// Remove a user from one or more families.
await descopeClient.management.user.removeFamilies('user-login-id', [family.data.id]);
// Impersonate a family dependent. The impersonator (by user ID or login ID) must be a member of
// the dependent's family and hold the family impersonate-dependents permission there.
const impersonateRes = await descopeClient.management.family.impersonateDependent(
'admin-user-id',
'dependent-login-id',
family.data.id, // optional - scopes the impersonated session to this family
);
console.log(impersonateRes.data.jwt);
// Stop impersonating a family dependent and return to the acting admin's own session.
const stopRes = await descopeClient.management.family.stopImpersonation(impersonateRes.data.jwt);
console.log(stopRes.data.jwt);
// Get and configure the project's family account settings. Omitted fields are left unchanged.
const settings = await descopeClient.management.family.getSettings();
await descopeClient.management.family.configureSettings({
enabled: true,
maxFamilyMembers: 5,
allowMultipleFamiliesUsers: false,
});
// Manage custom attribute definitions on the family entity itself.
await descopeClient.management.family.createCustomAttributes([{ name: 'plan', type: 1 }]);
const familyAttrs = await descopeClient.management.family.getCustomAttributes();
await descopeClient.management.family.deleteCustomAttributes(['plan']);
// Manage family-scoped user custom attribute definitions - user attributes whose values are held
// per family membership (AssociatedFamily.familyScopedAttributes) rather than on the user.
await descopeClient.management.user.createFamilyScopedCustomAttributes([
{ name: 'nickname', type: 1 },
]);
const familyScopedAttrs = await descopeClient.management.user.getFamilyScopedCustomAttributes();
await descopeClient.management.user.deleteFamilyScopedCustomAttributes(['nickname']);
管理密码
您可以读取和更新任何租户密码设置和政策 :
// Load tenant password settings by id
const passwordSettings = await descopeClient.management.password.getSettings('my-tenant-id');
// Update will override all fields as is. Use carefully.
await descopeClient.management.password.configureSettings('my-tenant-id', {
enabled: true,
minLength: 8,
expiration: true,
expirationWeeks: 4,
lock: true,
lockAttempts: 5,
reuse: true,
reuseAmount: 6,
lowercase: true,
uppercase: false,
number: true,
nonAlphaNumeric: false,
});
管理 SSO 应用程序
您可以创建、更新、删除或装入 SSO 应用程序:
// Create OIDC SSO application
await descopeClient.management.ssoApplication.createOidcApplication({
name: 'My OIDC app name',
loginPageUrl: 'http://dummy.com/login',
clientType: 'confidential', // 'confidential' or 'public'; if omitted, the account's default is used (see oidcSettings.clientType on load)
// Optional: send the app's back-channel logout URL a logout token when the user is force logged out
backChannelLogoutUrl: 'https://dummy.com/backchannel-logout',
notifyOnForceLogout: true,
});
// Create SAML SSO application
await descopeClient.management.ssoApplication.createSamlApplication({
name: 'My SAML app name',
loginPageUrl: 'http://dummy.com/login',
useMetadataInfo: true,
metadataUrl: 'http://dummy.com/metadata',
// Optional SAML Single Logout (SLO): the service provider can log the user out with a signed
// LogoutRequest, and it is sent one when a logout reaches the user's applications
singleLogoutEnabled: true,
singleLogoutPropagation: 'allApps', // 'none' (default) or 'allApps'
singleLogoutScope: 'session', // 'session' or 'allSessions'
notifyOnForceLogout: true, // also send it a LogoutRequest on a force logout (requires the 'soap' binding)
});
// Create WS-Fed SSO application
await descopeClient.management.ssoApplication.createWsFedApplication({
name: 'My WS-Fed app name',
loginPageUrl: 'http://dummy.com/login',
realm: 'urn:myapp:realm',
replyUrl: 'http://dummy.com/reply',
});
// Update OIDC SSO application.
// Update will override all fields as is. Use carefully.
await descopeClient.management.ssoApplication.updateOidcApplication({
id: 'my-app-id',
name: 'My OIDC app name',
loginPageUrl: 'http://dummy.com/login',
clientType: 'confidential', // pass the app's current client type
backChannelLogoutUrl: 'https://dummy.com/backchannel-logout', // an update without it clears it
});
// Update SAML SSO application.
// Update will override all fields as is. Use carefully.
await descopeClient.management.ssoApplication.updateSamlApplication({
id: 'my-app-id',
name: 'My SAML app name',
loginPageUrl: 'http://dummy.com/login',
enabled: true,
useMetadataInfo: false,
entityId: 'entity1234',
aceUrl: 'http://dummy.com/acs',
certificate: 'certificate',
});
// Update WS-Fed SSO application.
// Update will override all fields as is. Use carefully.
await descopeClient.management.ssoApplication.updateWsFedApplication({
id: 'my-app-id',
name: 'My WS-Fed app name',
loginPageUrl: 'http://dummy.com/login',
enabled: true,
realm: 'urn:myapp:realm',
replyUrl: 'http://dummy.com/reply',
});
// SSO application deletion cannot be undone. Use carefully.
await descopeClient.management.ssoApplication.delete('my-app-id');
// Load SSO application by id
const app = await descopeClient.management.ssoApplication.load('my-app-id');
// Load all SSO applications
const appsRes = await descopeClient.management.ssoApplication.loadAll();
appsRes.data.forEach((app) => {
// do something
});
管理用户
您可以创建、更新、删除或加载用户,以及按照过滤器进行搜索:
// A user must have a login ID, other fields are optional.
// Roles should be set directly if no tenants exist, otherwise set
// on a per-tenant basis.
await descopeClient.management.user.create('[email protected]', {
email: '[email protected]',
displayName: 'Desmond Copeland',
userTenants: [{ tenantId: 'tenant-ID1', roleNames: ['role-name1'] }],
});
// Alternatively, a user can be created and invited via an email / text message.
// Make sure to configure the invite URL in the Descope console prior to using this function,
// and that an email address / phone number is provided in the information.
await descopeClient.management.user.invite('[email protected]', {
email: '[email protected]',
displayName: 'Desmond Copeland',
userTenants: [{ tenantId: 'tenant-ID1', roleNames: ['role-name1'] }],
// You can override the project's User Invitation Redirect URL with this parameter
inviteUrl: '<invite-url>',
// You can inject custom data into the template.
// Note that you first need to configure custom template in Descope Console
// For example: configure {{options_k1}} in the custom template, and pass { k1: 'v1' } as templateOptions
templateOptions: { k1: 'v1', k2: 'v2' },
});
// You can invite batch of users via an email / text message.
// Make sure to configure the invite URL in the Descope console prior to using this function,
// and that an email address / phone number is provided in the information. You can also set
// a cleartext password or import a prehashed one from another service.
// Note: This function will send an invitation to each user in the `users` array. If you want to create users without sending invitations, use `createBatch` instead.
await descopeClient.management.user.inviteBatch(
[
{
loginId: '[email protected]',
email: '[email protected]',
phone: '+123456789123',
displayName: 'Desmond Copeland',
userTenants: [{ tenantId: 'tenant-ID1', roleNames: ['role-name1'] }],
hashedPassword: {
bcrypt: {
hash: '$2a$...',
},
},
},
],
'<invite_url>',
true,
false,
);
// Create a batch of users.
// This is useful when you want to create users programmatically without triggering the invitation flow.
// You can set a cleartext password or import a prehashed one from another service.
// Note: This function will NOT send an invitation to the created users. If invitations are required use `inviteBatch` instead.
await descopeClient.management.user.createBatch([
{
loginId: '[email protected]',
email: '[email protected]',
phone: '+123456789123',
displayName: 'Desmond Copeland',
userTenants: [{ tenantId: 'tenant-ID1', roleNames: ['role-name1'] }],
hashedPassword: {
bcrypt: {
hash: '$2a$...',
},
},
},
]);
// Update will override all fields as is, including family memberships: omitting
// familyAssociations removes the user from all of their families, and updating a dependent
// requires familyAssociations with the dependent's family. Use carefully, or use patch instead.
await descopeClient.management.user.update('[email protected]', {
email: '[email protected]',
displayName: 'Desmond Copeland',
userTenants: [{ tenantId: 'tenant-ID1', roleNames: ['role-name1'] }],
});
// Update explicit data for a user rather than overriding all fields
await descopeClient.management.user.updatePhone('[email protected]', '+18005551234', true);
await descopeClient.management.user.updateLoginId('[email protected]', '[email protected]');
await descopeClient.management.user.removeTenantRoles(
'[email protected]',
'tenant-ID1',
'role-name2',
);
// Update explicit user's data using patch (will override only provided fields)
const options: PatchUserOptions = { displayName: 'Desmond Copeland Jr.' };
await descopeClient.management.user.patch('[email protected]', options);
// User deletion cannot be undone. Use carefully.
await descopeClient.management.user.delete('[email protected]');
// Delete a batch of users. This requires Descope user IDs.
await descopeClient.management.user.deleteBatch(['<user-ID-1>', '<user-ID-2>']);
// Load specific user
const userRes = await descopeClient.management.user.load('[email protected]');
// If needed, users can be loaded using the user ID as well
const userRes = await descopeClient.management.user.loadByUserId('<user-ID>');
// loadUsers - load users by their user id, optionally you can decide if to return invalid users
const usersRes = await descopeClient.management.user.loadUsers(['<user-ID>']);
usersRes.data.forEach((user) => {
// do something
});
// Search all users, optionally according to tenant and/or role filter
// Results can be paginated using the limit and page parameters
// Additional filters: verifiedEmail, verifiedPhone, statuses, roles, tenantIds, etc.
const usersRes = await descopeClient.management.user.search({
tenantIds: ['tenant-ID'],
verifiedEmail: true, // optional: filter by verified email status
verifiedPhone: false, // optional: filter by verified phone status
});
console.log('Total users:', usersRes.data.total);
usersRes.data.users.forEach((user) => {
// do something
});
await descopeClient.management.user.logoutUser('my-custom-id');
await descopeClient.management.user.logoutUserByUserId('<user-ID>');
// Logout sessions by creation time. Each matching session is logged out on its next refresh or validation.
// At least one of `before` or `after` is required. `before` defaults to the server's current time; prefer
// omitting it over passing new Date(), since a `before` in the future is rejected. Optionally limit to
// specific session types with `sessionTypes`. The range stays active for a year. Deleting it stops it from
// logging out matching sessions it hasn't logged out yet; sessions already logged out stay logged out.
// The returned range is what the server stored, which may have a later `after` than requested.
// For example, log out sessions created in the last hour:
const rangeRes = await descopeClient.management.user.logoutSessionsCreatedBetween({
after: new Date(Date.now() - 3600 * 1000),
});
const rangesRes = await descopeClient.management.user.listLogoutSessionRanges();
await descopeClient.management.user.deleteLogoutSessionRange(rangeRes.data.id);
// Get users' authentication history
const userIds = ['user-id-1', 'user-id-2'];
const usersHistoryRes = await descopeClient.management.user.history(userIds);
usersHistoryRes.forEach((userHistory) => {
// do something
});
设置或过期用户密码
您可以为用户设置新的活动密码, 用户可以一起签名 . 您也可以设置一个临时密码, 用户在下次登录时将被迫更改 . 对于已经拥有活性密码的用户,可以过期其当前密码,有效要求他们在下一次登录时更改密码.
// Set a user's temporary password
await descopeClient.management.user.setTemporaryPassword('<login-ID>', '<some-password>');
// Set a user's password
await descopeClient.management.user.setActivePassword('<login-ID>', '<some-password>');
// Or alternatively, expire a user password
await descopeClient.management.user.expirePassword('<login-ID>');
管理工程
您可以更新工程名称和标签, 以及复制当前项目到一个新的项目 :
// Update will override all fields as is. Use carefully.
await descopeClient.management.project.updateName('new-project-name');
// Set will override all fields as is. Use carefully.
await descopeClient.management.project.updateTags(['tag1!', 'new']);
// Clone the current project to a new one
// Note that this action is supported only with a pro license or above.
const cloneRes = await descopeClient.management.project.clone('new-project-name');
使用公司管理密钥,您可以得到公司所有项目的列表:
const projects = await descopeClient.management.project.listProjects();
您可以通过导出快照来管理您的项目的设置和配置 :
// Exports the current state of the project
const exportRes = await descopeClient.management.project.exportSnapshot();
您也可以将先前导出快照导入同一项目或不同的项目 :
const validateReq = {
files: exportRes.data.files,
};
// Validate that an exported snapshot can be imported into the current project
const validateRes = await descopeClient.management.project.import(files);
if (!validateRes.ok) {
// validation failed, check failures and missingSecrets to fix this
}
// Import the previously exported snapshot into the current project
const importReq = {
files: exportRes.data.files,
};
await descopeClient.management.project.importSnapshot(files);
管理访问密钥
您可以创建、更新、删除或加载访问密钥,并根据过滤器进行搜索:
// An access key must have a name and expiration, other fields are optional.
// Roles should be set directly if no tenants exist, otherwise set
// on a per-tenant basis.
// If userId is supplied, then authorization will be ignored, and the access key will be bound to the user's authorization.
// If customClaims is supplied, then those claims will be present in the JWT returned by calls to ExchangeAccessKey.
// If description is supplied, then the access key will hold a descriptive text.
// If permittedIps is supplied, then the access key can only be used from that list of IP addresses or CIDR ranges.
await descopeClient.management.accessKey.create(
'key-name',
123456789, // expiration time
null,
[{ tenantId: 'tenant-ID1', roleNames: ['role-name1'] }],
undefined, // userId
undefined, // customClaims
undefined, // description
undefined, // permittedIps
{ attributeName: 'attributeValue' }, // customAttributes
);
// Load specific user
const accessKeyRes = await descopeClient.management.accessKey.load('key-id');
// Search all users, optionally according to tenant and/or role filter
const accessKeysRes = await descopeClient.management.accessKey.searchAll(['tenant-ID']);
accessKeysRes.data.forEach((accessKey) => {
// do something
});
// Update will override all fields as is. Use carefully.
await descopeClient.management.accessKey.update('key-id', 'new-key-name', 'new-description');
// Access keys can be deactivated to prevent usage. This can be undone using "activate".
await descopeClient.management.accessKey.deactivate('key-id');
// Disabled access keys can be activated once again.
await descopeClient.management.accessKey.activate('key-id');
// Access key deletion cannot be undone. Use carefully.
await descopeClient.management.accessKey.delete('key-id');
管理 SSO 设置
您可以管理SSO设置并映射SSO组角色和用户属性.
// You can get SSO settings for a specific tenant ID
// You can pass ssoId in case using multi SSO and you want to load specific SSO configuration
const ssoSettings = await descopeClient.management.sso.loadSettings('tenant-id');
// You can get all configured SSO settings for a specific tenant ID (for multi SSO usage)
const allSSOSettings = await descopeClient.management.sso.loadAllSettings('tenant-id');
// You can configure SSO settings manually by setting the required fields directly
// You can pass ssoId in case using multi SSO and you want to configure specific SSO configuration
const tenantId = 'tenant-id'; // Which tenant this configuration is for
const idpUrl = 'https://idp.com';
const entityId = 'my-idp-entity-id';
const idpCert = '<your-cert-here>';
const redirectURL = 'https://my-app.com/handle-sso'; // Global redirect URL for SSO/SAML
const domains = ['tenant-users.com']; // Users authentication with this domain will be logged in to this tenant
await descopeClient.management.sso.configureSAMLSettings(
tenantID,
{ idpUrl, entityId, idpCert },
redirectURL,
domains,
);
// Alternatively, configure using an SSO metadata URL
// You can pass ssoId in case using multi SSO and you want to configure specific SSO configuration
await descopeClient.management.sso.configureSAMLByMetadata(
tenantID,
{ idpMetadataUrl: 'https://idp.com/my-idp-metadata' },
redirectURL,
domains,
);
// Descope signs the SAML AuthnRequest it sends to the IdP. A few IdPs reject a signed request because
// their trusted provider entry holds no signing certificate for Descope - pass disableSignRequest on the
// settings (available on both variants above) to send the request unsigned for that configuration only.
await descopeClient.management.sso.configureSAMLSettings(
tenantID,
{ idpUrl, entityId, idpCert, disableSignRequest: true },
redirectURL,
domains,
);
// A configuration can be classified as authentication only: a login through it verifies the person's
// identity and returns the IdP response, creating no user and issuing no session, so it grants no
// access to your application. Omit authenticationOnly and the stored classification is kept, so an
// ordinary settings edit cannot clear it by omission; pass false to clear it. The same field is on the
// OIDC and Cross-App Access settings, and setting it through any one of them classifies the whole
// configuration. Read it back from the load response's top-level authenticationOnly.
await descopeClient.management.sso.configureSAMLSettings(
tenantID,
{ idpUrl, entityId, idpCert, authenticationOnly: true },
redirectURL,
domains,
);
// JIT provisioning can be turned off per SSO configuration: a login through it then signs in only
// users who already exist (invited, or provisioned through SCIM) and refuses anyone else. It applies to
// the configuration named by ssoId, or to the tenant's default configuration when ssoId is omitted.
// Omit jitDisabled to keep the stored value; pass false to turn JIT back on. The same field is on the
// OIDC settings. Read it back from the load response's top-level jitDisabled.
await descopeClient.management.sso.configureSAMLSettings(
tenantID,
{ idpUrl, entityId, idpCert, jitDisabled: true },
redirectURL,
domains,
'my-sso-id', // ssoId: omit for the tenant's default SSO configuration
);
// In case SSO is configured to work with OIDC use the following
// You can pass ssoId in case using multi SSO and you want to configure specific SSO configuration
const name = 'some-name';
const clientId = 'client id of OIDC';
const clientSecret = 'client secret';
// usePkce sends a PKCE code challenge to the IdP; omit it to keep the stored value
await descopeClient.management.sso.configureOIDCSettings(
tenantID,
{ name, clientId, clientSecret, redirectUrl, usePkce: true },
domains,
);
// You can create new SSO configuration (aka multi SSO)
const ssoId = 'my-new-additional-sso-id';
const displayName = 'My additional SSO configuration';
await descopeClient.management.sso.newSettings(tenantID, ssoId, displayName);
// You can delete existing SSO configuration
// You can pass ssoId in case using multi SSO and you want to delete specific SSO configuration
await descopeClient.management.sso.deleteSettings(tenantID);
// You can disable an SSO configuration without deleting it, and enable it again later.
// Its settings, mappings and domains are kept, so re-enabling needs no payload.
// You can pass ssoId in case using multi SSO and you want to disable a specific SSO configuration
await descopeClient.management.sso.configureAuthType(tenantID, 'none', ssoId);
// Enable it again on the protocol it is configured for ('saml' or 'oidc')
await descopeClient.management.sso.configureAuthType(tenantID, 'saml', ssoId);
注:证书的结构应与:
-----BEGIN CERTIFICATE-----
Certifcate contents
-----END CERTIFICATE-----
/ 您可以删除特定租户标识的 SSO 设置 正在等待 excope.client.management.sso.deleteSettings ("租户-d") 中
管理权限
您可以创建、更新、删除或加载权限 :
// You can optionally set a description for a permission.
const name = 'My Permission';
let description = 'Optional description to briefly explain what this permission allows.';
await descopeClient.management.permission.create(name, description);
// Update will override all fields as is. Use carefully.
const newName = 'My Updated Permission';
description = 'A revised description';
await descopeClient.management.permission.update(name, newName, description);
// Permission deletion cannot be undone. Use carefully.
await descopeClient.management.permission.delete(newName);
// Load all permissions
const permissionsRes = await descopeClient.management.permission.loadAll();
permissionsRes.data.forEach((permission) => {
// do something
});
管理角色
您可以创建、更新、删除或加载角色 :
// You can optionally set a description and associated permission for a roles.
// The optional `tenantId` will scope this role for a specific tenant. If left empty, the role will be available to all tenants.
const name = 'My Role';
const tenantId = '<tenant id>';
let description = 'Optional description to briefly explain what this role allows.';
const permissionNames = ['My Updated Permission'];
descopeClient.management.role.create(name, description, permissionNames, tenantId);
// Update will override all fields as is. Use carefully.
const newName = 'My Updated Role';
description = 'A revised description';
permissionNames.push('Another Permission');
descopeClient.management.role.update(name, newName, description, permissionNames, tenantId);
// Role deletion cannot be undone. Use carefully.
descopeClient.management.role.delete(newName, tenantId);
// Load all roles
const rolesRes = await descopeClient.management.role.loadAll();
rolesRes.data.forEach((role) => {
// do something
});
// Search roles
const rolesRes = await descopeClient.management.role.search({
tenantIds: ['t1', 't2'],
roleNames: ['role1'],
});
rolesRes.data.forEach((role) => {
// do something
});
查询 SSO 组
您可以查询 SSO 组 :
// Load all groups for a given tenant id
const groupsRes = descopeClient.management.group.loadAllGroups('tenant-id');
// Load all groups for the given user IDs (can be found in the user's JWT)
const groupsRes = descopeClient.management.group.loadAllGroupsForMember('tenant-id', [
'user-id-1',
'user-id-2',
]);
// Load all groups for the given user login IDs (used for sign-in)
const groupsRes = descopeClient.management.group.loadAllGroupsForMember(
'tenant-id',
[],
['login-id-1', 'login-id-2'],
);
// Load all group's members by the given group id
const groupsRes = descopeClient.management.group.loadAllGroupMembers('tenant-id', 'group-id');
groupsRes.data.forEach((group) => {
// do something
});
管理流程
您可以列出您的流量以及导入和导出流量和屏幕, 或者项目主题 :
// List all project flows
const res = await descopeClient.management.flow.list();
console.log('found total flows', res.total);
res.flows.forEach((flowMetadata) => {
// do something
});
// Delete flows by ids
await descopeClient.management.flow.delete(['flow-1', 'flow-2']);
// Export the flow and it's matching screens based on the given id
const res = await descopeClient.management.flow.export('sign-up');
console.log('found flow', res.data.flow);
res.data.screens.forEach((screen) => {
// do something
});
// Import the given flow and screens as the given id
const { flow, screens } = res.data;
const updatedRes = descopeClient.management.flow.import('sign-up', flow, screens);
console.log('updated flow', updatedRes.data.flow);
updatedRes.data.screens.forEach((screen) => {
// do something
});
// Run a management Flow
// Note: Flow must be a management flow, not an interactive flow
const runRes = await descopeClient.management.flow.run('management-flow-id');
console.log('flow result', runRes.data); // The result data will contain the flow's output, which is configured in the 'End' step of the flow
// Run a management Flow with input
// Note: Flow must be a management flow, not an interactive flow
const runWithInputRes = await descopeClient.management.flow.run('management-flow-id', {
input: {
key1: 'value1',
},
});
console.log('flow with input result', runWithInputRes.data); // The result data will contain the flow's output, which is configured in the 'End' step of the flow
// Export the current theme of the project
const res = descopeClient.management.theme.export();
console.log(res.data.theme);
// Import the given theme to the project
const updatedRes = descopeClient.management.theme.import(theme);
console.log(updatedRes.data.theme);
管理 JWTs
您可以在有效的 JWT 中添加自定义要求 .
const updatedJWTRes = await descopeClient.management.jwt.update('original-jwt', {
customKey1: 'custom-value1',
customKey2: 'custom-value2',
});
为用户生成JWT,在请求中模拟一个符号.
const res = await descopeClient.management.jwt.signIn('dummy');
为用户生成 JWT, 模拟一个签名请求 .
const res = await descopeClient.management.jwt.signUp('dummy');
为用户生成JWT,模拟一个签名或请求.
const res = await descopeClient.management.jwt.signUpOrIn('dummy');
为 OAuth 流量生成客户端断言 JWT .
const clientAssertionRes = await descopeClient.management.jwt.generateClientAssertionJwt(
'https://example.com/issuer', // issuer
'client-id-123', // subject
['https://example.com/token'], // audience
300, // expiresIn - number of seconds the token will will be valid for
false, // Optional. flattenAudience - set the audience claim as one string instead of array of strings (for case only one audience value has given)
'RS256', // Optional. algorithm - set the signing algorithm, value should be one of 'RS256', 'RS384', 'ES384' (default is RS256)
);
// clientAssertionRes.data.jwt contains the client assertion JWT
冒名顶替
您可以冒充到另一个用户
假冒用户必须拥有 impersonation 允许此请求生效.
反应将是冒名顶替用户的JWT的更新
const updatedJWTRes = await descopeClient.management.jwt.impersonate(
'impersonator-id',
'login-id',
true,
{ k1: 'v1' },
't1',
);
一旦假扮完成,你可以打电话 stopImpersonation,拿回一个jwt ht演员
const updatedJWTRes = await descopeClient.management.jwt.impersonate(
'<jwt string>',
{ k1: 'v1' },
't1',
);
注1:生成代码/链接功能,只为测试用户工作,不会为常规用户工作. 注2:如果在测试用户的登录/注册操作中,需要保证在调用登录/注册操作前生成代码.
嵌入式链接
可以创建嵌入式链接,直接接收可核查的符号而无需发送. 然后可以使用魔法链接"验证"的功能直接或通过流来验证这个符号.
const { token } = await descopeClient.management.user.generateEmbeddedLink('[email protected]', {
key1: 'value1',
});
审计
您可以对各个字段的特定值或全文进行审计搜索。 审计搜索限于过去30天.
// Full text search on the last 10 days
const audits = await descopeClient.management.audit.search({
from: Date.now() - 10 * 24 * 60 * 60 * 1000,
text: 'some-text',
});
console.log(audits);
// Search successful logins in the last 30 days
const audits = await descopeClient.management.audit.search({ actions: ['LoginSucceed'] });
console.log(audits);
您也可以使用数据创建审计事件
await descopeClient.management.audit.createEvent({
action: 'pencil.created',
type: 'info', // info/warn/error
actorId: 'UXXX',
tenantId: 'tenant-id',
data: {
some: 'data',
},
});
管理 FGA( 精细授权)
Descope支持完全基于关系的访问控制(ReBAC),使用像schema和操作一样的zanzibar. 一个计划由类型(如文档,文件夹,org等实体)组成,每个类型都有关系定义和权限来定义与其他类型的关系.
文件系统的一个简单的例子是:
model AuthZ 1.0
type user
type org
relation member: user
relation parent: org
type folder
relation parent: folder
relation owner: user | org#member
relation editor: user
relation viewer: user
permission can_create: owner | parent.owner
permission can_edit: editor | can_create
permission can_view: viewer | can_edit
type doc
relation parent: folder
relation owner: user | org#member
relation editor: user
relation viewer: user
permission can_create: owner | parent.owner
permission can_edit: editor | can_create
permission can_view: viewer | can_edit
SDK扫描仪使您能够充分管理计划与关系,并对关系的存在进行简单(而不是如此简单)的检查.
const descopeClient = require('@descope/node-sdk');
// Save schema
await descopeClient.management.fga.saveSchema(schema);
// Create a relation between a resource and user
await descopeClient.management.fga.createRelations([
{
resource: 'some-doc',
resourceType: 'doc',
relation: 'owner',
target: 'u1',
targetType: 'user',
},
]);
// Check if target has a relevant relation
// The answer should be true because an owner can also view
const relations = await descopeClient.management.fga.check([
{
resource: 'some-doc',
resourceType: 'doc',
relation: 'can_view',
target: 'u1',
targetType: 'user',
},
]);
重复FGA的反应时间 check 调用,特别是在高音量情景下,可以通过将调用重定向到与您应用程序相同的后端集群中的Descope FGA Cache Proxy运行来将调用降低到分毫秒分.
在通过Descope设置代理服务器后, 提供了 Docker 图像, 设置 fgaCacheUrl 参数与代理 URL 相等,以便在 SDK 中使用,如下例所示:
说明: 两者
fgaCacheUrl财务报告和审定财务报表managementKey必须规定要使用缓存代理。 如果只是这样的话fgaCacheUrl配置时没有managementKey,请求将使用标准的Descope API.
import DescopeClient from '@descope/node-sdk';
// Initialize client with FGA cache URL
const descopeClient = DescopeClient({
projectId: '<Project ID>',
managementKey: '<Management Key>', // Required for cache proxy
fgaCacheUrl: 'https://10.0.0.4', // example FGA Cache Proxy URL, running inside the same backend cluster
});
当 fgaCacheUrl 配置, 以下 FGA 方法将自动使用缓存代理, 而不是默认的 Descope API :
saveSchemacreateRelationsdeleteRelationscheck
如果缓存代理无法到达或返回出错,SDK会自动回落到标准的Descope API.
其他FGA业务如: loadResourcesDetails 财务报告和审定财务报表 saveResourcesDetails 将继续使用标准的Descope API终点.
管理外出应用程序
您可以创建、更新、删除或加载输出的应用程序 :
// Create an outbound application.
// For DCR-based apps (e.g. custom MCP servers that support RFC 7591 dynamic
// client registration), pass `useDcr: true` and `dcrUrl`.
const { id } =
await descopeClient.management.outboundApplication.createApplication({
name: 'my new app',
description: 'my desc',
...
});
// Create an outbound application from a preconfigured app library template.
// The template (e.g. "hubspot", "google", "slack") prepopulates the provider's
// OAuth config - authorization/token endpoints, default scopes, pkce, etc.
// Any field set in `overrides` takes precedence over the template default.
const { id: templatedId } =
await descopeClient.management.outboundApplication.createApplicationByTemplate({
templateId: 'hubspot',
clientId: 'my-client-id',
clientSecret: 'my-client-secret',
overrides: {
name: 'HubSpot',
// authorizationUrl / tokenUrl / defaultScopes / pkce inherited from the template
},
});
// Update an outbound application.
// Update will override all fields as is. Use carefully.
await descopeClient.management.outboundApplication.updateApplication({
id: 'my-app-id',
name: 'my updated app',
...
});
// delete an outbound appl