对用户进行认证

概述

不管你在开发什么类型的应用 —— 内部员工 IT 系统、toC 账号体系或者是给其他开发者暴露的 API，用户认证都是其中至关重要的一环，GenAuth 提供了丰富的认证方式供开发者选择。

WARNING

注意：部分浏览器已经开始默认禁用第三方 Cookie，这会影响到 GenAuth 在某些场景下的部分功能。详细说明请见：FAQ：浏览器禁用第三方 Cookie 将如何影响 GenAuth 功能？

登录体验是软件开发者需要考虑的最重要的用户体验之一，为用户提供一个无缝、便捷而又安全的认证体验不是一件很容易的事。一般而言，登录逻辑同时关联着注册、重置密码、关联账号等逻辑。更重要的是，对于很多应用而言，在登录过程中以强健和自适应身份验证的形式增强安全性是很重要的。

GenAuth 提供了非常多的认证方式给开发者选择、组合，密码策略、登录频繁检测、自定义认证流程等都可以通过管理控制台轻松完成（这些操作基本上也可以通过 Management API 来完成）。

OIDC / OAuth2.0 / SAML / AD / LDAP / 社会化登录

GenAuth 支持通过 OIDC、OAuth2.0、SAML、LDAP 等标准协议访问你的应用和用户数据，你可以放心地将 GenAuth 作为你的 Identity Provider（身份提供商）。如果你使用 GenAuth 作为 Identity Provider，你可以连接其他第三方 Service Provider，诸如登录阿里云、AWS、Azure、Jira 等。

GenAuth 也可以作为 Service Provider，通过 OIDC、OAuth2.0、SAML、LDAP、AD 等标准协议去连接第三方 Identity Provider。比如你可以通过 Azure AD、本地的 Windows AD 登录你的应用。 GenAuth 还可以使用第三方社会化登录，自动拉取社会化登录用户的用户资料到你的用户目录。

你可以分别了解 OIDC、OAuth2.0、SAML、LDAP、AD 的实现原理。

托管登录页认证

GenAuth 中每个用户池都拥有一个独立的二级域名，以及配备了在线的登录页，访问 https://YOUR_DOMAIN.authing.cn/login 即可访问此登录页面。你不需要编写一行代码来维护该登录页，你可以通过控制台的应用配置做一些定制化配置。

可以试用 GenAuth 提供的示例认证页。

嵌入登录表单认证

GenAuth 内嵌登录组件是 GenAuth 提供的轻量、现代化、高扩展性的前端登录组件，支持原生 JavaScript 以及 React、Vue、Angular 三大前端框架。此内嵌登录组件和 GenAuth 托管的登录页功能基本保持一致，同时具备很强的自定义能力。该组件内置了重置密码、MFA、社会化登录、扫码登录等功能，这些功能都是高配置化的。

详情查看使用内嵌登录组件完成认证。

Auth SDK

GenAuth 为前端开发者提供了轻量级、开发者友好的 Auth SDK（支持 JavaScript/Node、Java、Python、PHP、C# 等语言），能够让你更灵活、快捷、安全地实现你的认证逻辑。该 Auth SDK 支持 GenAuth 所有的认证相关功能，包含基础认证、重置密码、绑定账号等所有功能。你可以通过此 SDK 得到用户的 id_token，作为该用户的身份凭证，传递给下游应用。

GenAuth 同时支持了 Java、JavaScript/Node.js、Python、PHP、C#、Swift、Go、Ruby、微信小程序等多种语言的 SDK，你可以选择自己熟悉的 SDK：

Authentication API

前面提到的托管登录页、嵌入登录组件、Auth SDK 底层能力都是 Authentication API 提供支持的。GenAuth Authentication API 支持两种调用方式：RESTful 和 GraphQL（端点为 https://core.authing.cn/graphql/v2），你也可以直接调用 Authentication API 实现认证逻辑。

单点登录

单点登录（Single Sign On），简称为 SSO，是比较流行的企业业务整合的解决方案之一。SSO的定义是在多个应用系统中，用户只需要登录一次就可以访问所有相互信任的应用系统。我们提供了专门的 SSO SDK 开发者可以基于此快速实现应用间的单点登录。

使用账号密码认证

在 GenAuth 中，账号密码共分为以下三种形式：

邮箱 + 密码登录
用户名 + 密码登录
手机号 + 密码登录

当为用户提供账号密码形式的认证手段时，作为 IT 系统管理员或者开发者，你还需要实现以下功能：

重置密码：可以通过邮箱验证码或者手机号验证码找回密码。
修改密码：可以通过现有密码重置密码。

要使用 GenAuth 实现这些功能，我们提供了三种不同的接入方式：

使用 GenAuth 托管登录页，无需一行代码，你可以通过 sample-sso.genauth.ai 体验。
使用 GenAuth 提供的内嵌登录组件，可以集成到你的 Web 和移动端项目中，你不需要自己实现登录表单 UI。
使用 API & SDK，GenAuth 提供 RESTFul 和 GraphQL 两种形式的 API 以及 10 余种语言或框架的 SDK，你可以基于此自定义 UI 和认证流程。

