@ descope/ web- 组件

在控制台应用程序上创建您的登录页面, 完成后, 您可以使用此库向您的应用程序注入这些页面
它记录着.. 网络组件 并根据相关网页更新网页内容, 见下文使用实例

使用量

安装软件包

npm install @descope/web-component

作为图书馆

import '@descope/web-component' // This import will define `descope-wc` custom element
import { DescopeWc } // In case you need types definition or you want to use the class directly

// Render Descope Web Component, for example:
render(){
  return (
    <descope-wc project-id="myProjectId"/>
  )
}

在 HTML 文件内

• 复制文件 @descope/web-component/dist/index.js 重命名为 descope-wc.js 并将其放置在您的 HTML 文件所在位置

• 将以下脚本标签添加到您的 HTML 文件

<head>
  <script src="./descope-wc.js"></script>
</head>

• 现在可以将自定义元素添加到您的 HTML

<descope-wc project-id="<project-id>" flow-id="<flow-id>" form='{ "email": "[email protected]", "myCustomInput": "12" }' client='{ "browserVersion": window.navigator.appVersion }'></descope-wc>

• 说明: form 财务报告和审定财务报表 client 是可选参数,用于添加可在流量中使用的额外信息。 详情 点击这里。 。 。 .

运行示例

举例来说:

1. 安装依赖关系 pnpm i
2. 创建一个 .env 文件与以下变量:

// .env
# Descope Project ID
DESCOPE_PROJECT_ID=<project-id>
# Flow ID to run, e.g. sign-up-or-in
DESCOPE_FLOW_ID=<flow-id>
# Optional - Descope base URL
DESCOPE_BASE_URL
# Optional - Descope locale (according to the target locales configured in the flow)
DESCOPE_LOCALE=<locale>

# Telemetry fallback config (AWS CloudWatch RUM).
# Optional — used by the SDK only when the backend's config.json doesn't
# ship a `telemetry` block. Once it does, these are ignored.
# Leave DESCOPE_TELEMETRY_ENABLED unset or set to anything other than
# "true" to keep the fallback off.
DESCOPE_TELEMETRY_ENABLED=<true|false>
DESCOPE_TELEMETRY_APPLICATION_ID=<cloudwatch-rum-app-monitor-id>
DESCOPE_TELEMETRY_IDENTITY_POOL_ID=<aws-cognito-identity-pool-id>
DESCOPE_TELEMETRY_REGION=<aws-region>
# Optional — only required for the classic Cognito flow.
DESCOPE_TELEMETRY_GUEST_ROLE_ARN=<iam-guest-role-arn>
# Optional — 0..1, defaults to 1 (capture every session).
DESCOPE_TELEMETRY_SESSION_SAMPLE_RATE=1

1. 运行样本 pnpm run start 编号 : pnpm run start-web-sample

注: 这个包是单列波的一部分. 所以,如果您在依赖关系上有所改变,您必须重新运行 npm run start 编号 : pnpm run start-web-sample (这是暂时的解决方案,直到我们改进过程以适应单重).

安全特性

分资源廉正

网页组件自动应用 分资源廉正 当项目配置中存在SRI散列时, 请检查网络组件- ui 加载器 。 这提供了加密验证,说明所装入的脚本没有被篡改.

如何运作:

1. Descope 管弦乐服务为每个版本的网络组件- ui 库生成 SRI 散列
2. 散列包含在 config.json 作为 componentsVersionSri
3. 网络组件自动添加 integrity 财务报告和审定财务报表 crossorigin 脚本标签属性
4. 浏览器在执行前验证脚本完整性

生成脚本标签示例 :

<script src="https://descopecdn.com/npm/@descope/[email protected]/dist/umd/index.js" integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K..." crossorigin="anonymous"></script>

内容安全政策相容性 :

SRI与CSP合作无缝. 对于严格的CSP配置,将SRI与 nonce 属性 :

<descope-wc project-id="myProjectId" flow-id="sign-up-or-in" nonce="random-nonce-value"></descope-wc>

CSP 标题示例 :

Content-Security-Policy:
  script-src 'self'
    https://descopecdn.com
    https://static.descope.com
    https://cdn.jsdelivr.net
    'nonce-random-nonce-value';

后向兼容性 :

如果配置(更老的项目)中没有SRI散列,组件通常会不进行完整性检查而加载. 不需要中断更改 .

跨源 OAuth 弹出

当 OAuth 弹出重定向页面的出处不同于打开它的页面时(参见 popup-origin),弹出会只将OAuth结果寄给开源Descope证明弹出. Descope证明,当弹出是项目核准的域之一时,或者当项目没有核准的域时,打开弹出页的出处. 否则,弹出只回答同一个来源 BroadcastChannel,因此列出项目核准域中的主要应用程序域.

可选属性

可选属性

errorTransformer - 接收出错对象并返回字符串的函数。 返回的字符串将显示给用户 .

该功能可用于将出错消息翻译为用户语言,或更改出错消息.

用法示例:

function translateError(error) {
  const translationMap = {
    SAMLStartFailed: 'No es posible iniciar sesión en este momento, por favor intenta nuevamente más tarde',
  };
  return translationMap[error.type] || error.text;
}

const descopeWcEle = document.getElementsByTagName('descope-wc')[0];

descopeWcEle.errorTransformer = translateError;

logger - 定义如何记录错误、警告和信息的对象。 分别默认控制台.error,控制台.warn和控制台.info

用法示例:

const logger = {
  info: (message: string, description: string, state: any) => {
    console.log(message, description);
  },
  warn: (title: string, description: string) => {
    console.warn(`WARN: ${title}`, description);
  },
  error: (title: string, description: string) => {
    console.error(`ERROR: ${title}`, description);
  },
};

