Guard for Web

PreviousAPI（GraphQL）Next自定义 Guard 的 UI 样式

Last updated 4 years ago

Was this helpful?

Guard for Web

Guard 是一种可嵌入的登录表单，可根据你的需求进行配置，建议用于单页面应用程序。它使你可以轻松添加各种社会化登录方式，以便你的用户可以无缝登录，并且在不同平台拥有一致的登录体验。

该表单拥有以下基本功能：

邮箱-密码/手机-验证码/认证；
忘记密码以及重置密码；
记住账号功能（加密存储到浏览器本地）；
社会化登录，如 Github 登录、微信登录（）；
小程序扫码登录（）；
响应式特性（兼容移动端和 PC 端）；
使用 LDAP 登录（）；
完整的 UI 自定义功能。

使用方法

1. 引入代码

通过 CDN 安装

<script src="https://cdn.jsdelivr.net/npm/@authing/guard/dist/Guard.umd.min.js"></script>

通过 npm 安装

$ npm install @authing/guard --save

移动端

如果你的用户定位为移动用户，Authing 建议你将以下标签添加到应用程序的头部：

<meta name="viewport" content="width=device-width, initial-scale=1"/>

2. 显示表单

首先，你需要初始化一个新的 Guard 对象，并提供 Authing UserPoolId（每个 Authing 应用的唯一用户池 ID，你可以从控制台中获取），如下所示：

const form = new Guard('AUTHING_USERPOOL_ID');

完成这两步后就可以使用表单了。

3. 监听登录事件以获取用户信息

你可以使用 .on 方法监听 Guard 的事件，如：

// 使用 `.on` 方法，并监听 `login` 事件即可在用户登录成功后获得用户信息
form.on('login', (userInfo) => {
  localStorage.setItem('userInfo', JSON.stringify(userInfo));
  localStorage.setItem('token', JSON.stringify(userInfo.token));
});

4. 验证 JWT Token 的合法性以及是否过期

使用小程序扫码认证

处理回调事件

初始化 Guard 后可监听 scanned-success 事件取回用户信息，如下所示：

const form = new Guard('AUTHING_USERPOOL_ID');

form.on('scanned-success', (userInfo) => {
  // 使用 userInfo 以及 userInfo.token 等信息
});

非 SSO 场景

开发者直接从 Authing 的用户池中获取用户数据，不走 OAuth、OIDC 等协议流程。如果用户登录成功，你将在前端直接获取到他的数据。Guard 此场景下用于为开发者快速生成登录表单 UI，快速接入用户系统。上一节内容讲述的使用方法就是非 SSO 场景，以下是完整示例：

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <title>Guard Example</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.jsdelivr.net/npm/@authing/guard/dist/Guard.umd.min.js"></script>
</head>
<body>

    <div id="my-form"></div>

    <script>
        const userPoolId = "YOUR_AUTHING_USERPOOL_ID";
        const guard = new Guard(userPoolId, {
            logo: "https://usercontents.authing.cn/client/logo@2.png",
            title: "Authing",
            // 把表单插入到 id 为 my-form 的标签
            mountId: "my-form",
        });
        guard.on("authenticated", userInfo => {
            // 用户登录成功后，你可以直接在这里获取他的用户信息
            console.log(userInfo);
        });
        guard.on("register", userInfo => {
            // 用户注册成功后，你可以直接在这里获取他的用户信息
            console.log(userInfo);
        });
        guard.on("scanned-success", userInfo => {
            // 用户扫码登录成功后，你可以直接在这里获取他的用户信息
            console.log(userInfo);
        });
    </script>
</body>
</html>

SSO 场景

作为 IdP（身份提供商），对外提供身份服务，Guard 此场景下用于 IdP 确认用户身份。支持的协议有 OAuth 2.0，OIDC，SAML，LDAP。

作为与其他 IdP 通信的客户端，Guard 此场景下充当 SP 和其他 IdP 通信，用于完成相应登录协议发起授权的环节，例如向其他 SAML IdP 发送 SAML Request请求。

部署示例：