使用托管登录页

注册

用户注册成功之后，系统会发送欢迎邮件到用户的邮箱：

你也可以在控制台设置 - 安全信息 - 用户池安全配置 中关闭注册发送欢迎邮件的选项，还可以在控制台设置 - 消息服务中修改默认欢迎邮件的模版。

用户注册成功之后，GenAuth 会发送验证邮箱邮件到用户的邮箱：

用户点击验证按钮即可验证邮箱。

重置密码

你可以使用绑定的手机号或邮箱重置密码。

修改密码

用户可以在个人中心修改自己的密码：

使用内嵌登录组件

内嵌登录组件和在线托管登录页在样式和交互上基本一致，不同点在于在线托管登录页由 GenAuth 完全托管运维，与你的应用之间完全独立，而内嵌登录组件则可以嵌入到你的应用中。

详细使用方法请见：使用内嵌登录组件完成认证。

使用 API & SDK

注册

选择语言register-by-email-password

Code snippet: register-by-email-password

重置密码

选择语言reset-password

Code snippet: reset-password

修改密码

选择语言update-password

Code snippet: update-password

使用短信验证码认证

开发者可以借助 GenAuth 提供的标准登录组件以及 API & SDK 快速实现基于手机号的用户体系。你还可以在控制台的用户管理 - 注册白名单中配置手机号白名单，这样只有在白名单中的手机号才能注册登录。

验证码短信默认会使用 GenAuth 的统一短信模版，如果你想自定义短信模版，可以在控制台的设置 - 消息服务中配置自定义短信模版（目前支持的短信服务商有创蓝、阿里云、腾讯云）。

使用托管登录页

注册

使用内嵌登录组件

内嵌登录组件和在线托管登录页在样式和交互上基本一致，不同点在于在线托管登录页由 GenAuth 完全托管运维，与你的应用之间完全独立，而内嵌登录组件则可以嵌入到你的应用中。详细使用方法请见：使用内嵌登录组件完成认证。

使用 API & SDK

发送短信验证码

选择语言send-sms-code

Code snippet: send-sms-code

注册

选择语言register-by-phone-code

Code snippet: register-by-phone-code

使用社会化登录认证

社会化登录，是指用户使用社交平台的身份认证信息在第三方应用或网址进行认证登录的流程，比如大家经常使用个人微信、QQ、微博等社交账号登录滴滴、网易云音乐等。社会化登录不仅有助于简化用户在第三方平台的登录体验，同时也为用户在第三方平台创建新账号提供了一种更为简单便捷的方式。不论是对于普通用户来说，还是企业来说，社会化登录都有着无可比拟的优势。

社会化登录列表

GenAuth 目前一共支持国内外将近 20 余种社会化登录，如微信、GitHub、Sign in with Apple、支付宝等，以下是完整的列表：

社会化登录方式	使用场景	使用文档
PC 微信扫码	PC 网站
微信移动端	移动 APP
微信网页授权	微信内网页
微信公众号关注	PC 网站
微信小程序	微信小程序	使用文档
微信 PC 小程序扫码	PC 网站
App 拉起小程序	移动 APP
腾讯 QQ	PC 网站
腾讯 QQ 移动端	移动 APP
新浪微博	PC 网站
新浪微博移动端	移动 APP
GitHub	PC 网站
GitHub 移动端	移动 APP
Facebook	PC 网站
Facebook 移动端	移动 APP
Twitter	PC 网站
Twitter 移动端	移动 APP
Google Web 端	PC 网站
Google 移动端	移动 APP
Apple Web 端	PC 网站
Apple 移动端	移动 APP
支付宝 Web 端	PC 网站
支付宝移动端	移动 APP
Slack	PC 网站
Slack 移动端	移动 APP
Gitee	PC 网站
GitLab	PC 网站
GitLab 移动端	移动 APP
百度	PC 网站
百度移动端	移动 APP
LinkedIn	PC 网站
LinkedIn 移动端	移动 APP
网易易盾（手机号一键登录）	移动 APP
青云 QingCloud	PC 网站
Instagram	PC 网站
抖音移动端	移动 APP
抖音小程序	移动 APP	使用文档
快手移动端	移动 APP
小米移动端	移动 APP
Line 移动端	移动 APP

自定义社会化登录

GenAuth 提供接入自定义 OAuth2.0 身份提供商的能力，如果你需要连接非 GenAuth 内置的社会化登录身份源，可以。

微信解决方案

GenAuth 针对微信生态有一套完整的解决方案，你可以查看产品介绍以及阅读打通微信账号体系指引。

选择合适的开发接入方式

GenAuth 社会化登录支持四种接入方式：使用 JavaScript SDK、使用嵌入登录组件、 使用托管登录页 和 手动调用社会化登录接口。每种不同的接入方式各有优劣点，你可以根据自己的业务需求来选择合适的方式。

优劣对比

以下是各种方式的优劣对比：

