¶ 使用内嵌登录组件完成认证

更新时间: 2025-06-11 08:01:00

内嵌登录组件（Guard）被认为是灵活性和集成之间的最佳平衡。如果集成需要更深入的自定义级别，或者在一些前后端分离的场景中无法使用托管模式，则建议使用此模式。内嵌登录组件由 Authing 构建和更新，使用行业最佳实践安全性设计，仅需要几行 JavaScript 代码就可以集成到你开发的项目中。它可以直接从 CDN 或 NPM 加载，也可以从源代码构建。Authing 登录组件同时提供 Javascript 原生、React、Vue 和 Angular 的多种集成模式，在你的任何项目中都可以无缝集成并享有高度自定义灵活性。更加详细的介绍请见接入 Authing Guard。

你可以查看托管登录页 vs 可嵌入登录组件了解 Authing 托管的登录页和内嵌登录组件的区别。

¶ 内嵌登录组件介绍

Authing 内嵌登录组件集成了以下功能：

登录：包含账号密码登录（包括手机号 + 密码、邮箱 + 密码、用户名 + 密码）、验证码登录（短信验证码、邮箱验证码）以及移动端 APP 扫码。
注册：包含手机验证码注册和用户名密码注册。
社会化登录，如 GitHub 登录（需先在后台配置）。
APP 扫码登录（需先接入 APP 扫码登录）。
小程序扫码登录（需先在后台配置）。
企业身份源登录（需要配置企业身份源）。
忘记密码以及重置密码。
MFA 认证。

其具备以下特性：

轻量级：所有资源打包起来只有几百 kb；
响应式：兼容移动端和 PC 端网页；
定制化：可以支持完整的 UI 自定义功能。

¶ 不同前端框架的接入流程

无论使用哪一种框架，你都需要用到应用的 appId ，请先前往控制台获取 (opens new window)。关于 APP ID 所在位置，请参阅应用配置 (opens new window)。

选择前端框架

首先，通过 npm/yarn/cnpm 安装 Authing library.

推荐使用 npm （稳定版本 v3.1.21）或 yarn，它们能更好的和 webpack (opens new window) 打包工具进行配合，也可放心地在生产环境打包部署使用，享受整个生态圈和工具链带来的诸多好处。如果你的网络环境不佳，也可使用 cnpm (opens new window) 。

运行下列命令行安装 Authing React.JS library：

$ yarn add @authing/guard-react

# OR

$ npm install @authing/guard-react --save

然后，在你的 React 应用中完成配置：

App.tsx

// 代码示例：https://github.com/Authing/Guard/blob/master/examples/guard-react/normal/src/App.tsx
import React from "react";
import { GuardProvider } from "@authing/guard-react";
import "@authing/guard-react/dist/esm/guard.min.css";

// 你的业务代码根组件
import RouterComponent from "./router";

const App = () => {
  return (
    <GuardProvider
      appId="AUTHING_APP_ID"
      // 如果你使用的是私有化部署的 Authing 服务，需要传入自定义 host，如:
      // host="https://my-authing-app.example.com"

      // 默认情况下，会使用你在 Authing 控制台中配置的第一个回调地址为此次认证使用的回调地址。
      // 如果你配置了多个回调地址，也可以手动指定（此地址也需要加入到应用的「登录回调 URL」中）：
      // redirectUri="YOUR_REDIRECT_URI"
    >
      <RouterComponent></RouterComponent>
    </GuardProvider>
  );
};

Embed.tsx

// 代码示例：https://github.com/Authing/Guard/blob/master/examples/guard-react/normal/src/pages/Embed.tsx
import React, { useEffect } from "react";
import { useGuard, User } from "@authing/guard-react";

export default function Login() {
  // 获取 Guard 实例
  const guard = useGuard();

  useEffect(() => {
    // 使用 start 方法挂载 Guard 组件到你指定的 DOM 节点，登录成功后返回 userInfo
    guard.start("#authing-guard-container").then((userInfo: User) => {
      console.log("userInfo: ", userInfo);
    });
  }, []);

  return (
    <div>
      <div id="authing-guard-container"></div>
    </div>
  );
}

¶ 在后端验证用户的 Token 是否有效

用户信息的 token 字段为标准的 OIDC IdToken，你可以在后端使用应用的 ID 和 Secret 验证此 token。