<!DOCTYPE html>
<html lang="zh-cn">
  <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" />
    <link rel="icon" href="https://fe-static.authing.cn/dist/favicon.png" />
    <title>Authing SSO</title>
  </head>
  <body>
    <noscript>
      <strong>We're sorry but sso doesn't work properly without JavaScript enabled.
        Please enable it to continue.</strong>
    </noscript>
    <script src="https://cdn.jsdelivr.net/npm/@authing/guard/dist/Guard.umd.min.js"></script>
    <script>
      var appId = "YOUR_AUTHING_SSO_APPID";
      var userPoolId = "YOUR_AUTHING_USERPOOL_ID";
      var domain = "example.authing.cn";
      const guard = new Guard(userPoolId, {
        appId,
        domain,
        hideClose: true,
        isSSO: true,
        SSOHost: location.origin,
        qrcodeScanning: {
          redirect: false
        },
        host: {
          user: "私有部署的内部地址",
          oauth: "私有部署的内部地址"
        }
      });
    </script>
  </body>
</html>

用户自行修改资料

在 SSO 应用的用户认证页面，用户可以修改自己的资料。

对于使用云上 SaaS 的用户，可以访问以下链接，进入个人资料修改页面：

https://<appDomain>.authing.cn/login/profile

其中 <appDomain> 是你的 SSO 应用的二级域名。

如果用户未登录，会先要求用户登录再进入个人中心；对于已登录的用户则会直接进入个人中心。

API

构造函数 new Guard(userPoolId, options)

初始化一个新的 Guard 实例。SSO 场景和非 SSO 场景下传参方式有所不同。

非 SSO 场景

只需提供用户池 id。

userPoolId: 用户池 id

SSO 场景

供私有化部署用户参考，SaaS 用户无需操心 Guard SSO 场景部署。

userPoolId: 用户池 id
options.appId {String}: Authing SSO 应用的 appId；
options.domain {String}: Authing SSO 应用的域名. 通常是 <appDomain>.authing.cn；
options.passwordEncPublicKey {String}: PEM 格式密码加密公钥，默认为 Authing 官方的加密公钥。私有化部署用户需要传入自己的加密公钥。

authing 对象

authing-load 事件是 Authing 对象初始化后的回调事件。

guard.on('authing-load', (authing) => {
  console.log('Authing 实例初始化成功', authing);

  // authing.login
  // authing.register
  // authing.logout
  // authing.checkLoginStatus
  // ...
  // 更多请参考：https://docs.authing.cn/authing/sdk/authing-sdk-for-web
});

显示和隐藏表单

Guard 提供了两个方法用以操作界面的显示和隐藏，方法名见下表：

方法名称

方法参数

功能

show

mountId

指定 Guard 将在何处显示，接受一个 html 元素 id，不含#号。不指定则默认全屏弹出 Modal 登录框

hide

无

隐藏表单

在初始化完构造函数后会自动执行 show 方法，如：

const form = new Guard('AUTHING_USERPOOL_ID', { ... });
form.hide();

自定义选项

Guard 的构造函数 Guard 的第二个参数提供了一些高级功能。

以下是完整的参数列表：

参数名称

是否必填

默认值

类型

参数说明

nonce

否

[Random]

Number

随机数，用于防范网络攻击

timpstamp

否

当前时间戳

Number

初始化时的时间戳，用于防范网络攻击

mountId

否

无

String

指定 Guard 表单将在何处显示，接受一个 html 元素 id，不含 # 号。不指定则默认全屏弹出 Modal 登录框

title

否

Authing

String

产品名称

logo

否

[Authing LOGO]

String

产品logo，默认为 Authing 的官方 Logo

forceLogin

否

false

Boolean

是否将注册和登录合并，合并后如果用户不存在将自动注册

hideQRCode

否

false

Boolean

是否隐藏小程序扫码登录，在开发者在 Authing 控制台开启小程序扫码登录后，若此项为 true 将不显示小程序扫码登录

hideUP

否

false

Boolean

是否隐藏用户名-密码登陆，隐藏后将不显示用户名-密码登录框

hideUsername

否

false

Boolean

是否隐藏注册时的用户名填写，隐藏后将不显示用户名输入框

hideRegister

否

false

Boolean

是否隐藏注册框，隐藏后将不显示注册框

hideSocial

否

false

Boolean

是否隐藏社会化登录，在开发者在 Authing 控制台开启社会化登录后，若此项为 true 将隐藏全部社会化登录

