¶ 将 Guard 接入到标准 WEB 应用
更新时间: 2024-10-10 07:28:40
¶ 说明
Guard 5.0 (opens new window) 于 2022 年 8 月 17 日发布，如果你正在使用之前的版本 Guard 3.x (opens new window) 或 Guard 4.x (opens new window)，可参考：
将 Guard 接入到原生 JS 项目 (opens new window)
¶ 简介
Guard 是 Authing 提供的一种轻便的认证组件，你可以把它嵌入在你任何的 MPA（Multiple Page Application）应用中，一站式处理复杂的用户认证流程。
准备好你的原生 JavaScript 项目，跟随引导将 Authing Guard 接入到你的原生 JavaScript 项目中吧！
¶ STEP 1：创建 Authing 应用
- 使用 Authing 创建一个应用：
- 进入控制台
- 展开左侧应用菜单，点击自建应用菜单
- 点击右上角创建自建应用按钮
- 填写应用名称和认证地址、选择标准 Web 应用
- 点击创建
- 在认证配置处填写登录回调 URL和登出回调 URL
- 换取 token 身份验证方式选择 none
- 保存当前配置。
¶ STEP 2：接入 Guard
根据你的使用场景和个人偏好，在使用 Guard 时，你可以选择是否采用构建流程。
¶ 使用构建工具
npm install --save @authing/guard
使用 appId 即可初始化 Guard，更多可选参数及其应用场景可参考：GuardOptions
import { Guard } from '@authing/guard'
const guard = new Guard({
appId: 'AUTHING_APP_ID'
})
点击查看使用示例 (opens new window)，下载代码并进入对应的目录，即可快速体验 Guard 基本功能。
¶ 不使用构建工具
若不想经过构建流程就可以使用 Guard，请直接复制下面的代码到一个 HTML 文件中，并在浏览器中打开它：
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Document</title>
<script src="https://cdn.authing.co/packages/guard/5.0.4/guard.min.js"></script>
<link rel="stylesheet" href="https://cdn.authing.co/packages/guard/5.0.4/guard.min.css" />
</head>
<body>
<div id="guard"></div>
<script>
const guard = new GuardFactory.Guard({
appId: 'AUTHING_APP_ID'
})
</script>
</body>
</html>
至此，你已经完成了 Guard 的初始化，接下来你可以使用 Guard 实例来完成后续更多的操作。
¶ STEP 3：使用 Guard
Guard 提供三种登录方式，分别是嵌入模式、弹窗模式、跳转模式。
嵌入模式、弹窗模式：在指定的 DOM 中渲染一个登录框组件，通过这个组件面板可轻松完成登录、注册、找回密码、MFA 多因素认证、各种社会化登录等操作。在线体验 (opens new window)
跳转模式：Guard 完整集成并封装了 Authing 认证类 SDK，只需一行代码即可实现登录、登出、处理登录成功后的回调等能力。
使用 Guard 提供的各种 API 可拥有获取用户信息、切换语言、自定义样式等能力。
¶ 嵌入模式
使用 start 和 unmount 方法实现组件渲染和卸载。
<button id="unmount">unmount Guard</button>
<div id="guard"></div>
<script>
guard.start('#guard').then(userInfo => {
console.log(userInfo)
})
document.querySelector('#unmount').onclick = function () {
guard.unmount()
}
</script>
¶ 弹窗模式
当 Guard 初始化时的参数 mode 为 modal 时，启动窗口模式，可使用以下 API 操作 Guard 窗口的展示和隐藏。
<button id="show-guard">show Guard</button>
<button id="hide-guard">hide Guard</button>
<div id="guard"></div>
<script>
guard.start('#guard').then(userInfo => {
console.log(userInfo)
})
document.querySelector('#show-guard').onclick = function () {
guard.show()
}
document.querySelector('#hide-guard').onclick = function () {
guard.hide()
}
</script>
¶ 跳转模式
// login.html
guard.startWithRedirect()
// callback.html
guard.handleRedirectCallback().then(() => {
window.location.replace('personal.html')
})
¶ 退出登录
guard.logout()
¶ 用户注册
guard.startRegister()
¶ 判断用户登录状态
guard.checkLoginStatus().then(user => {
// 如果是未登录状态，user 为 undefined
console.log(user)
})
¶ 切换语言
<div id="change-lang">changeLang</div>
<script>
let lang = 'zh-CN'
document.querySelector('#change-lang').onclick = function () {
lang = 'zh-CN' ? 'en-US' : 'zh-CN'
guard.changeLang(lang)
}
</script>
¶ 自定义样式
<div id="change-content-css">changeContentCSS</div>
<script>
document.querySelector('#change-content-css').onclick = function () {
guard.changeContentCSS('body {background: red}')
}
</script>
¶ 启用多因素人脸识别
进入 Authing 控制台，左侧菜单选择 安全设置 -> 多因素认证，右侧开启人脸识别
在原有基础上引入 face-api，且在初始化 Guard 时传入参数 facePlugin 即可。
<script src="https://cdn.authing.co/packages/face-api/face-api.min.js"></script>
<div id="guard"></div>
<script>
const guard = new GuardFactory.Guard({
appId: 'AUTHING_APP_ID',
facePlugin: faceapi
})
</script>
¶ 示例代码
当前文档对应的完整示例代码请参考：examples (opens new window)
¶ 注册事件
使用 Guard 提供的 on 方法可以方便的注册一些实用的事件
guard.on('event-name', () => {
console.log('........')
})
常用事件列表：
| 事件名称 | 描述 | 回调参数 | 回调参数说明 |
|---|---|---|---|
| load | Guard 初始化完成，开始渲染页面 | authClient | AuthenticationClient 对象，详情请查看 authing-js-sdk (opens new window) |
| load-error | Guard 初始化失败 | error | 错误信息 |
| login | 用户登录成功 | user | 用户信息 |
| login-error | 用户登录失败 | error | 错误信息 |
| register | 用户注册成功 | user | 用户信息 |
| register-error | 用户注册失败 | error | 错误信息 |
| close | modal 模式中关闭 Guard 事件 | - | - |
¶ Guard 内置 Authing JS SDK
Guard 集成了 AuthenticationClient, 可调用 AuthenticationClient 的所有方法。
guard.getAuthClient().then(authClient => {
authClient.registerByEmail()
authClient.validateToken()
// .........
})
// ....
参考 Authentication SDK (opens new window)
¶ 常用参数列表
¶
GuardOptions
初始化 Guard 所需参数：
| 名称 | 类型 | 默认值 | 必传 | 描述 |
|---|---|---|---|---|
| appId | String | - | 是 | appId |
| mode | normal / modal | normal | 否 | Guard 组件展示模式，normal：嵌入模式，modal：窗口模式 |
| defaultScene | GuardModuleType | login | 否 | 组件默认渲染界面 |
| align | none / left / center / right | none | 否 | Guard 默认展示位置 |
| lang | zh-CN / en-US | zh-CN | 否 | 语言 |
| isSSO | Boolean | true | 否 | 是否是单点登录 |
| host | String | - | 否 | 自建应用的「认证地址」，如果是开启了单点登录，则应填写单点登录的「应用面板地址」 |
| scope | String | - | 否 | OIDC scope |
| redirectUri | String | - | 否 | 回调地址，可在 Console 控制台配置 |
| state | String | - | 否 | OIDC 状态 |
| facePlugin | FacePlugin | - | 否 | 控制台开启多因素人脸识别认证后必传 |
使用以上参数实例化 Guard，你可以体验 Guard 最基本的登录、注册等功能。
如果想拥有 Guard 的完整能力，可以配置 config 和 authClientOptions（相同参数以上表格中的值优先级更高）：
¶
config
| 名称 | 类型 | 描述 | 默认值 |
|---|---|---|---|
| target | String | 指定 Guard 表单的挂载点，接受 querySelector (opens new window) (opens new window)能接受的所有参数或者 dom 元素，若未传入，Guard 会自动生成一个 div 标签放入 body 的最后面 | - |
| mode | GuardMode | Guard 组件展示模式 | normal |
| title | String | 产品名称 | Authing 控制台中的配置 |
| logo | String | 产品 logo | Authing 控制台中的配置 |
| contentCss | String | 自定义 CSS 样式，如果指定了，会在 DOM 的 head 中插入一个 节点。如 body {background:#6699 !important;} | - |
| loginMethods | LoginMethods | 需要使用的普通登录(包括 LDAP)方式列表 | Authing 控制台中的配置 |
| registerMethods | RegisterMethods | 需要使用的注册方式 | Authing 控制台中的配置 |
| defaultRegisterMethod | RegisterMethods | 默认展示的注册方式 | Authing 控制台中的配置 |
| defaultScenes | GuardModuleType | 打开组件时展示的界面 | GuardModuleType.LOGIN |
| socialConnections | SocialConnections[] | 需要使用的社会化登录列表，如果在 Authing 控制台中没有配置，则不会显示 | Authing 控制台中的配置 |
| enterpriseConnections | Array | 需要使用的企业身份源列表(不包括 LDAP)，列表项值为配置的企业身份源唯一标识符，注意：企业身份源需要传入对应 appId 才能使用，如果在 Authing 控制台中没有配置，则不会显示 | Authing 控制台中的配置 |
| defaultLoginMethod | String | 默认显示的登录方式。可选值为 options.loginMethods 中的某一项 | Authing 控制台中的配置 |
| autoRegister | Boolean | 是否将注册和登录合并，合并后如果用户不存在将自动注册 | Authing 控制台中的配置 |
| disableRegister | Boolean | 是否禁止注册，禁止的话会隐藏「注册」入口 | Authing 控制台中的配置 |
| disableResetPwd | Boolean | 是否禁止重置密码，禁止的话会隐藏「忘记密码」入口 | Authing 控制台中的配置 |
| clickCloseable | Boolean | Modal 模式时是否隐藏登录框右上角的关闭按钮，如果隐藏，用户将不能通过点击按钮关闭登录框 | Authing 控制台中的配置 |
| escCloseable | Boolean | Modal 模式时是否可以通过键盘 ESC 键关闭登录框 | Authing 控制台中的配置 |
| isSSO | Boolean | 是否是单点登录 | Authing 控制台中的配置 |
| lang | 'zh-CN' | 使用语言，可选值为 zh-CN、en-US | 'en-US' |
| langRange | ('zh-CN'｜ 'en-US')[] | 语言切换可选的范围，如果填入空数组 或 一个项时，则不会显示语言切换按钮 | ['zh-CN', 'en-US'] |
| host | String | 自建应用的「认证地址」，如果是开启了单点登录，则应填写单点登录的「应用面板地址」 | - |
¶
GuardMode
| 键 | 值 | 说明 |
|---|---|---|
| Modal | 'modal' | 模态框模式 |
| Normal | 'normal' | 正常模式 |
¶
LoginMethods
| 键 | 值 | 说明 |
|---|---|---|
| LDAP | 'ldap' | LDAP 身份目录登录(需要配置 LDAP 服务) |
| AppQr | 'app-qrcode' | APP 扫码登录(需要接入 APP 扫码登录) |
| Password | 'password' | 账号密码登录(包括手机号 + 密码、邮箱 + 密码、用户名 + 密码。) |
| PhoneCode | 'phone-code' | 手机验证码登录 |
| WxMinQr | 'wechat-miniprogram-qrcode' | 微信 PC 小程序扫码登录 |
| AD | 'ad' | AD 用户目录登录 |
¶
RegisterMethods
| 键 | 值 | 说明 |
|---|---|---|
| 'email' | 邮箱注册 | |
| Phone | 'phone' | 手机验证码注册 |
¶
GuardModuleType
| 键 | 值 | 说明 |
|---|---|---|
| LOGIN | 'login' | 登录界面 |
| REGISTER | 'register' | 注册界面 |
¶
SocialConnections
| 键 | 值 | 说明 |
|---|---|---|
| ALIPAY | 'alipay' | 支付宝登录 |
| 'google' | 谷歌登录 | |
| WECHATPC | 'wechat:pc' | 微信 PC 登录 |
| WECHATMP | 'wechat:webpage-authorization' | 微信网页授权 |
| WECHATMOBILE | 'wechat:mobile' | 微信移动端扫码登录 |
| WECHATWORK_ADDRESS_BOOK | 'wechatwork:addressbook' | 企业微信通讯录 |
| WECHATWORK_CORP_QRCONNECT | 'wechatwork:corp:qrconnect' | 企业微信内部应用 |
| DINGTALK | 'dingtalk' | 钉钉登录 |
| 'weibo' | 微博登录 | |
| APPLE | 'apple' | Apple 登录 |
| LARK_PUBLIC | 'lark-public' | 飞书应用商店登录 |
| LARK_INTERNAL | 'lark-internal' | 飞书企业自建应用登录 |
| BAIDU | 'baidu' | 百度登录 |
| 'linkedin' | 领英登录 | |
| SLACK | 'slack' | Slack 登录 |
| YIDUN | 'yidun' | 网易易盾登录 |
| QINGCLOUD | 'qingcloud' | 青云 QingCloud 登录 |
| 'facebook' | FaceBook 登录 |
¶
authClientOptions
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| appId | String | 是 | 应用 ID |
| appHost | String | 否 | 应用完整域名，如 https://sample-app.authing.cn，不带最后的斜线 '/' |
| tenantId | String | 否 | 租户 ID |
| lang | zh-CN / en-US | 否 | 语言 |
| secret | String | 否 | 应用密钥 |
| protocol | oauth / oidc / saml / cas | 否 | 应用身份协议 |
| tokenEndPointAuthMethod | client_secret_post / client_secret_basic / none | 否 | 获取 token 端点认证方式 |
| introspectionEndPointAuthMethod | client_secret_post / client_secret_basic / none | 否 | 检查 token 端点认证方式 |
| revocationEndPointAuthMethod | client_secret_post / client_secret_basic / none | 否 | 撤回 token 端点认证方式 |
| timeout | Number | 否 | 请求超时时间 |
| websocketHost | String | 否 | Websocket 服务器域名 |
| requestFrom | String | 否 | 请求来源 |
| token | String | 否 | token |
| publicKey | String | 否 | 密码传输加密公钥 |
| privateKeys | PrivateKey[] | 否 | 用于解密 Token 的私钥 |
| onError | (code: number, message: string, data?: any): void | 否 | 错误回调函数 |