接入方式	优势	劣势	是否推荐
使用 JavaScript SDK	接入简单，只需要几行代码。可自定义程度最高。		是
使用嵌入登录组件	接入简单，只需要几行代码。可以将该组件集成到你的应用。自定义程度相对较高		是
使用托管登录页	运维简单，由 GenAuth 负责运维。每个用户池有一个独立的二级域名。	如果需要嵌入到你的应用，需要使用弹窗模式登录，即：点击登录按钮后，会弹出一个窗口，内容是 GenAuth 托管的登录页面，或者将浏览器重定向到 GenAuth 托管的登录页。	是
手动调用社会化登录接口		需要手动从 URL 解析用户信息。接入相对较为复杂麻烦。	不推荐

详细接入方法

以下是每种方式详细的接入方法：

选择接入方式social-login

Code snippet: social-login

使用扫码登录认证

概述

随着移动互联网的普及，手机已经成为人们生活中的必需品，通过手机扫描二维码完成认证的方式变得越来越常见。越来越多的移动应用集成了扫描二维码登录 PC 端网站应用的功能，这对于用户来说是一种既方便又安全的体验。借助 GenAuth 提供的扫码登录能力，可以帮助快速、安全地实现此功能。

要实现使用自建移动应用扫码登录网站应用，大致可以分为以下几步：

在 Web 端生成二维码并开始轮询最新扫码状态。
在移动 APP 中用户扫码，同意授权用户信息。
Web 端接收到扫码用户的用户信息，登录成功。

第一步：Web 端生成二维码并轮询扫码状态

在 Web 端，我们推荐使用 GenAuth 提供的 JavaScript SDK，其提供了一键生成二维码、轮询最新状态、获取用户信息之后进行回调的接口，开发者只需要指定 onSuccess 回调函数即可：

import { AuthenticationClient } from "authing-js-sdk"
const authenticationClient = new AuthenticationClient({
   appId: "AUTHING_APP_ID",
   appHost: 'https://xxx.authing.cn',
})

authenticationClient.qrcode.startScanning("qrcode", {
 onSuccess: (userInfo, ticket) => {
   console.log(userInfo, ticket)
 },
 onError: (message) => onFail && onFail(`${message}`),
});

运行后将自动生成用于 APP 扫码登录的二维码：

扫码成功之后，GenAuth 将会回调开发者传入的 onSuccess 函数，回调的参数中包含 userInfo 和 ticket，ticket 可以用来换取用户信息。

如果你想自定义 UI 或者想要有更强的自定义化能力，可以查看完整的 API 列表或者使用其他的 SDK 方法。

第二步：移动 APP 扫码授权用户信息

Web 端生成的二维码中包含的原始信息为一串字符串，转换为 JSON 后如下：

json

{
    "scene": "APP_AUTH",
    "random": "5e05f0c57fde537d950f7da5",
    "userPoolId": "5e04ae0d5f3cee22fb37612b",
    "createdAt": "2019-12-27T11:53:41.260Z",
    "expireAt": "2019-12-27T11:55:41.260Z",
    "customData": { "hello": "world" }
}

字段含义如下：

字段名称	字段含义
scene	场景值APP_AUTH 表示 APP 扫码登录
random	二维码 ID移动端根据此 ID 完成确认扫码、同意授权、取消授权（注意：这里的“确认扫码”意思是移动端标记此二维码已经被扫描，但是用户还没有采取同意或取消操作。有关二维码的详细状态，请见完整接口列表页）。
userPoolId	用户池 ID
createdAt	二维码创建时间
expireAt	二维码过期时间
customData	用户自定义字段了解如何添加自定义数据，请见完整接口列表页。

INFO

有关如何在 iOS 中扫描并解析二维码的内容，可以查看使用 AVFoundation 读取二维码。

要实现 APP 扫描登录 Web 端，首先要求 APP 端用户处于登录状态（这是理所当然的），调用相关接口的时候要带上终端用户的 token。移动端一共需要用到三个接口：

确认扫码
同意授权
取消授权

INFO

要了解这个三个接口的详情，请见完整接口列表页。

以上三个接口移动端 Android Guard SDK 和 iOS Guard SDK 提供了对应的 API：

Android ：请先确保移动应用已依赖并初始化 Android Guard SDK，然后在扫码认证流程中使用扫码认证 API。
iOS：请先确保移动应用已依赖并初始化 IOS Guard SDK，然后在扫码认证流程中使用扫码认证 API。

移动端确认扫码之后，Web 将会看到相关提示。

移动端同意授权之后，整个登录流程也就完成了，开发者可以使用 ticket 去换取用户信息了。

javascript

const authenticationClient = new AuthenticationClient({
   appId: "AUTHING_APP_ID",
   appHost: 'https://xxx.authing.cn',
})
const user = await authenticationClient.qrcode.exchangeUserInfo('TICKET')

INFO

在此获取 AUTHING_APP_ID 和 APP HOST。

第三步：登录成功

获取到用户信息之后，你可以得到用户的身份凭证（用户信息的 token 字段），你可以在客户端后续发送给后端服务器的请求中携带上此 token, 以 axios 为例：

