@forgerock/login-widget

ForgeRock 登录部件

无 • 妇女 支助 • 妇女 文档

目录

• 概览
• 所需资源
• 快速启动
  • 安装
  • 添加 CSS 软件
  • 挂起部件
• 可观察模式
  • 订阅事件
  • 取消订阅
  • 获取当前值
  • 请求新值
  • 使用承诺
• 完成部件 API
  • 部件
  • 配置
  • 旅程
  • 构成部分
  • 用户
  • 样式配置
  • 链接配置
  • 内容配置
  • CAPTCHA 配置
  • 脚本文本输出
• 支持的回调
• 免责声明
• 许可证

概览

登录元件是处理任何现代JavaScriptapp中的登录,注册,和相关用户流量的全能UI组件. 它与React,Vue,Angular,Svelte,或vanilla JavaScript合作——目前不支持Node.js或服务器侧渲染(SSR).

部件使用 旅行客户端 用于行刑,以及 OIDC 客户端 用于 OAuth/OIDC 令牌和用户信息。 它在这些SDK上方增加了一个UI渲染层来消除开发和维护复杂认证流的UI组件的需要. 虽然这个渲染层是与斯维尔特和泰尔温德一起开发的,但两者都是"编译而去"的,没有运行时间依赖性. 由此产生的部件是库和框架不可知性.

部件可以分为两个形式因素:

1. 模式 (default):在打开并关闭的模式对话框中,渲染器构成元素. 已挂载 外部 你的应用程序控制DOM.
2. 内入: 只是没有容器的窗体元素。 已挂载 内部 你的应用程序控制DOM.

两种形式因素都提供相同的认证,OAuth/OIDC,以及用户特性. 从Modal开始——它提供了最快的路径来添加登录/注册,最小的干扰到您现有的代码库.

所需资源

• ECMAScript 模块或通用JS 启用客户端 JavaScript app
• 一个完全支持的现代浏览器:Chrome,Firefox,Safari,或Chrimium Edge

不予支持:Internet Explorer,Legacy Edge,WebView,Electron等被修改的浏览器类似环境.

快速启动

安装

npm install @forgerock/login-widget

添加 CSS 软件

导入您的 JavaScript :

import '@forgerock/login-widget/widget.css';

导入您的 CSS :

@import '@forgerock/login-widget/widget.css';

或者在 HTML 中链接( 从 npm 模块复制 CSS 文件到您的静态文件):

<link rel="stylesheet" href="/path/to/file/widget.css" />

控制CSS连锁店

虽然不需要,但使用 @layer 确保浏览器按预定顺序应用CSS,无论导入顺序如何. 更多信息: @ layer。 。 。 .

1. 将您的 CSS 包成一层 :

   @layer app {
     /* Your app's CSS */
   }
   

2. 在 CSS 装入之前, 在 HTML 中声明层顺序 :

   <style type="text/css">
     @layer app;
     @layer 'fr-widget.base';
     @layer 'fr-widget.utilities';
     @layer 'fr-widget.components';
     @layer 'fr-widget.variants';
   </style>
   

   部件 CSS 已完全命名空格 —— 它不会覆盖您的应用程序的 CSS 除非您使用相同的选择器命名会议 .

挂起部件

在您的 HTML 文件中添加一个专用元素, 作为直接的孩子 <body>,与您的主应用根分离 :

<body>
  <div id="root"></div>
  <div id="widget-root"></div>
</body>

提示: 不要将模式形式因子挂载在您的应用程序虚拟 DOM 中的动态元素上 。 在您静态的 HTML 文件内硬编码它 .

导入、配置和即时 :

import Widget, { configure, journey } from '@forgerock/login-widget';

// 1. Configure — async; awaiting it ensures both clients are ready before use
await configure({
  // REQUIRED — the well-known URL, shared by the journey and OIDC clients
  serverConfig: {
    wellknown:
      'https://your-tenant.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration',
  },
  // REQUIRED if you use OAuth/OIDC tokens, user info, or logout
  oidcClient: {
    clientId: 'YourOauthClient',
    redirectUri: `${window.location.origin}/callback`,
    scope: 'openid profile email', // OPTIONAL — defaults to 'openid'
  },
});

// 2. Instantiate
const widgetRootEl = document.getElementById('widget-root');
new Widget({ target: widgetRootEl });

// 3. Start a journey
const journeyEvents = journey();
journeyEvents.start();

提示数字 : configure() 总是 await 在您的应用程序的顶层( )index.js 或者说 app.js打电话之前 journey().start() 或其他部件 API。 这确保了OIDC和出行客户在尝试任何取货之前都能够完全构建.