hideClose

否

false

Boolean

是否隐藏登录框右上角的关闭按钮，如果隐藏，用户将不能通过点击按钮或按 ESC 关闭登录框

placeholder

否

{}

Object

定制输入框的 paceholder

placeholder.username

否

请输入用户名

String

定制输入框的 paceholder

placeholder.email

否

请输入邮箱

String

用户名输入框的 paceholder

placeholder.password

否

请输入密码

String

邮箱输入框的 paceholder

placeholder.confirmPassword

否

请确认密码

String

密码输入框的 paceholder

placeholder.verfiyCode

否

请输入验证码

String

验证码输入框的 paceholder

placeholder.newPassword

否

请输入新密码

String

新密码输入框的 paceholder

placeholder.phone

否

请输入手机号

String

手机号输入框的 paceholder

placeholder.phoneCode

否

4 位验证码

String

手机验证码输入框的 paceholder

qrcodeScanning

否

{}

Object

小程序扫码登录的配置项

qrcodeScanning.redirect

否

true

Boolean

是否执行跳转（在用户后台配置的URL），若值为false，用户数据会通过 onSuccess 回调函数返回

qrcodeScanning.interval

否

1500

Number

每隔多少秒检查一次是否扫码，默认1500

qrcodeScanning.tips

否

使用微信或小程序身份管家扫码登录

String

提示信息，可写HTML

以下供私有部署用户查看

参数名称

是否必填

默认值

类型

参数说明

useSelfWxapp

否

false

Boolean

是否使用私有部署的小程序提供二维码，此选项仅供私有部署用户使用

host

否

{}

Object

GraphqlQL 通讯地址配置项

host.user

否

[Authing 官方链接]

String

GraphQL 链接，默认 Authing 官方链接，此处用于私有部署 Authing 的用户使用

host.oauth

否

[Authing 官方链接]

String

GraphQL 链接，默认 Authing 官方链接，此处用于私有部署 Authing 的用户使用

appId

是

无

String

SSO 应用的云上 ID

domain

否

无

String

SSO 类应用云上域名

protocol

否

oauth

String

用于显示指定 SSO 应用类型，可选值为 oauth、oidc、saml

SSOHost

否

String

SSO 类应用的通讯地址，默认 Authing 官方链接，此处用于私有部署 Authing 的用户使用

isSSO

否

false

Boolean

用于标识当前是否为 SSO 模式，如果只是想简单生成登录表单，使用默认 false 即可

回调事件 on(event, callback)

在初始化 Guard 后，可使用 on方法，如：

const form = new Guard('AUTHING_USERPOOL_ID');
form.on('login', function(user) {
    // 成功登录后的回调事件，参数 user 为用户数据
});

Guard 会在以下生命周期中触发相应事件，完整的事件列表如下：

事件名称

事件说明

事件参数

事件参数说明

authing-load

Authing UserPool ID 验证通过，加载完成

authing

authing 对象，可直接操作 login,register 等方法

authing-unload

Authing UserPool ID 验证失败

error

错误信息

social-load

社会化登录列表加载完成

oauthList

完整的 OAuth 列表，若用户未在后台配置过则为空

social-unload

社会化登录列表加载失败

error

错误信息

用户登录成功

user

用户数据

用户登录失败

error

错误信息，包含字段缺失／非法或服务器错误等信息

用户注册成功

user

用户数据

用户注册失败

error

错误信息，包含字段缺失／非法或服务器错误等信息

email-sent

忘记密码邮件发送成功

data

发送的结果

email-sent-error

忘记密码邮件发送失败

error

错误信息

reset-password

重置密码成功

data

重置密码结果

reset-password-error

重置密码失败

error

错误信息

scanned-success

扫码登录成功

user

用户数据

scanned-error

扫码登录失败

error

错误信息

scanning-interval-starting

开始监听扫码事件

interval

用户可使用 clearInterval 停止监听

form-closed

Guard 关闭事件

null

用户按下 ESC 或点击右上方的关闭按钮后会触发此事件

接下来你可能还需要

对比与自己开发 UI 的优势以理解为什么要使用 Guard：

PreviousAPI（GraphQL）Next自定义 Guard 的 UI 样式

Last updated 4 years ago

Was this helpful?