const axios = require("axios");
axios
  .get({
    url: "https://yourdomain.com/api/v1/your/resources",
    headers: {
      Authorization: "Bearer ID_TOKEN",
    },
  })
  .then((res) => {
    // custom codes
  });

在后端接口中需要检验此 token 的合法性，来验证用户的身份，验证方式详情请见验证用户身份凭证（token）。识别用户身份之后，你可能还需要对该用户进行权限管理，以判断用户是否对此 API 具备操作权限。

APP 扫码登录完整接口列表

GenAuth 提供基于 REST 的扫码登录接口，开发者可以直接调用。

生成二维码

POSThttps://core.authing.cn/api/v2/qrcode/gene

该接口会返回二维码 ID （random）和二维码链接。

Headers

Name	Type	Description
`x-authing-userpool-id`REQUIRED	`string`	用户池 ID

Body Parameters

Name	Type	Description
`customeData`OPTIONAL	`string`	自定义数据字段，会写入二维码的原始数据中。
`scene`REQUIRED	`string`	场景值。为常量值，填 APP_AUTH。

Response

200: OK

字段释义：

random: 二维码唯一标志，查询二维码状态、用户确认授权接口会用到。
url: 二维码图片地址。
expiresIn: 二维码有效时间。

json

{
  "code": 200,
  "data": {
    "random": "SzZrszCJNCFfVBDUCKLDtAYNBR96SK",
    "expiresIn": 120,
    "url": "https://files.authing.co/user-contentsqrcode/5fae2648201cfd526f0ec354/SzZrszCJNCFfVBDUCKLDtAYNBR96SK.png"
  }
}

生成的二维码示例：

使用在线二维码解码工具查看二维码数据如下：

json

{
  "scene": "APP_AUTH",
  "random": "SzZrszCJNCFfVBDUCKLDtAYNBR96SK",
  "userPoolId": "5fae2648201cfd526f0ec354",
  "createdAt": "2020-11-13T06:23:25.396Z",
  "expiresIn": 120,
  "customData": {}
}

查询二维码状态

GEThttps://core.authing.cn/api/v2/qrcode/check

Query Parameters

Name	Type	Description
`random`REQUIRED	`string`	二维码 ID。

Response

200: OK

json

{
  "code": 200,
  "message": "查询二维码状态成功！",
  "data": {
    "random": "SzZrszCJNCFfVBDUCKLDtAYNBR96SK",
    "userInfo": {},
    "status": 0,
    "ticket": null,
    "scannedUserId": null
  }
}

请求结果字段说明：

status
- 0: 未扫码。
- 1: 已经扫码但用户还没有点击同意授权或者取消授权，此时会返回用户的头像和昵称，但不包含其他机密信息，可用于前端头像展示。
- 2: 用户同意授权
- 3: 用户取消授权
- -1: 过期
userInfo:
- 默认情况下，在用户扫码之后，会包含昵称（nickname）和头像（photo）两个字段
- 开发者也可以配置返回完整用户信息（包括登录凭证 token）
ticket：用于换取完整用户资料。**此字段只有在用户同意授权之后才会出现。**详情见下文。

使用 ticket 换取用户信息

POSThttps://core.authing.cn/api/v2/qrcode/userinfo

Body Parameters

Name	Type	Description
`ticket`REQUIRED	`string`	查询二维码状态接口返回的 ticket

Response

200: OK

json

{
  "code": 200,
  "message": "换取用户信息成功",
  "data": {
    "id": "5e05bbf2d51b3761d5c71070",
    "email": "983132@qq.com",
    "emailVerified": false,
    "oauth": "",
    "username": "983132@qq.com",
    "nickname": "",
    "company": "",
    "photo": "https://usercontents.authing.co/authing-avatar.png",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImVtYWlsIjoiOTgzMTMyQHFxLmNvbSIsImlxxxxxxxxx",
    "phone": "",
    "tokenExpiredAt": "2020-01-11T08:08:18.000Z",
    "loginsCount": 1,
    "lastIp": "::1",
    "signedUp": "2019-12-27T08:08:18.115Z",
    "blocked": false,
    "isDeleted": false
  }
}

INFO

注意：默认情况下，此接口只允许在服务器端调用，即需要使用用户池密钥初始化之后。

ticket 默认有效时间为 300 s。

开发者可在 GenAuth 控制台 基础配置 -> 基础设置 -> App 扫码登录 Web 自定义配置 处修改。详情见自定义配置项页。

APP 端标记已扫码

POSThttps://core.authing.cn/api/v2/qrcode/scanned

APP 端标记已扫码，标记扫码之后 Web 端将可以获取到当前用户的昵称和头像。

Headers

Name	Type	Description
`x-authing-userpool-id`REQUIRED	`string`	用户池 ID
`Authorization`REQUIRED	`string`	用户登录凭证。

Body Parameters

Name	Type	Description
`random`REQUIRED	`string`	二维码 ID。

Response

200: OK