示例的 token 如下：

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1ZjIxNTFiZWFlNWE4YjRjZTZiMGJhZTkiLCJiaXJ0aGRhdGUiOiIiLCJmYW1pbHlfbmFtZSI6IiIsImdlbmRlciI6IiIsImdpdmVuX25hbWUiOiIiLCJsb2NhbGUiOiIiLCJtaWRkbGVfbmFtZSI6IiIsIm5hbWUiOiIiLCJuaWNrbmFtZSI6IiIsInBpY3R1cmUiOiJodHRwczovL3VzZXJjb250ZW50cy5hdXRoaW5nLmNuL2F1dGhpbmctYXZhdGFyLnBuZyIsInByZWZlcnJlZF91c2VybmFtZSI6InRlc3RAZXhhbXBsZS5jb20iLCJwcm9maWxlIjoiIiwidXBkYXRlZF9hdCI6IjIwMjEtMDEtMThUMDc6NDg6NTUuNzgxWiIsIndlYnNpdGUiOiIiLCJ6b25laW5mbyI6IiIsImFkZHJlc3MiOnsiY291bnRyeSI6IiIsInBvc3RhbF9jb2RlIjoiIiwicmVnaW9uIjoiIiwiZm9ybWF0dGVkIjoiIn0sInBob25lX251bWJlciI6bnVsbCwicGhvbmVfbnVtYmVyX3ZlcmlmaWVkIjpmYWxzZSwiZW1haWwiOiJ0ZXN0QGV4YW1wbGUuY29tIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJkYXRhIjp7InR5cGUiOiJ1c2VyIiwidXNlclBvb2xJZCI6IjVhOWZhMjZjZjg2MzVhMDAwMTg1NTI4YyIsImFwcElkIjoiNjAwNTNiNzQxNjQ3OGRlMmU4OGZhYjQzIiwiaWQiOiI1ZjIxNTFiZWFlNWE4YjRjZTZiMGJhZTkiLCJ1c2VySWQiOiI1ZjIxNTFiZWFlNWE4YjRjZTZiMGJhZTkiLCJfaWQiOiI1ZjIxNTFiZWFlNWE4YjRjZTZiMGJhZTkiLCJwaG9uZSI6bnVsbCwiZW1haWwiOiJ0ZXN0QGV4YW1wbGUuY29tIiwidXNlcm5hbWUiOiJ0ZXN0QGV4YW1wbGUuY29tIiwidW5pb25pZCI6bnVsbCwib3BlbmlkIjpudWxsLCJjbGllbnRJZCI6IjVhOWZhMjZjZjg2MzVhMDAwMTg1NTI4YyJ9LCJ1c2VycG9vbF9pZCI6IjVhOWZhMjZjZjg2MzVhMDAwMTg1NTI4YyIsImF1ZCI6IjYwMDUzYjc0MTY0NzhkZTJlODhmYWI0MyIsImV4cCI6MTYxMjE2NTg4OCwiaWF0IjoxNjEwOTU2Mjg4LCJpc3MiOiJodHRwczovL3NhbXBsZS1hcHAuYXV0aGluZy5jbi9vaWRjIn0.SNyGBffF-zBqDQFINGxUJZrWSAADHQhbEOsKvnH4SLg

你可以在 JWT.IO (opens new window)（国内用户可以访问此镜像站 (opens new window)）中解码此 ID Token ：

其中 sub 字段为用户的 ID，aud 字段为应用的 ID，你可以通过 Microsoft identity platform ID tokens (opens new window) 了解 OIDC IdToken 每个字段的详细释义。

基本上所有语言都提供了检验 IdToken 的 Library，以 Node.js 为例，你可以使用 JSON Web Token (opens new window) 来验证 IdToken：

const jwt = require("jsonwebtoken");

try {
  const data = jwt.verify("YOUR_ID_TOKEN", "YOUR_APP_SECRET");
} catch (error) {
  // token might be invalid or expired
  console.error(error);
}

如果验证成功，你可以通过 sub 字段得到该用户的唯一 ID，之后你就可以将用户 ID 与自己的业务结合起来啦！如果你需要给不同的用户授权不同的角色、权限，你可以了解如何给用户授权角色、权限，以进行细粒度的权限控制。

¶ 详细的参数与事件列表

Authing 内嵌登录组件支持高度自定义化，除了自定义标题、Logo 等基础配置外，你还可以配置不同的登录方式，通过自定义 CSS 完全自定义样式等；除了成功登录事件外，Authing 内嵌登录组件还封装了成功注册、登录失败、登录注册方式切换等事件，详细文档请见登录组件（Guard）文档。

上一篇: 使用托管登录页完成认证下一篇: 使用 API & SDK 完成认证