自定义登录

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

适用场景

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

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

步骤概览

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

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

前置动作

获取自定义登录私钥

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

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

注意

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

签发 Ticket

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

注意

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

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

字段	说明
`env_id`	私钥所属的环境 ID
`private_key_id`	私钥标识，签发的 Ticket 中会携带此 ID 用于校验
`private_key`	RSA 私钥内容，用于签发 JWT

@cloudbase/js-sdk 自 v3.1 起内置 Node.js 适配器，可在服务端签发 Ticket。credentials 同样是 init() 的顶层配置。

const cloudbase = require("@cloudbase/js-sdk");

// 1. 初始化 SDK
const app = cloudbase.init({
  env: "your-env-id",
  // credentials 是 init() 的顶层配置，不要放在 auth 下
  credentials: require("/path/to/your/tcb_custom_login.json"),
});

exports.main = async (event, context) => {
  // 2. 创建 ticket（js-sdk 中 createTicket 为异步方法）
  const ticket = await app.auth.createTicket("your-customUserId");
  // 3. 将 ticket 返回至客户端
  return ticket;
};

注意

customUserId 必须满足以下需求：

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

提示

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

注册流程

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

注册流程主要包括：

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

登录流程

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

Auth.signInWithCustomTicket 用于自定义登录。调用时直接传入获取 Ticket 的函数。

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. 登录 CloudBase，传入获取 ticket 的函数
    const { data, error } = await auth.signInWithCustomTicket(async () => {
      // 调用开发者自有服务接口获取 ticket
      const response = await fetch("/api/get-custom-ticket");
      const result = await response.json();
      return result.ticket;
    });

    if (error) {
      console.error("自定义登录失败:", error.message);
    } else {
      console.log("自定义登录成功，用户信息:", data.user);
    }
  }
}

login();

整体流程示意如下：

自定义登录

适用场景​

步骤概览​

前置动作​

获取自定义登录私钥​

签发 Ticket​

注册流程​

登录流程​