{
    code: 200,
    message: "二维码扫描确认成功",
    data: {
        random: "", // 原样返回
        status: 0,
        description: "xxxx",
    }
}

INFO

APP 端需要满足两个条件：

用户必须处于登录态
用户的用户池 ID 和二维码用户池 ID 匹配。

APP 端同意授权

POSThttps://core.authing.cn/api/v2/qrcode/confirm

APP 端同意授权，调用此接口前需要先调用 scanned 接口。

Headers

Name	Type	Description
`x-authing-userpool-id`REQUIRED	`string`	用户池 ID
`Authorization`REQUIRED	`string`	用户登录凭证。

Body Parameters

Name	Type	Description
`random`REQUIRED	`string`	二维码 ID

Response

200: OK

{
    code: 200,
    message: "授权登录成功",
    data: {
        random: "", // 原样返回
        status: 1,
        description: "xxxx",
    }
}

INFO

APP 端需要满足两个条件：

用户必须处于登录态
用户的用户池 ID 和二维码用户池 ID 匹配。

APP 端取消授权

POSThttps://core.authing.cn/api/v2/qrcode/cancel

APP 端取消授权，调用此接口前需要先调用 scanned 接口。

Headers

Name	Type	Description
`x-authing-userpool-id`REQUIRED	`string`	用户池 ID
`Authorization`REQUIRED	`string`	用户登录凭证。

Body Parameters

Name	Type	Description
`random`REQUIRED	`string`	二维码 ID

Response

200: OK

{
    code: 200,
    message: "取消授权成功",
    data: {
        random: "", // 原样返回
        status: -1,
        description: "xxxx",
    }
}

INFO

APP 端需要满足两个条件：

用户必须处于登录态
用户的用户池 ID 和二维码用户池 ID 匹配。

自定义配置项

GenAuth 一直以来都致力于带给开发者高度自定义的开发体验，所以我们提供以下自定义配置项，开发者可以根据自己业务的需要，在安全性和便捷性之间权衡。开发者可在 GenAuth 控制台 安全设置 -> 基础设置 -> 登录设置 -> App 扫码登录 Web 自定义配置 处自定义配置。

二维码有效时间

默认 120 s。

是否在查询二维码状态接口返回完整用户信息

默认不返回。由于查询二维码状态接口是没有权限校验的，这意味着直接在此接口返回用户信息（包含登录凭证 token）是存在安全隐患的，所以我们推荐开发者遵循最佳实践：查询二维码状态接口只返回用户昵称和头像，使用 ticket 换取用户信息。

ticket 有效时间

默认为 300 s。

是否允许在浏览器使用 ticket 换取用户信息

默认不允许，需要在服务器端调用，即需要使用用户池密钥初始化之后。点击了解如何初始化后端 SDK。

一个典型的使用场景是：用户扫码同意授权、开发者得到 ticket 之后，发送到自己的后端，使用后端 SDK 换取用户信息，之后重定向到已登录页面，同时将用户信息写入 localStroage。

使用小程序扫码登录网站

小程序扫码登录网站是 GenAuth 的一个开创性的设计，在 GenAuth 中开启扫描登录二维码登录后可以获得微信官方的实名用户信息，用户一键授权即可以真实号码完成注册或者登录，为开发者建立以手机号码为基础的账号体系。

应用场景：PC 网站；
概述：在 PC 网站应用中展示小程序二维码，然后使用微信扫码登录应用；
优势：可以获取到微信用户的手机号与实名信息；

你可以点击此处体验小程序扫码登录。

完整接入流程请见：PC 网站使用小程序扫码登录。

在小程序中进行认证

在小程序中，除了获取、修改用户资料，邮箱手机号登录，添加用户自定义字段等基础操作之外，你还可以使用小程序环境独有的通过微信授权获取用户手机号、 使用微信授权登录、使用微信授权的手机号登录 等方法。

在 GenAuth 中配置小程序登录

为了在小程序中使用 GenAuth 小程序 SDK，你需要先在微信开放平台申请一个小程序，同时在 GenAuth 控制台内填入该小程序的配置。

详情请见：在 GenAuth 中配置小程序登录。

引入 GenAuth 小程序 SDK

详细的安装流程请见：安装小程序 SDK。

第一步先初始化 AuthenticationClient，初始化需要传入AppId （应用 ID）：

你可以在控制台的应用中查看自己的应用列表。

const { AuthenticationClient } = require("authing-wxapp-sdk");

const authing = new AuthenticationClient({
  appId: "AUTHING_APP_ID",
});

接下来就可以使用 AuthenticationClient 的方法了，如使用微信授权登录：

javascript

const { code } = await wx.login();
const data = await authing.loginByCode(code);

如果用户第一次在小程序中登录，且用户没有使用和该小程序绑定同一主体的微信应用登录过，将会创建一个新账号。
如果用户第一次在小程序中登录，但是该用户使用和该小程序绑定同一主体的微信应用登录过，将会返回对应的微信账号。

详情请见：小程序 SDK。

手机号一键登录

