跳到主要内容

自定义登录

开发者可以使用自定义登录，在自己的服务器或者云函数内，为用户签发带有自定义身份 ID 的「自定义登录凭证 Ticket」，随后用户端 SDK 便可以使用 「Ticket」 登录

适用场景​

自定义登录适用于以下场景：

  • 开发者希望将自有的账号体系与云开发 CloudBase 账号进行一对一关联
  • 开发者希望自行接管鉴权流程

步骤概览​

自定义登录需要以下几个步骤：

  1. 获取 CloudBase 自定义登录私钥
  2. 使用 CloudBase 服务端 SDK，通过私钥签发出 Ticket，并返回至用户端
  3. 用户端 SDK 使用 Ticket 登录 CloudBase

前置动作​

获取自定义登录私钥​

  1. 前往 云开发平台/身份认证/登录方式
  2. 在登录方式列表中，选择「自定义登录」方式，点击「启用」，再点击私钥下载

私钥是一份携带有 JSON 数据的文件，请将下载或复制的私钥文件保存到您的服务器或者云函数中，假设路径为 /path/to/your/tcb_custom_login.json。

注意
  1. 私钥文件是证明管理员身份的重要凭证，请务必妥善保存，避免泄漏
  2. 每次生成私钥文件都会使之前生成的私钥文件在 2 小时后失效

签发 Ticket​

调用 CloudBase 服务端 SDK，在初始化时传入自定义登录私钥，随后便可以签发出 Ticket，并返回至用户端。

注意

签发 Ticket 的操作仅能在服务端进行（云函数、云托管、自建服务器等）。credentials 中的私钥是证明管理员身份的敏感凭证，严禁写入小程序、H5 等前端环境或前端可访问的环境变量中，避免泄漏。

credentials 是 cloudbase.init() 的顶层配置（不要放在 auth 下），其内容即下载的私钥文件，包含以下字段（无需手动填写，直接引入文件即可）：

字段说明
env_id私钥所属的环境 ID
private_key_id私钥标识，签发的 Ticket 中会携带此 ID 用于校验
private_keyRSA 私钥内容，用于签发 JWT
const cloudbase = require("@cloudbase/node-sdk");

// 1. 初始化 SDK
const app = cloudbase.init({
  env: "your-env-id",
  region: "ap-shanghai", // 不传默认为上海地域
  // 传入自定义登录私钥（credentials 是 init 的顶层配置）
  credentials: require("/path/to/your/tcb_custom_login.json"),
});

// 2. 开发者自定义的用户唯一身份标识
const customUserId = "your-customUserId";

// 3. 创建ticket
const ticket = app.auth().createTicket(customUserId);

// 4. 将ticket返回至客户端
return ticket;
注意

customUserId 必须满足以下需求：

  • 4-32 位字符
  • 字符只能是大小写英文字母、数字、以及 _-#@(){}[]:.,<>+#~ 中的字符
提示

开发者也可以编写一个云函数用于生成 Ticket，并为其设置 HTTP 访问服务，随后用户端便可以通过 HTTP 请求的形式获取 Ticket，详细的方案请参阅 使用 HTTP 访问云函数 。

注册流程​

使用自定义登录时，用户管理完全由开发者自行处理。在 CloudBase 中，自定义登录不需要单独的注册流程，用户在第一次使用自定义登录时会自动创建对应的 CloudBase 用户。

注册流程主要包括：

  1. 在您的用户系统中创建用户账号
  2. 使用 CloudBase 服务端 SDK 为该用户签发 Ticket
  3. 客户端使用 Ticket 完成首次登录（此时 CloudBase 会自动创建对应用户）

登录流程​

用户端应用获取到 Ticket 之后，便可以进行登录

Auth.setCustomSignFunc 用于设置获取自定义登录的 ticket 函数

Auth.signInWithCustomTicket 用于自定义登录

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-env-id",
});

const auth = app.auth();

async function login() {
  const loginState = auth.hasLoginState();
  // 1. 建议登录前检查当前是否已经登录
  if (!loginState) {
    // 2. 请求开发者自有服务接口获取ticket
    await auth.setCustomSignFunc(() => {
      // 调用开发者自有服务接口获取ticket
      const ticket = "xxx";
      // 获取 ticket 并返回 Promise
      return Promise.resolve(ticket);
    });
    // 3. 登录 CloudBase
    await auth.signInWithCustomTicket();
  }
}

login();

整体流程示意如下：

自定义登录