# Guard for Web

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

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

  • 登录:
  • 注册:
    • 账号密码注册;
    • 手机验证码注册;
  • 忘记密码以及重置密码;
  • MFA 认证;
  • 响应式特性(兼容移动端和 PC 端);
  • 完整的 UI 自定义功能;
  • 兼容主流前端 UI 库:
    • 原生 JavaScript 调用;
    • Vue 组件;
    • React 组件;
    • Angular 组件。

Guard demo

在线示例

# Guard for Native JavaScript

Native JavaScript,即原生 JavaScript,若你的项目没有使用 React, Vue, Angular 等框架,可通过原生 JavaScript 版本命令式调用 Guard。

# 基本使用

# 1. 通过 npm 安装使用

安装

$ yarn add @authing/native-js-ui-components

# OR

$ npm install @authing/native-js-ui-components --save

使用

import { AuthingGuard } from '@authing/native-js-ui-components'
// 引入 css 文件
import '@authing/native-js-ui-components/lib/index.min.css'

const guard = new AuthingGuard('AUTHING_USERPOOL_ID')

// 事件监听
guard.on('load', (authClient) => console.log(authClient))

# 2. 通过 cdn 引入使用

引入代码

// JavaScript 代码
<script src="https://cdn.jsdelivr.net/npm/@authing/native-js-ui-components"></script>
...
// CSS 文件
<link href="https://cdn.jsdelivr.net/npm/@authing/native-js-ui-components/lib/index.min.css" rel="stylesheet"></link>

使用

<script>
var guard = new AuthingNativeJsUIComponents.AuthingGuard("AUTHING_USERPOOL_ID")

// 事件监听
guard.on("load", authClient => console.log(authClient))
</script>

# 事件监听

Guard 会在整个声明周期中触发各种事件,如:登录成功、注册成功、登录失败...监听这些事件的方法如下:

...
// Guard 检测 userPoolId 和 appId(如果传入的话) 完成
guard.on("load", authClient => {
    console.log(authClient)
})
// 用户登录成功
guard.on("login", (user, authClient) => {
    console.log(user, authClient)
})
...

更多事件请查看完整事件列表

# API

# 构造函数 new Guard(userPoolId, config)

初始化一个新的 Guard 实例。
userPoolId 为 Authing 用户池 ID,必须传入。
config 是 Guard 的高级配置,详细请查看高级配置

# Guard 实例

Guard 实例提供了三个方法:

方法名 方法参数 功能
on

evtName: 事件名,详细请查看事件列表

Handler: 对应事件的处理函数

监听某个事件
show - modal 模式中显示表单
hide - modal 模式中隐藏表单

# 在线体验


# Guard for React

# 基本使用

# 1. 通过 npm 安装使用

安装

$ yarn add @authing/react-ui-components

# OR

$ npm install @authing/react-ui-components --save

使用

import React from 'react'
import ReactDOM from 'react-dom'
import { AuthingGuard } from '@authing/react-ui-components'
// 引入 css 文件
import '@authing/react-ui-components/lib/index.css'

const App = () => {
  const userPoolId = 'AUTHING_USERPOOL_ID'
  const config = {
    logo: 'https://usercontents.authing.cn/client/logo@2.png',
    title: 'Authing',
    socialConnections: ['github'],
  }
  const onLogin = (userInfo) => {
    console.log(userInfo)
  }
  return <Guard userPoolId={userPoolId} config={config} onLoding={onLogin} />
}

ReactDOM.render(<App />, root)

# 2. 通过 cdn 引入使用

引入代码

// JavaScript 代码
<script src="https://cdn.jsdelivr.net/npm/@authing/vue-react-components"></script>
...
// CSS 文件
<link href="https://cdn.jsdelivr.net/npm/@authing/vue-react-components/lib/index.min.css" rel="stylesheet"></link>

使用