手机号一键登录是由三大运营商提供的一种极为便捷的认证方式。

当前 GenAuth 支持通过网易易盾接入该能力，网易易盾集成了三大运营商一键登录 SDK，提供了统一的移动端应用接口。你可以通过以下三步快速完成接入。

STEP1：易盾后台配置

参考易盾文档创建应用，设置包名、上传签名

拷贝 business Id、SecretId、SecretKey

STEP2：GenAuth 后台配置

创建社会化身份源

选择网易易盾

将易盾后台信息填入 GenAuth 控制台

STEP3：移动端集成

通过我们提供的 SDK，开发者只需要一行代码就能集成一键登录功能，请参考：

Android 集成指导

iOS 集成指导

成功集成后效果如下

在移动端实现单点登录

移动应用单点登录（Single Sign On，单点登录）和传统 Web 端 SSO 类似，指的是在多个应用系统中，用户只需要登录一次就可以访问所有相互信任的应用系统。

GenAuth 目前共支持两种形式的移动端单点登录方式：

自动检测同一设备上关联应用的登录态
唤起关联 App 以交换用户信息

自动检测方式

自动检测方式，和美团系 App 类似，可以实现同一设备上所有相互信任系统只要有其中一个处于登录状态，就能检测出相关用户，提示用户是否使用该账号登录，从而实现单点登录。

如下图所示：

你可以查看这个视频的演示：

具体接入方式请见：移动端自动检测登录。

唤起 App 方式

唤起 App 方式，指的是在应用 A 唤起应用 B，用户在应用 B 内同意授权登录，之后跳转会应用 A，应用 A 通过某种方式获取用户信息。此模式正在开发中。

对认证流程进行扩展

添加用户自定义字段

用户自定义字段是除了基础用户字段之外，可以给用户对象添加的额外字段。开发者可以通过设置自定义字段，存储少量业务相关的数据。

你可以在 设置->字段管理->用户字段管理 页面配置自定义用户字段。

可以定义以下几种类型的自定义字段：

字符串
数值
日期
布尔值
Object 对象

在给新创建的自定义字段命名时，你可以编辑该字段在多种语言环境下的显示名称：

直接在「显示名称」下的输入框中编辑，得到默认展示的字段名称
勾选「中文」，并编辑中文环境下的字段显示名称
勾选「English」，并编辑英文环境下的字段显示名称
勾选「繁體」，并编辑繁体中文环境下的字段显示名称
勾选「日本語」，并编辑日语环境下的字段显示名称

特别的，如果该字段的显示环境未包含在上述四种语言环境的范围内，将会采用你配置的「默认展示的字段名称」进行显示。

配置自定义字段之后，你可以开启应用的注册信息补全页面，让用户补全这些自定义字段的信息。

在 应用详情 - 高级配置 页，开启 自定义本应用的登录框

然后切换到 品牌化，勾上 开启注册信息补全 开关，然后选择刚刚添加的自定义字段：

输入类型可以选择文本、密码、数字、日期、颜色、Email 和图片，这会决定页面最终的展示样式。

点击保存，之后访问应用的登录页面。

用户点击注册之后将跳转到下面这个注册信息补全页面：

用户成功注册之后，你可以在用户详情页面看到用户刚刚输入的自定义字段值：

添加角色自定义字段

角色自定义字段是除了基础角色字段之外，可以给角色添加的额外字段。开发者可以通过设置自定义字段，存储少量业务相关的数据。

你可以在 设置->字段管理->角色字段管理 标签页添加、编辑、搜索（通过 Key 和 显示名称 搜索）和删除角色扩展字段。

要添加角色扩展字段，执行以下步骤：

点击添加按钮添加角色扩展字段。
输入 字段Key、显示名称，选择 数据类型，输入 字段描述。

INFO

可以定义以下几种类型的自定义字段：

字符串
数字
布尔值
枚举值
日期

选择是否开启 控制台角色详情是否可见 开关（默认开启）。

INFO

如开启了 控制台角色详情是否可见 开关，则在控制台权限模块下 角色管理 页面查看某角色详情时，可在 扩展字段 标签页查看并设置角色自定义字段。

对于 字符串 / 数字数据类型，可以选择是否开启 是否唯一字段（如开启，表示要确保该扩展字段在用户池内唯一性）。
点击保存按钮。

添加部门扩展字段

部门扩展字段是除了基础部门字段之外，可以给部门添加的额外字段。开发者可以通过设置自定义字段，存储少量业务相关的数据。

你可以在 设置->字段管理->部门字段管理 页面点击“添加”按钮添加部门扩展字段。

可以定义以下几种类型的自定义字段：

字符串
布尔值

IdToken 添加扩展字段

什么是 IdToken

id_token 相当于用户的身份证，开发者的前端访问后端接口时应当携带 id_token，开发者服务器需要校验前端传递的 id_token。可用 OIDC 应用的密钥或 OIDC 应用公钥验签，然后可以得到此 token 对应的用户 ID 以及基本信息。示例代码请见：使用应用密钥验证 Token。

