dqj/sample-site

Fork 0

Files

dqj 6c9491bfd0 Add SSO and device management samples

2026-05-20 22:40:32 +09:00

6.6 KiB

Raw Blame History

Fido2Login SDK API 文档

概述

Fido2UIManager.renderLogin() 是一个用于渲染登录组件的API，支持：

Fido2/Passkey 自动登录
密码登录回退
密码重试次数限制
完全的回调驱动（SDK不跳转页面）

使用方法

1. 引入依赖

<script src="files/jquery.js"></script>
<script src="files/bootstrap.js"></script>
<script src="files/dfido2-lib.js"></script>
<script src="files/fido2-ui-sdk.js"></script>

2. 添加容器

<div id="login-container"></div>

3. 初始化登录组件

const loginManager = Fido2UIManager.renderLogin({
  container: '#login-container',
  features: {
    autoAuth: true,
    enablePasswordLogin: true,
    maxPasswordAttempts: 3,
    showRemainingAttempts: true
  },
  callbacks: {
    onFido2Success: (userId, session) => {
      // 处理Fido2登录成功
    },
    onFido2Error: (error) => {
      // 处理Fido2登录失败
    },
    onPasswordLogin: (userId, password) => {
      // 返回 Promise<boolean>
    },
    onPasswordExhausted: (userId, attempts, maxAttempts) => {
      // 密码重试次数耗尽
    },
    onLoginClosed: () => {
      // UI被关闭
    }
  }
});

配置参数

container

类型: string | Element
必填: 是
说明: 模态框容器元素

features

类型: Object
默认值: 见下方

属性	类型	默认值	说明
`autoAuth`	boolean	true	有注册设备时自动Fido2登录
`enablePasswordLogin`	boolean	true	是否启用密码登录功能
`autoShowPassword`	boolean	false	Fido2失败后是否自动显示密码框
`maxPasswordAttempts`	number	3	密码最大重试次数
`showRemainingAttempts`	boolean	true	是否显示剩余尝试次数

theme

类型: Object
说明: 复用 renderDeviceManager 的theme配置

属性	类型	默认值	说明
`logo`	string	null	Logo图片URL
`primaryColor`	string	'#696cff'	主色调
`backgroundColor`	string	'#ffffff'	背景色
`textColor`	string	'#333333'	文字颜色
`borderRadius`	string	'8px'	边框圆角

language

类型: string
默认值: 'zh-CN'
说明: 支持9种语言

callbacks

onFido2Success(userId, session)

触发时机: Fido2登录认证成功
参数:
- userId: string - 用户ID
- session: object - 会话信息
注意: SDK不跳转页面，由调用端处理跳转

onFido2Error(error)

触发时机: Fido2登录失败或取消
参数: error 对象
- code: string - 错误码
- message: string - 错误信息
- originalError: object - 原始错误

error.code 值:

code	说明
`CANCELED`	用户取消认证
`AUTH_FAILED`	认证失败
`NO_REGISTRATION`	无注册设备且未启用密码登录
`NOT_SUPPORTED`	浏览器不支持WebAuthn

onPasswordLogin(userId, password)

触发时机: 用户点击密码登录按钮
参数:
- userId: string - 用户ID
- password: string - 密码
返回值: Promise<boolean>
- true: 登录成功
- false: 登录失败

onPasswordExhausted(userId, attempts, maxAttempts)

触发时机: 密码重试次数耗尽
参数:
- userId: string - 用户ID
- attempts: number - 已尝试次数
- maxAttempts: number - 最大允许次数
注意: UI已自动关闭

onLoginClosed()

触发时机: 用户关闭模态框（点击×或调用hide()）

实例方法

show()

显示登录模态框

hide()

隐藏登录模态框，触发 onLoginClosed 回调

destroy()

销毁登录组件实例，不触发任何回调

setMode(mode)

切换登录模式

mode: 'fido2' 或 'password'

getUserId()

获取当前输入的用户ID

getState()

获取当前状态

返回值: 'loading' | 'fido2' | 'password' | 'closed'

getMode()

获取当前模式

返回值: 'fido2' | 'password'

getAttemptCount()

获取当前密码尝试次数

getRemainingAttempts()

获取剩余尝试次数

resetPasswordAttempts()

重置密码尝试计数器

国际化支持

默认支持9种语言：

en-US (英语)
zh-CN (简体中文)
ja (日语)
es (西班牙语)
de (德语)
fr (法语)
pt (葡萄牙语)
ko (韩语)
ru (俄语)
it (意大利语)

可通过 customI18n 配置自定义文本：

Fido2UIManager.renderLogin({
  customI18n: {
    'title_login': {
      'en-US': 'Custom Login',
      'zh-CN': '自定义登录'
    }
  }
});

完整示例

<!DOCTYPE html>
<html>
<head>
  <title>Login Example</title>
  <link rel="stylesheet" href="files/bootstrap.css">
  <script src="files/jquery.js"></script>
  <script src="files/bootstrap.js"></script>
  <script src="files/dfido2-lib.js"></script>
  <script src="files/fido2-ui-sdk.js"></script>
</head>
<body>
  <div id="login-container"></div>

  <script>
    const loginManager = Fido2UIManager.renderLogin({
      container: '#login-container',
      features: {
        autoAuth: true,
        enablePasswordLogin: true,
        maxPasswordAttempts: 3,
        showRemainingAttempts: true
      },
      callbacks: {
        onFido2Success: (userId, session) => {
          // 保存登录状态
          localStorage.setItem('userId', userId);
          localStorage.setItem('session', JSON.stringify(session));
          // 跳转页面
          window.location.href = '/dashboard';
        },
        onFido2Error: (error) => {
          switch (error.code) {
            case 'CANCELED':
              console.log('用户取消登录');
              break;
            case 'AUTH_FAILED':
              console.log('认证失败:', error.message);
              break;
            case 'NO_REGISTRATION':
              alert('暂未注册设备，请联系管理员');
              break;
          }
        },
        onPasswordLogin: (userId, password) => {
          return fetch('/api/login', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ userId, password })
          }).then(r => r.ok);
        },
        onPasswordExhausted: (userId, attempts, maxAttempts) => {
          alert('尝试次数过多，请稍后重试');
        },
        onLoginClosed: () => {
          console.log('登录窗口已关闭');
        }
      }
    });
  </script>
</body>
</html>

版本信息

FIDO2 UI SDK: v1.0.0+
文件: files/fido2-ui-sdk.js
新增功能: Fido2UIManager.renderLogin()

6.6 KiB Raw Blame History Unescape Escape