可观察模式

大多数元件API是同步的并使用以事件为中心的可观测模式. 部件使用 Svelte 的简化标准可观察执行, 称为“ 仓库 ” —— 这些都嵌入到部件中, 而不是您需要管理的应用程序的依赖性 .

有关斯维尔特商店合同的更多信息。 。 。 .

订阅事件

import { user } from '@forgerock/login-widget';

const userInfoEvents = user.info();

userInfoEvents.subscribe((event) => {
  if (event.loading) {
    console.log('User info is being requested from server');
  } else if (event.successful) {
    console.log('User info request was successful');
    console.log(event.response);
  } else if (event.error) {
    console.error('User info request failed');
    console.error(event.error.message);
  }
});

取消订阅

可观察者不像"承诺"——他们不解而得到清理. 在不再需要时必须取消订阅,特别是在频繁被创建和销毁的组件方面:

const unsubscribe = userInfoEvents.subscribe((event) => console.log(event));

// Later, when no longer needed:
unsubscribe();

说明: 如果在应用程序整个存在期间一直存在的顶级组件上签名,则不需要不签名.

获取当前值

要在不订阅未来事件的情况下将当前值存储在部件内, 请拨 subscribe 并立即调用返回的未订阅函数 :

let userInfo;
userInfoEvents.subscribe((event) => (userInfo = event.response))();

请求新值

行动方法 get 以请求服务器的新值。 任何活动 subscribe 调用会收到由此引发的事件:

userInfoEvents.get();

使用承诺

所有涉及网络呼叫的部件 API 也支持承诺 :

// async/await
const userInfo = await userInfoEvents.get();

// Promise chain
userInfoEvents
  .get()
  .then((data) => console.log(data))
  .catch((err) => console.error(err));

完成部件 API

部件

import Widget from '@forgerock/login-widget';

// Instantiate
const widget = new Widget({
  target: widgetRootEl, // REQUIRED; a real DOM element
  props: {
    type: 'modal', // OPTIONAL; "modal" (default) or "inline"
  },
});

// Remove widget from DOM and destroy listeners
widget.$destroy();

说明: 调用 $destroy() 如果在经常被创建和销毁的组件中即时插入部件。 我们建议在您的应用树上, 在一个曾经创建并保存的组件中, 立即提高.

配置

import { configure } from '@forgerock/login-widget';

// configure() is async — await it before calling any other Widget API
await configure({
  // REQUIRED — the well-known URL, shared by the journey and OIDC clients
  serverConfig: {
    wellknown:
      'https://your-tenant.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration',
  },
  // REQUIRED if you use OAuth/OIDC tokens, user info, or logout
  oidcClient: {
    clientId: 'WebOAuthClient',
    redirectUri: `${window.location.origin}/callback`,
    scope: 'openid profile email',
  },
  // OPTIONAL — logger for both clients; `level` gates verbosity and `custom`
  // redirects SDK log output to your own sink. See the full example below.
  logger: { level: 'warn' },
  // OPTIONAL — request middleware for both clients; see the full example below
  middleware: [],
  // OPTIONAL — token storage config; see Storage section below
  storage: { type: 'sessionStorage', name: 'tokens' },
  // OPTIONAL — see dedicated sections below
  content: {},
  links: {},
  style: {},
});

移民说明(2.0): 这个 forgerock 配置对象已替换为 oidcClient。 。 。 . 最终点的发现现在由 serverConfig.wellknown,由旅程和OIDC共享 客户- baseUrl, (中文(简体) ), realmPath, (中文(简体) ), timeout,以及 support 不再使用. clientId 财务报告和审定财务报表 redirectUri 配置时需要 oidcClient· ; scope 默认为 'openid'。 。 。 . tokenStore 已经 移动到顶层 storage 选项.

锁定器

高层 logger 选项将同时传输到行程和OIDC客户端.

await configure({
  serverConfig: {
    wellknown:
      'https://your-tenant.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration',
  },
  logger: {
    level: 'debug',
    // OPTIONAL — route SDK logs to your own sink instead of the console.
    custom: {
      error: (...args) => myLogger.error(...args),
      warn: (...args) => myLogger.warn(...args),
      info: (...args) => myLogger.info(...args),
      debug: (...args) => myLogger.debug(...args),
    },
  },
  oidcClient: {
    clientId: 'WebOAuthClient',
    redirectUri: `${window.location.origin}/callback`,
    scope: 'openid profile email',
  },
});

OIDC 客户端选项

所有属性都嵌入其中 oidcClient。 。 。 .

所有 OIDC 选项示例 :