在 GenAuth 中，用户信息的 token 字段就是一个 IdToken。

IdToken 默认字段

一个 OIDC IdToken 默认包含以下字段，参考 OIDC 规范：

字段名	含义
sub	subject 的缩写，为用户 ID
name	姓名
given_name	名字
family_name	姓氏
middle_name	中间名
nickname	昵称
preferred_username	希望被称呼的名字
profile	基础资料
picture	头像
website	网站链接
email	电子邮箱
email_verified	邮箱是否被认证
gender	性别
birthdate	生日
zoneinfo	时区
locale	区域
phone_number	手机号
phone_number_verified	认证手机号
address	地址
formatted	详细地址
street_address	街道地址
locality	城市
region	省
postal_code	邮编
country	国家
updated_at	信息更新时间

IdToken 添加扩展字段

你可以使用 GenAuth 的 Pipeline 能力在用户认证流程中插入自定义代码段，给用户添加自定义 IdToken 字段。例如下面的例子中，我们给用户的 id_token 添加了 KEY 这个字段，值为 VALUE：

javascript

async function pipe(user, context, callback) {
  user.addToken('KEY', 'VALUE')
  callback(null, user, context)
}

你可以在这个网站解析 id_token 。

使用自定义数据库对用户进行认证

使用自定义数据库可以满足以下场景的需求：

使用自己的数据库保存用户数据：完全使用自己的数据库保存用户数据，这种模式下，GenAuth 将不会存储你的任何用户信息。
惰性迁移用户到 GenAuth：这种迁移用户的模式称为惰性迁移（lazy migration），简单来说原理如下：最开始所有的原始用户数据在你的数据库，当用户第一次尝试在 GenAuth 登录时，GenAuth 会通过你配置的自定义数据库脚本在你的数据库查找并验证用户，如果成功，会将该用户迁移到 GenAuth 中；该用户第二次登录时，将使用 GenAuth 的数据库对其进行验证；当所有的用户都至少登录一次时，意味着迁移上云任务完成。

你可以通过以下方式配置自定义数据库：前往 GenAuth 控制台的 连接身份源 - 自定义数据库 页面开启自定义数据库连接，详情请见使用自定义数据库。

使用 Pipeline 对认证流程进行扩展

GenAuth Pipeline 为一组运行在云端的用户自定义 JavaScript 代码，可以让开发者扩展、自定义 GenAuth 能力。

GenAuth Pipeline 函数均为用户可自定义，同时我们还提供了丰富的函数模版，帮助开发者快速上手开发。

同时 Pipeline 为一组函数，和普通 Hooks 的区别在于，Pipeline 整个流程中的函数数据可以相互传递，实现工业流水线一样的效果。这种设计模式，可以使得开发者的自定义函数更加模块化，便于管理。

GenAuth Pipeline 后端使用 serverless 架构，所有的用户自定义代码均运行在云端，保证不同租户之间的隔离性，同时能弹性伸缩，既保证了安全性，有提升了运行效率。

你可以借助 GenAuth Pipeline，实现以下功能：

白名单机制：如注册邮箱后缀白名单、注册 IP 白名单等。
事件通知：如用户注册之后发送群通知、用户登录 IP 异常通知等。
权限控制：如用户登录之后根据邮箱将其加入某用户组等。
扩展用户字段：如往给该请求用户添加自定义 Metadata 等。
自定义 token：如往 token 中加入自定义字段等。
... 还有更多，想象空间是无穷的。

比如通过以下代码，我们可以实现禁止非 example.com 结尾的邮箱注册的逻辑：

javascript

async function pipe(user, context, callback) {
  const { email } = context.request.body
  // 非邮箱注册方式
  if (!email) {
    return callback(null, user, context)
  }
  if (!email.endsWith("example.com")) {
    return callback(new Error('Access denied.'));
  }
  return callback(null, user, context);
}

更多应用场景与详细文档请见此。

使用 Webhook 监听认证事件

Webhooks 允许你对用户注册、登录等行为进行监听，从而对其做一些自定义处理。当你的用户登录、注册、修改密码、验证 MFA （详细的事件列表请见 Webhook 支持的事件列表）之后，都会给你配置的远程 HTTP URL 发送一个 HTTP POST 请求，你可以在这里完成相关的事件处理，比如：

用户在 GenAuth 注册之后，将用户信息同步到 OA 系统；
用户修改用户信息之后，将用户信息的变动同步到 OA 系统；
当用户的邮箱验证之后，给该用户添加相应的积分等。

有关详情，请参阅 Webhooks。

对登录框进行个性化配置

你可以在 GenAuth 控制台的「品牌化」功能区对整个用户池的登录框进行个性化的配置，包括「单点登录 SSO」的登录框以及用户池内所有自建应用的登录框。

在「全局登录框」，你可以根据需要进行相关的「样式配置」和「功能配置」。具体功能包括：

样式配置

登录框版本选择：如何切换至新版 Guard | GenAuth 文档
自定义背景：改变登录框加载和展示的背景
自定义加载图标：改变登录框加载时的图标
隐藏企业身份源登录
隐藏社会化登录
隐藏忘记密码
自定义 CSS