<script>
var App = () => {
    const userPoolId = "AUTHING\_USERPOOL\_ID"
    const config = {
    logo: "https://usercontents.authing.cn/client/logo@2.png",
    title: "Authing",
    socialConnections: ['github'],
  }
  const onLogin = (userInfo) => {
    console.log(userInfo)
  }
    return <AuthingReactUIComponents.AuthingGuard userPoolId={userPoolId} config={config} onLogin={onLogin} />
}

ReactDOM.render(<App />, root);
</script>

# 参数

参数名 说明 是否必传 默认值
userPoolId 用户池 ID -
config Guard 高级配置,同高级配置,注意,这里无需 传入 target 参数 -
visible modal 模式时表单是否可见 ·

# 事件监听

所有事件请查看事件列表,注意在 React 中,事件监听应采用小驼峰命名,如:onLogin, onLoginError

# 在线体验


# Guard for Vue

# 基本使用

# 1. 通过 npm 安装使用

安装

$ yarn add @authing/vue-ui-components

# OR

$ npm install @authing/vue-ui-components --save

使用

<template>
<AuthingGuard :userPoolId="userPoolId" :config="config" @register="handleRegister" />
</template>
<script>
import { AuthingGuard } from "@authing/vue-ui-components"

export default {
  components: {
    AuthingGuard
  },
  data() {
    return {
      userPoolId: "AUTHING\_USER\_POOL\_ID",
      config: {
        socialConnections: ['github'],
        logo: "https://usercontents.authing.cn/client/logo@2.png",
        title: "Authing",
      },
    };
  },
  methods: {
    handleRegister(*user*) {
      console.log(user)
    }
  },
};
</script>

# 2. 通过 cdn 引入使用

引入代码

// JavaScript 代码
<script src="https://cdn.jsdelivr.net/npm/@authing/vue-ui-components"></script>
...
// CSS 文件
<link href="https://cdn.jsdelivr.net/npm/@authing/vue-ui-components/lib/index.css" rel="stylesheet"></link>

使用

<script>
const userPoolId = "AUTHING\_USERPOOL\_ID"
const config = {
  logo: "https://usercontents.authing.cn/client/logo@2.png",
  title: "Authing",
  socialConnections: ['github'],
}

const app = new Vue({
  el: "#app",
  render: h => h(AuthingVueUIComponents.AuthingGuard, {
      props: {
      userPoolId,
      config,
    }
  }),
})
</script>

# 参数

参数名 说明 是否必传 默认值
userPoolId 用户池 ID -
config Guard 高级配置,同高级配置,注意,这里无需 传入 target 参数 -
visible modal 模式时表单是否可见 ·

# 事件监听

所有事件请查看事件列表,监听方式为 @login @login-error 等

# 在线体验


# Guard for Angular

# 基本使用

# 1. 通过 npm 安装使用

安装

$ yarn add @authing/ng-ui-components

# OR

$ npm install @authing/ng-ui-components --save

使用

// app.module.ts
import { BrowserModule } from '@angular/platform-browser'
import { NgModule } from '@angular/core'
import { AuthingGuardModule } from '@authing/ng-ui-components'
import { AppComponent } from './app.component'
@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, AuthingGuardModule],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

// app.component.ts
import { Component } from '@angular/core'
import {
  CommonMessage,
  AuthenticationClient,
} from 'ng-ui-components'
@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss'],
})
export class AppComponent {
  title = 'demo'
  userPoolId = '59f86b4832eb28071bdd9214'
  onLoad(e: AuthenticationClient) {
    console.log('ffffff', *e*)
  }
}

// app.component.html
<authing-guard [userPoolId]="userPoolId" (onLoad)="onLoad($event)"></authing-guard>

# 2. 通过 cdn 引入使用

引入代码

<script src="https://cdn.jsdelivr.net/npm/@authing/ng-ui-components"></script>

使用

<div ng-app="">
  <authing-guard [userPoolId]="AUTHING_USER_POOL_ID"></authing-guard>
</div>

# 参数

参数名 说明 是否必传 默认值
userPoolId 用户池 ID -
config Guard 高级配置,同 #配置,注意,这里无需 传入 target 参数 -
visible modal 模式时表单是否可见 ·