await configure({
  serverConfig: {
    wellknown:
      'https://your-tenant.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration',
  },
  logger: { level: 'debug' },
  middleware: [
    (req, action, next) => {
      console.log('[middleware]', action.type, req.url);
      next();
    },
  ],
  storage: { type: 'sessionStorage', name: 'tokens', prefix: 'myapp' },
  oidcClient: {
    clientId: 'WebOAuthClient',
    redirectUri: `${window.location.origin}/callback`,
    scope: 'openid profile email',
    oauthThreshold: 60000,
    par: true,
    loginHint: '[email protected]',
    acrValues: 'urn:acr:2fa',
    query: { ui_locales: 'en-US' },
  },
});

存储

高层 storage 选项配置 OIDC 客户端坚持符号的位置。 镜子 sDK的车 StorageConfig 工会- type 选择浏览器存储或自定义槽.

// Browser store
storage: { type: 'sessionStorage', name: 'tokens', prefix: 'myapp' },

// Custom store
storage: {
  type: 'custom',
  name: 'tokens',
  custom: {
    get: async (key) => myStore.read(key),
    set: async (key, value) => myStore.write(key, value),
    remove: async (key) => myStore.delete(key),
  },
},

旅程

import { journey } from '@forgerock/login-widget';

const journeyEvents = journey({
  oauth: true, // OPTIONAL; default true; use OAuth flow for tokens
  user: true, // OPTIONAL; default true; fetch user info from /userinfo
});

// Start a journey
journeyEvents.start({
  journey: 'Login', // OPTIONAL; journey name (omit to let AM choose the default)
  resumeUrl: window.location.href, // OPTIONAL; URL for resuming a suspended journey
});

// Change to a different journey
journeyEvents.change({
  journey: 'Registration',
});

// Listen for events
journeyEvents.subscribe((event) => {
  if (event.journey.successful) {
    console.log('Authentication succeeded', event);
  }
});

巡回赛计划:

{
  journey: {
    completed: false,     // boolean
    error: null,          // null or { code, message, step }
    loading: false,       // boolean
    step: null,           // null or step object from ForgeRock AM
    successful: false,    // boolean
    response: null,       // null or success response from AM
  },
  oauth: {
    completed: false,     // boolean
    error: null,          // null or { code, message }
    loading: false,       // boolean
    successful: false,    // boolean
    response: null,       // null or OAuth/OIDC tokens
  },
  user: {
    completed: false,     // boolean
    error: null,          // null or { code, message }
    loading: false,       // boolean
    successful: false,    // boolean
    response: null,       // null or user info (driven by OAuth scope)
  },
}

构成部分

这个 component API控制部件的生命周期. 对于模式形式因素,它规定: open 财务报告和审定财务报表 close 方法。 。 .

import { component } from '@forgerock/login-widget';

const componentEvents = component();

// Open/close the modal
componentEvents.open();
componentEvents.close();

// Listen for lifecycle events
componentEvents.subscribe((event) => {
  if (event.mounted) console.log('Widget is mounted');
  if (event.open === false) console.log('Modal closed:', event.reason);
});

组件事件计划 :

{
  error: null,    // null or { code, message, step }
  mounted: false, // boolean
  open: null,     // boolean or null (null for inline type)
  reason: null,   // "user" | "auto" | "external"
  type: null,     // "modal" | "inline"
}

近因:

用户

import { user } from '@forgerock/login-widget';

// User info
const userEvents = user.info();
userEvents.subscribe((event) => console.log(event));
userEvents.get(); // Fetch fresh user info from server

// User tokens
const tokenEvents = user.tokens();
tokenEvents.subscribe((event) => console.log(event));
tokenEvents.get(); // Fetch fresh tokens from server

// Logout
user.logout(); // Clears user data and emits events to subscribers

用户信息/ 令牌事件计划 :

{
  completed: false,  // boolean
  error: null,       // null or { code, message }
  loading: false,    // boolean
  successful: false, // boolean
  response: null,    // object from /userinfo or /access_token endpoint
}

调用受保护资源

已删除于 2. 0.0 : 这个 request 导出( 遗留物的别名) HttpClient.request)已经 已删除. @forgerock/oidc-client 不提供 HTTP 客户端。 从 user.tokens() 打电话 fetch 直接添加 Authorization 给自己页眉:

import { user } from '@forgerock/login-widget';

const tokenEvents = user.tokens();
const { response: tokens } = await tokenEvents.get();