功能配置

登录注册合并：开启后，新用户输入相关信息后将一次完成注册并登录；老用户正常完成登录。
登录注册协议：开启后，用户在登录/注册时需要勾选你所配置的服务条款和隐私条款等内容。
登录注册信息补全：开启后，用户在登录/注册之后会被要求补全信息，需要添加更多字段请详见：添加自定义用户字段。

如果你想对某个自建应用的登录框进行独立于全局的个性化配置，可以这样操作：

首先，找到「高级配置」区域，并打开「自定义本应用的登录框」开关。打开本开关后，本应用的登录框首先将继承你在「全局登录框」中的配置，你可以在此基础上进行改动，不用担心会对用户带来突然的登录框样式改变。

开启此开关后，你便可以在该自建应用的「品牌化」功能区实现对其的独立配置了。

对用户进行认证 ​

概述 ​

OIDC / OAuth2.0 / SAML / AD / LDAP / 社会化登录 ​

托管登录页认证 ​

嵌入登录表单认证 ​

Auth SDK ​

Authentication API ​

单点登录 ​

使用账号密码认证 ​

使用托管登录页 ​

注册 ​

登录 ​

重置密码 ​

修改密码 ​

使用内嵌登录组件 ​

使用 API & SDK ​

注册 ​

登录 ​

重置密码 ​

修改密码 ​

使用短信验证码认证 ​

使用托管登录页 ​

登录 ​

注册 ​

使用内嵌登录组件 ​

使用 API & SDK ​

发送短信验证码 ​

登录 ​

注册 ​

使用社会化登录认证 ​

社会化登录列表 ​

自定义社会化登录 ​

微信解决方案 ​

选择合适的开发接入方式 ​

优劣对比 ​

详细接入方法 ​

使用扫码登录认证 ​

概述 ​

第一步：Web 端生成二维码并轮询扫码状态 ​

第二步：移动 APP 扫码授权用户信息 ​

第三步：登录成功 ​

APP 扫码登录完整接口列表 ​

生成二维码 ​

Headers

Body Parameters

Response

查询二维码状态 ​

Query Parameters

Response

使用 ticket 换取用户信息 ​

Body Parameters

Response

APP 端标记已扫码 ​

Headers

Body Parameters

Response

APP 端同意授权 ​

Headers

Body Parameters

Response

APP 端取消授权 ​

Headers

Body Parameters

Response

自定义配置项 ​

二维码有效时间 ​

是否在查询二维码状态接口返回完整用户信息 ​

ticket 有效时间 ​

是否允许在浏览器使用 ticket 换取用户信息 ​

使用小程序扫码登录网站 ​

在小程序中进行认证 ​

在 GenAuth 中配置小程序登录 ​

引入 GenAuth 小程序 SDK ​

手机号一键登录 ​

STEP1：易盾后台配置 ​

STEP2：GenAuth 后台配置 ​

STEP3：移动端集成 ​

在移动端实现单点登录 ​

自动检测方式 ​

唤起 App 方式 ​

对用户进行认证

概述

OIDC / OAuth2.0 / SAML / AD / LDAP / 社会化登录

托管登录页认证

嵌入登录表单认证

Auth SDK

Authentication API

单点登录

使用账号密码认证

使用托管登录页

注册

登录

重置密码

修改密码

使用内嵌登录组件

使用 API & SDK

注册

登录

重置密码

修改密码

使用短信验证码认证

使用托管登录页

登录

注册

使用内嵌登录组件

使用 API & SDK

发送短信验证码

登录

注册

使用社会化登录认证

社会化登录列表

自定义社会化登录

微信解决方案

选择合适的开发接入方式

优劣对比

详细接入方法

使用扫码登录认证

概述

第一步：Web 端生成二维码并轮询扫码状态

第二步：移动 APP 扫码授权用户信息

第三步：登录成功

APP 扫码登录完整接口列表

生成二维码

查询二维码状态

使用 ticket 换取用户信息

APP 端标记已扫码

APP 端同意授权

APP 端取消授权

自定义配置项

二维码有效时间

是否在查询二维码状态接口返回完整用户信息

ticket 有效时间

是否允许在浏览器使用 ticket 换取用户信息

使用小程序扫码登录网站

在小程序中进行认证

在 GenAuth 中配置小程序登录

引入 GenAuth 小程序 SDK

手机号一键登录

STEP1：易盾后台配置

STEP2：GenAuth 后台配置

STEP3：移动端集成

在移动端实现单点登录

自动检测方式

唤起 App 方式

对认证流程进行扩展

添加用户自定义字段

添加角色自定义字段

添加部门扩展字段

IdToken 添加扩展字段

什么是 IdToken

IdToken 默认字段

IdToken 添加扩展字段

使用自定义数据库对用户进行认证

使用 Pipeline 对认证流程进行扩展

使用 Webhook 监听认证事件

对登录框进行个性化配置

样式配置

功能配置