271 lines
6.6 KiB
Markdown
271 lines
6.6 KiB
Markdown
# Fido2Login SDK API 文档
|
||
|
||
## 概述
|
||
|
||
`Fido2UIManager.renderLogin()` 是一个用于渲染登录组件的API，支持：
|
||
- Fido2/Passkey 自动登录
|
||
- 密码登录回退
|
||
- 密码重试次数限制
|
||
- 完全的回调驱动（SDK不跳转页面）
|
||
|
||
## 使用方法
|
||
|
||
### 1. 引入依赖
|
||
|
||
```html
|
||
<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. 添加容器
|
||
|
||
```html
|
||
<div id="login-container"></div>
|
||
```
|
||
|
||
### 3. 初始化登录组件
|
||
|
||
```javascript
|
||
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` 配置自定义文本：
|
||
```javascript
|
||
Fido2UIManager.renderLogin({
|
||
customI18n: {
|
||
'title_login': {
|
||
'en-US': 'Custom Login',
|
||
'zh-CN': '自定义登录'
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
## 完整示例
|
||
|
||
```html
|
||
<!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()`
|