const response = await fetch('https://protected.resource.com', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${tokens.accessToken}`,
  },
});

说明: 遗产 request 401 上自动刷新代号并解析身份网关 政策咨询。 这些行为不是新的SDK提供的,必要时必须由消费者实施.

样式配置

配置部件的视觉外观 :

await configure({
  style: {
    checksAndRadios: 'animated', // OPTIONAL; 'animated' or 'standard'
    labels: 'floating', // OPTIONAL; 'floating' or 'stacked'
    logo: {
      dark: 'https://example.com/img/white-logo.png',
      light: 'https://example.com/img/black-logo.png', // REQUIRED if logo provided
      height: 300,
      width: 400,
    },
    sections: {
      // OPTIONAL; modal only
      header: false, // Display a header section with logo
    },
    stage: {
      icon: true, // OPTIONAL; display generic stage icons
    },
    callbacks: {
      // OPTIONAL; per-callback style rules, keyed by AM callback type name
      // — see "Scripted Text Output"; rules are plain string dictionaries
      TextOutputCallback: [{ type: '4', display: 'hidden' }],
    },
  },
});

说明编号: sections.header 属性仅适用于模式形式因素。 这个 logo 财产适用于所有形式因素.

Logo CSS 自定义属性

标识配置作为根级 CSS 自定义属性应用在部件根上 元素,在每个主题通过后重新应用。 这些是 倒计时 槽; IDM 页面节点 主题设置主 --logo-light 编号 : --logo-dark 插槽并优先于它们.

有效 light 编号 : dark 值为 https:// URL( URL) , (中文), data:image/ URI, 或根相通路径 (牵头单位) /) (中文(简体) ). 无效的值通过配置验证来投放 .

链接配置

设置术语和条件页面的 URL( 由 TermsAndConditionsCallback:

await configure({
  links: {
    termsAndConditions: 'https://example.com/terms',
  },
});

内容配置

用自定义文本覆盖部件的默认内容 。 关于整个计划,见 en-US 语言文件。 。 。 .

await configure({
  content: {
    // Custom content that overrides Widget defaults
  },
});

CAPTCHA 配置

AM在召回有效载荷中都不显示隐形模式 ReCaptchaCallback 或者说 ReCaptchaEnterpriseCallback。使用 captcha 选项来配置无形渲染 :

await configure({
  captcha: {
    mode: 'invisible', // 'visible' (default) | 'invisible'
  },
});

脚本装入 : 部件在挂载时自动注入所需的 CAPTCHA 脚本—— 没有手动 <script> 需要标记 。 如果提供者API(window.grecaptcha 编号 : window.hcaptcha当部件挂载时, 插入已跳过 .

脚本文本输出

行程可以返回客户端 JavaScript 作为 TextOutputCallback 与 messageType 4 ——例如追踪或设备指印片段. 此部件不执行这些脚本, 因此默认它会将脚本源打印到屏幕上作为文本 .

隐藏规则列表 callbacks数字 :

await configure({
  style: {
    callbacks: {
      // omit for default: prints the script source
      TextOutputCallback: [{ type: '4', display: 'hidden' }],
    },
  },
});

每条规则都是一个简单的字符串词典, 传递给那个召回的渲染器. type 选择一个 TextOutputCallback 信件类型和 display: 'hidden' 压制之. 资料0)),警告(1)和出错(2信息照常传送。 脚本仍然没有以两种方式执行——该选项只控制其来源是否被显示.

支持的回调

部件支持以下 ForgeRock 回调 :

• 页面节点
• 用户名、 密码
• WebAuthn( 注册和登录)
• 推动认证
• 一次性密码验证
• 社会登录( 苹果, Facebook, 谷歌)
• 电子邮件暂停( “ 魔法链接 ” )
• 设备配置
• reCAPTCHA v2(可见+可见), reCAPTCHA Entertainment, hCaptcha(可见+可见)
• QR 代码
• 小平保护

免责声明

此代码由ForgeRock在"照样"的基础上提供,没有任何种类的保证,在法律允许的最大限度内提供. ForgeRock不代表、要求或保证该守则的使用,也不保证与该守则有关的任何数据或资料的准确性、及时性或完整性,ForgeRock特此声明所有担保,无论是明示的、默示的还是法定的,包括不受限制地保证具有商贸能力、适合某一特定目的,以及任何不违反该守则的保证。 ForgeRock不应因本守则的任何使用、实施或配置而产生或与之有关的任何赔偿责任,包括但不限于用于任何商业目的。 与使用该法典有关的任何诉讼或诉讼只能由ForgeRock居住或ForgeRock主要经营的法域的法院提起,并且根据该法域的法律,排除其法律冲突条款.

许可证

这个项目根据麻省理工学院许可证获得许可证——见: 自由主义 详细文件.

版权2022-2026平身份公司. 所有权利保留.