# 事件监听

所有事件请查看事件列表,监听方式为小驼峰命名,如 onLogin, onLoginError

# 在线示例


# 展示方式

Guard 目前有两种展示方式 modal | normalnormal 方式会将表单插入指定的 dom 节点,适合将登陆作为单独页面的场景,modal 模式会以模态框形式展示表单,适合在已有页面中弹出进行登录。默认展示方式为 normal,可通过传入 mode 参数配置展示方式:

import { AuthingGuard, GuardMode } from '@authing/native-js-ui-components'
// 引入 css 文件
import '@authing/native-js-ui-components/lib/index.min.css'

const guard = new AuthingGuard('AUTHING_USERPOOL_ID', {
  mode: GuardMode.Modal,
})

// modal 模式需要调用 show 方法才会展示表单
guard.show()

注意:native js 版本的 modal 模式需要在初始化后手动调用 guard.show() 才会展示 Guard。

# SSO 场景

单点登录(Single Sign On),简称为 SSO,是目前比较流行的企业业务整合的解决方案之一。SSO 的定义是在多个应用系统中,用户只需要登录一次就可以访问所有相互信任的应用系统。
随着企业发展,你的公司可能会采购各种 SaaS 软件、OA 系统、ERP 系统等,虽然这些软件提高了办公效率,单每个系统都需要单独登录就会显得非常繁杂,这时你就可以在 Authing 中注册一个应用作为 SSO 身份提供者,在同一浏览器中只需登录一次,就可访问所有系统。使用 Guard 进行 SSO 登录的方法如下:

...
const guard = new AuthingGuard("AUTHING_USERPOOL_ID", {
  appId: "AUTHING_APP_ID", // 需要作为单点登录身份服务的应用 ID
  appDomain: "xxx.authing.cn", // 单点登录应用的域名
  isSSO: true, // 表示开启 SSO 模式
})
...

通过传入 appId, appDomain, isSSO 就可开启 SSO 登录模式,Guard 会在 load 事件之后检测是否已有用户登录此应用,若有会直接触发 login 事件,方便你进行下一步操作。

# 高级配置

Guard 提供了很多高级配置,如自定义 UI,使用特定登录方式等。所有配置如下:

参数名 参数说明 类型 是否必传 默认值
target 指定 Guard 表单的挂载点,接受 querySelector (opens new window) 能接受的所有参数或者 dom 元素,若未传入,Guard 会自动生成一个 div 标签放入 body 的最后面 String HTMLElement
mode Guard 展示模式 GuardMode GuardMode.Normal
title 产品名称 String Authing
logo 产品 logo String [Authing logo]
contentCss 自定义 CSS 样式,如果指定了,会在 DOM 的 head 中插入一个 节点。如 body {background:#6699 !important;}。 String -
loginMethods 需要使用的普通登录(包括 LDAP)方式列表 LoginMethods[] [LoginMethods.PhoneCode, LoginMethods.Password]
registerMethods 需要使用的注册方式 RegisterMethods[] [RegisterMethods.Email, RegisterMethods.Phone]
defaultRegisterMethod 默认展示的注册方式 RegisterMethods _RegisterMethods.Email*
defaultScenes 打开组件时展示的界面 GuardScenes _GuardScenes.Login*
socialConnections 需要使用的社会化登录列表 SocialConnections[] []
enterpriseConnections 需要使用的企业身份源列表(不包括 LDAP),列表项值为配置的企业身份源唯一标识符,注意:企业身份源需要传入对应 appId 才能使用 Array []
defaultLoginMethod 默认显示的登录方式。可选值为 options.loginMethods 中的某一项

String

LoginMethods.Password
autoRegister 是否将注册和登录合并,合并后如果用户不存在将自动注册 Boolean false
disableRegister 是否禁止注册,禁止的话会隐藏「注册」入口 Boolean false
disableResetPwd 是否禁止重置密码,禁止的话会隐藏「忘记密码」入口
clickCloseable Modal 模式时是否隐藏登录框右上角的关闭按钮,如果隐藏,用户将不能通过点击按钮关闭登录框 Boolean true
escCloseable Modal 模式时是否可以通过键盘 ESC 键关闭登录框 Boolean true
isSSO 是否是单点登录 Boolean false
appId 应用 ID String SSO 模式时必传 -
appDomain SSO 模式时的 app 域名 String SSO 模式时必传 -
qrCodeScanOptions 扫码登录配置,详情请查看 QrCodeAuthenticationClient().startScanning(domId, options) (opens new window) 的 options 参数 Objcect null
apiHost 私有部署时的 API 请求地址 String 私有部署时必传 [Authing 官方 api 地址]

# 类型说明

以下为高级配置中可能用到的所有枚举值的说明:

# GuardMode

Guard 展示方式

key value 说明
Modal 'modal' 模态框模式
Normal 'normal' 正常模式

# LoginMethods

Guard 支持的普通登录方式

key value 说明
LDAP 'ldap' LDAP 身份目录登录(需要配置 LDAP 服务 (opens new window))
AppQr 'app-qrcode' APP 扫码登录(需要接入 APP 扫码登录 (opens new window))
Password 'password' 账号密码登录(包括手机号 + 密码、邮箱 + 密码、用户名 + 密码。)
PhoneCode 'phone-code' 手机验证码登录
WxMinQr 'wechat-miniprogram-qrcode' 微信小程序扫码登录
AD 'ad' AD 用户目录登录

# RegisterMethods

Guard 支持的注册方式

key value 说明
Email 'email' 邮箱注册
Phone 'phone' 手机验证码注册

# GuardScenes

Guard 可展示的界面

key value 说明
Login 'login' 登录界面
Register 'register' 注册界面

# ResetPwdMethods

Guard 支持的重置密码方式

key value 说明
Email 'email' 邮件验证码重置
Phone 'phone' 手机短信验证码重置

# SocialConnections

Guard 支持的社会化登录方式

key value 说明
Qq 'qq' QQ 登录
Weibo 'weibo' 新浪微博登录
Alipay 'alipay' 支付宝登录
Github 'github' GitHub 登录
Google 'google' Google 账号登录
WxPc 'wechat:pc' 微信 PC 端登录
Dingtalk 'dingtalk' 钉钉登录
WxMobile 'wechat:mobile' 微信移动端登录
WxWCorpQr 'wechatwork:corp:qrconnect' 企业微信二维码登录
WxWebAuth 'wechat:webpage-authorization' 微信网页授权登录
WxMinApp 'wechat:miniprogram:app-launch' App 拉起小程序登录
WxMinDefault 'wechat:miniprogram:default' 微信小程序登录
WxWSPQr 'wechatwork:service-provider:qrconnect' 企业微信第三方应用扫码授权登录
WxWSPAuth 'wechatwork:service-provider:authorization' 企业微信第三方应用网页授权登录

# 事件

Guard 所有事件列表如下:

事件名 事件说明 事件参数 事件参数说明
load Authing userPoolId 和 appId(有 appId 时) 验证通过,加载完成 authClient AuthenticationClient 对象,可直接操作 login, register,详情请查看 authing-js-sdk (opens new window)
load-error Authing userPoolId 验证失败,加载失败 error 错误信息
login 用户登录成功 user, authClient

user: 用户信息

authClient 同上

login-error 用户登录失败 error 错误信息,包含字段缺失/非法或服务器错误等信息
register 用户注册成功 user, authClient

user: 用户信息

authClient 同上

register-error 用户注册失败 error 错误信息,包含字段缺失/非法或服务器错误等信息
pwd-email-send 忘记密码邮件发送成功 - -
pwd-email-send-error 忘记密码邮件发送失败 error 错误信息
pwd-phone-send 忘记密码手机验证码发送成功 - -
pwd-phone-send-error 忘记密码手机验证码发送失败 error 错误信息
pwd-reset 重置密码成功 - -
pwd-reset-error 重置密码失败 error 错误信息
close modal 模式中 guard 关闭事件 - -