const descopeWcEle = document.getElementsByTagName('descope-wc')[0];

descopeWcEle.logger = logger;

onScreenUpdate

当出现新屏幕状态时, 并在每次呼叫后, 都会调用此功能 。 它得到以下参数:

• screenName: 即将渲染的屏幕名称
• context: 包含即将到来的屏幕状态的对象
• next: 当调用时继续流执行的函数
• ref: 提及去镜-wc节点

该函数可以是同步或async,并且应当返回布尔表示是否应该渲染自定义屏幕:

• true: 渲染自定义屏幕
• false: 渲染默认流程屏幕

断裂变化( v4. 0.0) : 服务器生成的用于直接显示的屏幕数据 context 现在生活在 context.data - 比如说. context.totp → context.data.totp, (中文(简体) ), context.inboundAppApproveScopes → context.data.inboundAppApproveScopes现状, form,和身份字段(user 编号 : project 编号 : lastAuth)住顶上. 见 这个 context 对象 完整清单 context.data 字段.

此功能允许渲染自定义屏幕而不是默认的流程屏幕. 对于高度定制化的 UI 或默认屏幕未覆盖的特定逻辑来说,它可能有用

为了制作自定义屏幕,其内容应作为儿童随附 descope-wc 组件

用法示例:

function onScreenUpdate(screenName, context, next, ref) {
  if (screenName === 'My Custom Screen') {
    ref.innerHTML = `
          <form>
            <input type="text" name="email" placeholder="Email" />
            <button type="submit">Submit</button>
          </form>
        `;

    ref.closest('form').addEventListener('submit', (e) => {
      e.preventDefault();
      const formData = new FormData(e.target);
      const data = Object.fromEntries(formData.entries());

      // replace with the button interaction id
      next('interactionId', data);
    });

    return true;
  }

  return false;
}

const descopeWcEle = document.querySelector('descope-wc');

descopeWcEle.onScreenUpdate = onScreenUpdate;

这个 context 对象

context 携带即将到来的屏幕状态 :

• 顶级 —— 说 error, (中文(简体) ), action, (中文(简体) ), form (输入/输出渠道)和 用户上下文 : user, (中文(简体) ), project, (中文(简体) ), lastAuth。 。 。 .
• context.data 所有服务器制作的屏幕数据 在一个干净稳定的地方,所以你 不需要阅读 内部,深沉的路径.

例如,一个生成 MFA 恢复代码的屏幕会将它们暴露为平面阵列:

function onScreenUpdate(screenName, context, next, ref) {
  if (screenName === 'Display recovery codes') {
    const codes = context.data.recoveryCodes; // string[]
    // render the codes in your custom UI…
    return true;
  }
  return false;
}

context.data 可能包括(每个屏幕产生时才会显示):

• recoveryCodes - 生成外交部的回收代码(string[](中文(简体) )
• totp 编号 : notp 外交部设置(图像、提供/直接URL)
• sentTo - 传送检察官办公室/编码的地方(用口罩的电子邮件/电话)
• inboundAppApproveScopes - 范围 入境应用程序要求用户批准
• passwordPolicy - 显示/执行密码规则
• securityQuestionsSetup 编号 : securityQuestionsVerify - 安全问题
• userTenants, (中文(简体) ), userRoles, (中文(简体) ), ssoApplications, (中文(简体) ), ssoConfigurations - 选择选项
• samlAttributeMappings, (中文(简体) ), oidcAttributeMappings, (中文(简体) ), samlGroupMappings ——SSO测绘
• sso ——SSO服务提供者配置
• selfProvisionDomains - 租户自给领域
• outboundApp ——出局 OAuth 应用程序按钮信息

context.data 是一个由 SDK 拥有的支持,稳定的字段—— 与其读取,不如读取 原始屏幕状态内部。 它只暴露了上面有记录的字段;任何其他字段 内部屏幕状态数据被故意省略。 在 SDK 发布中添加了新字段.

每把钥匙 context.data 是一个SDK拥有,有文件记载的名称。 SDK从不说 任意、自定义键直接打开 context.data,所以总是添加新字段 没有打破已有的.

尚未曝光 : 动态选择选项( 其选项被计算出来的选定组件) 以流动盟誓, 它们的键是流本身的字段名,所以它们不符合固定形状 以上;暂时略去,保留给未来 context.data.selects 地图。 这个 以前没有自定义屏幕可用的数据,所以对现有代码没有任何修改.

断裂变化( v4. 0.0) : 曾经直接显示的屏幕数据字段 context 现在住在下面 context.data。移动读取相应,例如. context.inboundAppApproveScopes → context.data.inboundAppApproveScopes, (中文(简体) ), context.totp → context.data.totp现状, form字段 (单位:千美元)user编号 :project编号 :lastAuth)住顶上.

活动

error - 出错时开火 事件细节包含出错对象.

用法示例:

const descopeWcEle = document.getElementsByTagName('descope-wc')[0];
descopeWcEle.addEventListener('error', (e) => alert(`Error! - ${e.detail.errorMessage}`));

success - 流量成功完成后发射。 事件细节包含流结果.

用法示例:

const descopeWcEle = document.getElementsByTagName('descope-wc')[0];
descopeWcEle.addEventListener('success', (e) => alert(`Success! - ${JSON.stringify(e.detail)}`));

ready - 页面准备好了就开火.

此事件对在装入页面前显示/ 隐藏装入指示有用 . 注意:如果流量涉及重定向到过程的非初始阶段,例如与Magic Link或OAuth,此事件也会被发送.

用法示例:

const descopeWcEle = document.getElementsByTagName('descope-wc')[0];
descopeWcEle.addEventListener('ready', () => {
  // Remove/hide the loading indication
});