Add SSO and device management samples
This commit is contained in:
dqj
270
docs/LOGIN_SDK.md
Normal file
270
docs/LOGIN_SDK.md
Normal file
@@ -0,0 +1,270 @@
|
||||
# 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()`
|
||||
Reference in New Issue
Block a user