跳到主要内容

登录认证

app.auth()

接口描述

返回 Auth 对象

签名:auth({ persistence: string }): Auth

输入参数

字段类型必填说明
persistencestring身份认证状态如何持久保留,有三个选项 localsessionnone,默认为 session
  • local:在显式退出登录之前的 30 天内保留身份验证状态
  • session:在窗口关闭时清除身份验证状态
  • none:在页面重新加载时清除身份验证状态

示例代码

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

const app = cloudbase.init({
env: "xxxx-yyy"
});

const auth = app.auth({
persistence: "local" //用户显式退出或更改密码之前的30天一直有效
});

Auth

Auth.currentUser

接口描述

返回表示当前用户的 User 实例

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

// 执行某种登录之后...
const user = app.auth().currentUser;

Auth.getCurrenUser()

接口描述

Auth.currentUser的异步操作,返回表示当前用户的 User 实例

签名:getCurrenUser(): Promise<User | null>

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

// 执行某种登录之后...
app
.auth()
.getCurrenUser()
.then((user) => {
// ...
});

Auth.hasLoginState()

接口描述

返回当前登录状态 LoginState,如果未登录,则返回 null

签名:hasLoginState(): LoginState | null

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

const loginState = app.auth().hasLoginState();

if (loginState) {
// 登录态有效
} else {
// 没有登录态,或者登录态已经失效
}

Auth.getLoginState()

接口描述

Auth.hasLoginState()的异步操作,返回当前登录状态 LoginState,如果未登录,则返回 null

签名:getLoginState(): Promise<LoginState | null>

提示

此 API 是 hasLoginState 的异步模式,适用于本地存储为异步的平台,比如 React Native

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

const loginState = app
.auth()
.getLoginState()
.then((loginState) => {
if (loginState) {
// 登录态有效
} else {
// 没有登录态,或者登录态已经失效
}
});

Auth.weixinAuthProvider()

接口描述

获取用于微信登录的 WeixinAuthProvider

签名:weixinAuthProvider({ appid: string, scope: string }): WeixinAuthProvider

字段类型必填说明
appidstring微信公众平台(或开放平台)应用的 appid。
scopestring网页授权类型,可选值为 snsapi_base(公众平台,只获取用户的 openid)、snsapi_userinfo(公众平台,获取用户的基本信息)和 snsapi_login(开放平台网页授权)。

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

const provider = app.auth().weixinAuthProvider({
appid: "your-appid",
scope: "snsapi_base"
});
provider.getRedirectResult().then((loginState) => {
if (loginState) {
// 登录成功,本地已存在登录态
} else {
// 未登录,唤起微信登录
provider.signInWithRedirect();
}
});

Auth.customAuthProvider()

接口描述

获取用于自定义登录的 CustomAuthProvider

签名:customAuthProvider(): CustomAuthProvider

示例代码

// 将 your-envId 替换成您的环境 ID
const app = cloudbase.init({
env: "your-envId"
});

async function login() {
// 获取自定义登录 ticket
// 将 your-api 替换成获取 ticket 的 URL
const ticket = await fetch("your-api");

app
.auth({
persistence: "session"
})
.customAuthProvider()
.signIn(ticket)
.then(() => {
// 登录成功
})
.catch((err) => {
// 登录失败
});
}

login();

Auth.anonymousAuthProvider()

接口描述

获取用于匿名登录的 AnonymousAuthProvider

签名:anonymousAuthProvider(): AnonymousAuthProvider

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

app
.auth({
persistence: "session"
})
.anonymousAuthProvider()
.signIn()
.then(() => {
// 登录成功
})
.catch((err) => {
// 登录失败
});

Auth.signUpWithEmailAndPassword()

接口描述

使用邮箱和密码注册一个云开发账户,调用后,会自动向注册邮箱发送邮箱验证邮件

签名:signUpWithEmailAndPassword(email: string, password: string): Promise<void>

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

const auth = app.auth();

const email = "foo@bar.com";
const password = "your_awesome_password";
auth.signUpWithEmailAndPassword(email, password).then(() => {
// 发送验证邮件成功
});

Auth.signInWithEmailAndPassword()

接口描述

使用邮箱和密码登录云开发。

签名:signInWithEmailAndPassword(email: string, password: string): Promise<LoginState>

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

const auth = app.auth();

const email = "foo@bar.com";
const password = "your_awesome_password";
auth.signInWithEmailAndPassword(email, password).then((loginState) => {
// 邮箱密码登录成功
});

Auth.sendPasswordResetEmail()

接口描述

发送重置密码的邮件。

签名:sendPasswordResetEmail(email: string): Promise<void>

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

const auth = app.auth();

const email = "foo@bar.com";
auth.sendPasswordResetEmail(email).then(() => {
// 发送重置密码邮件成功
});

Auth.signInWithUsernameAndPassword()

接口描述

使用用户名密码登录云开发。

签名:signInWithUsernameAndPassword(username: string, password: string): Promise<LoginState>

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

const auth = app.auth();

const username = "your_awesome_username";
const password = "your_awesome_password";
auth.signInWithUsernameAndPassword(username, password).then((loginState) => {
// 用户名密码登录成功
});

Auth.isUsernameRegistered()

接口描述

检查用户名是否被绑定过。

签名:isUsernameRegistered(username: string): Promise<boolean>

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

const auth = app.auth();

const username = "your_awesome_username";
auth.isUsernameRegistered(username).then((registered) => {
//
});

Auth.sendPhoneCode()

接口描述

发送手机验证码。

签名:sendPhoneCode(phoneNumber: string): Promise<boolean>

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

const auth = app.auth();

auth.sendPhoneCode("18600000000").then((res) => {
if (res === true) {
console.log("验证码发送成功!");
}
});

Auth.signUpWithPhoneCode()

接口描述

手机号注册(支持短信验证码+密码方式)。

签名:signUpWithPhoneCode(phoneNumber: string,phoneCode: string,password?: string): Promise<LoginState>

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

const auth = app.auth();

auth.signUpWithPhoneCode("18600000000", "000000", "12345678").then((res) => {
// 注册成功
});

Auth.signInWithPhoneCodeOrPassword()

接口描述

手机号登录(支持短信验证码 or 密码方式)。

签名:signInWithPhoneCodeOrPassword({phoneNumber: string, phoneCode?: string, password?: string}): Promise<LoginState>

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

const auth = app.auth();

// 手机短信验证码登录
auth
.signInWithPhoneCodeOrPassword({
phoneNumber: "18600000000",
phoneCode: "000000"
})
.then((res) => {
// 登录成功
});

// 手机密码登录
auth
.signInWithPhoneCodeOrPassword({
phoneNumber: "18600000000",
password: "12345678"
})
.then((res) => {
// 登录成功
});

Auth.forceResetPwdByPhoneCode()

接口描述

手机号强制重置密码。

签名:forceResetPwdByPhoneCode({phoneNumber: string, phoneCode: string, password: string}): Promise<LoginState>

提示

自 @cloudbase/js-sdk@1.6.0 版本起支持此接口

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

const auth = app.auth();

// 手机短信验证码登录
auth
.forceResetPwdByPhoneCode({
phoneNumber: "your phoneNumber",
phoneCode: "code",
password: "your password"
})
.then((res) => {
// 重置密码成功,自动获得登录态
});

Auth.signOut()

接口描述

登出云开发

签名:signOut(): Promise<void>

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

const auth = app.auth();

auth.signOut();

Auth.getAuthHeader()

接口描述

获取 HTTP 鉴权头部,可用于 HTTP 访问云函数或者云托管时的鉴权。如果未登录,则返回 null

签名:getAuthHeader(): { "x-cloudbase-credentials": string } | null

提示

此接口获取的是本地的登录态,并不会判断登录态是否过期,如果担心登录态过期建议使用对应的异步接口Auth.getAuthHeaderAsync()

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

const auth = app.auth();

auth.getAuthHeader(); // { "x-cloudbase-credentials": "......" }

Auth.getAuthHeaderAsync()

接口描述

Auth.getAuthHeader()的异步操作,获取 HTTP 鉴权头部,可用于 HTTP 访问云函数时的鉴权。如果未登录,则返回 null

签名:getAuthHeaderAsync(): Promise<{ "x-cloudbase-credentials": string } | null>

提示

调用此接口会刷新本地登录态,不存在登录态过期问题。

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

const auth = app.auth();

auth.getAuthHeaderAsync().then((res) => {
// { "x-cloudbase-credentials": "......" }
});

Auth.shouldRefreshAccessToken()

接口描述

接收一个回调函数,并且会在刷新短期访问令牌前调用此回调函数,根据返回值决定是否要刷新短期访问令牌。

对于两种登录态并存(Cloudbase、自身业务登录态)的 Web 应用,可以在回调函数内判断自身业务登录态是否失效,从而决定是否续期 Cloudbase 的短期访问令牌。

签名:shouldRefreshAccessToken(callback: () => boolean): void

示例代码

auth.shouldRefreshAccessToken(() => {
if (/* 自身业务登录态还有效 */) {
return true;
} else {
return false;
}
});

Auth.onLoginStateChanged()

接口描述

接收一个回调函数,并且会在登录状态改变时,调用此回调函数。

签名:onLoginStateChanged(callback: (loginState: LoginState) => any): void

示例代码

auth.onLoginStateChanged((loginState) => {
if (loginState) {
// 有登录状态
} else {
// 没有登录
}
});

Auth.onLoginStateExpired()

接口描述

接收一个回调函数,并且会在登录状态过期,调用此回调函数。

签名:onLoginStateExpired(callback: Function): void

示例代码

auth.onLoginStateExpired(() => {
// 此时登录状态过期,需要重新登录
});

Auth.onAccessTokenRefreshed()

接口描述

接收一个回调函数,并且会在短期访问令牌刷新后,调用此回调函数。

签名:onAccessTokenRefreshed(callback: Function): void

示例代码

auth.onAccessTokenRefreshed(() => {
// 此时短期访问令牌已经被刷新
});

Auth.onAnonymousConverted()

接口描述

接收一个回调函数,并且会在匿名登录状态被转换后,调用此回调函数。

签名:onAnonymousConverted(callback: Function): void

示例代码

auth.onAnonymousConverted(() => {
// 此时匿名登录状态已经被转换
});

Auth.onLoginTypeChanged()

接口描述

接收一个回调函数,并且会在登录类型发生变化后,调用此回调函数。

签名:onLoginTypeChanged(callback: Function): void

示例代码

auth.onLoginTypeChanged(() => {
// 此时登录类型已经发生变化
});

LoginState

LoginState 对象是对用户当前的登录态的抽象

LoginState.loginType

类型:string

表示当前的登录类型

取值含义
"ANONYMOUS"匿名登录
"WECHAT"微信登录
"CUSTOM"自定义登录

LoginState.user

类型:User | null

表示当前用户,具体请参考 User

如果没有登录,则为 null

LoginState.isAnonymousAuth

类型:boolean

表示当前是否为匿名登录

LoginState.isCustomAuth

类型:boolean

表示当前是否为自定义登录

LoginState.isWeixinAuth

类型:boolean

表示当前是否为微信登录

LoginState.isUsernameAuth

类型:boolean

表示当前是否为用户名密码登录

User

User 对象是对云开发用户的抽象表示

User.uid

类型:string

云开发用户的全局唯一 ID

User.loginType

类型:string

表示当前的登录类型

取值含义
"ANONYMOUS"匿名登录
"WECHAT"微信登录
"CUSTOM"自定义登录

User.openid

类型:string

表示此用户绑定的微信 openid

User.unionId

类型:string

表示此用户绑定的微信 unionId

User.wxOpenId

表示此用户绑定的微信 openid

User.wxPublicId

表示此用户绑定的微信开放平台 openid

User.customUserId

表示此用户绑定的自定义登录 customUserId

User.qqMiniOpenId

类型:string

表示此用户对应的 QQ 小程序 openid

User.nickName

类型:string

用户昵称

User.gender

类型:string

用户性别,取值仅限于:"MALE""FEMALE"UNKNOWN"

User.avatarUrl

类型:string

用户头像 URL

User.location

类型: { country: string; province: string; city: string }

用户地理位置

User.username

类型:string

用户名

User.hasPassword

类型:boolean

是否设置了密码

User.update()

接口描述

更新用户信息

签名:update(userInfo): Promise<void>

示例代码

const user = auth.currentUser;

user
.update({
nickName: "王小黑", // 昵称,不超过 45 个字符
gender: "MALE", // 性别,取值仅限于 MALE、FEMALE、UNKNOWN
avatarUrl: "https://...", // 头像地址,不超过 255 个字符
country: "中国", // 不超过 45 个字符
province: "广东", // 不超过 45 个字符
city: "深圳" // 不超过 45 个字符
})
.then(() => {
// 更新用户信息成功
});

User.refresh()

接口描述

刷新本地用户信息。当用户在其他客户端更新用户信息之后,可以调用此接口同步更新之后的信息。

签名:refresh(): Promise<UserInfo>

示例代码

const user = auth.currentUser;

user.refresh().then(() => {
// 刷新用户信息成功
});

User.linkWithTicket()

接口描述

将当前账户与自定义登录 Ticket 进行绑定,绑定之后便可以通过自定义登录登录当前云开发账户。

签名:linkWithTicket(ticket: string): Promise<void>

示例代码

const user = auth.currentUser;

// ticket 为获取到的自定义登录 Ticket
user.linkWithTicket(ticket).then(() => {
// 绑定成功
});

User.linkWithRedirect()

接口描述

将当前账户与第三方鉴权提供方,以重定向的形式,进行绑定,绑定之后便可以通过第三方鉴权提供方登录当前的云开发账户。

签名:linkWithRedirect(provider: AuthProvider): void

示例代码

以绑定微信登录为例:

const user = auth.currentUser;

const provider = auth.weixinAuthProvider({
appid: "....",
scope: "snsapi_base"
});

user.linkWithRedirect(provider); // 调用之后,网页会被重定向至第三方登录页面

User.updatePassword()

接口描述

修改密码。如果用户之前没有设置过密码,那么无需填写 oldPassword

签名:updatePassword(newPassword: string, oldPassword?: string): Promise<void>

示例代码

const user = auth.currentUser;
user.updatePassword("new_password", "old_password").then(() => {
// 更新密码成功
});

User.updateEmail()

更新当前的登录邮箱,调用后会发送验证邮件到新邮箱,用户需要访问验证邮件中的激活链接来完成更新。

注意

该接口还可用于其他登录方式(如匿名登录)绑定邮箱登录,若原登录方式未设置密码,需指定密码参数。(自 sdk 1.6.0 版本后支持)

接口描述

修改登录邮箱。

签名:updateEmail(newEmail: string, password?: string): Promise<void>

示例代码

const user = auth.currentUser;
user.updateEmail("new_email@foo.com").then(() => {
// 发送验证邮件
});
// 匿名登录绑邮箱转正
import cloudbase from "@cloudbase/js-sdk";
const app = cloudbase.init({
env: "xxx"
});

const auth = app.auth({
persistence: "local"
});

async function login() {
const loginState = await auth.getLoginState();
if (!loginState) {
// 匿名登录
await auth.anonymousAuthProvider().signIn();

// 绑邮箱
const updateEmailRes = await auth.currentUser.updateEmail(
"your email address",
"your password"
);

console.log("updateEmailRes", updateEmailRes);
}
}

login();

User.updateUsername()

接口描述

修改用户名。

签名:updateUsername(newUsername: string): Promise<void>

示例代码

const user = auth.currentUser;
user.updateUsername("new_username").then(() => {
// 修改成功
});

User.linkWithPhoneNumber()

接口描述

绑定手机号

签名:linkWithPhoneNumber(phoneNumber: string,phoneCode: string): Promise<void>

示例代码

const user = auth.currentUser;
user.linkWithPhoneNumber("18600000000", "000000").then(() => {
// 修改成功
});

User.updatePhoneNumber()

接口描述

更新手机号

签名:updatePhoneNumber(phoneNumber: string,phoneCode: string): Promise<void>

示例代码

const user = auth.currentUser;
user.updatePhoneNumber("18600000000", "000000").then(() => {
// 修改成功
});

接口描述

解绑某个登录方式。

签名:unlink(loginType): Promise<void>

loginType 取值含义
WECHAT-OPEN微信开放平台
WECHAT-PUBLIC微信公众平台
WECHAT-UNION微信 UnionID
CUSTOM自定义登录
EMAIL邮箱登录
PHONE手机号登录
注意

不能解绑当前登录方式

示例代码

const user = auth.currentUser;

user.unlink("CUSTOM").then(() => {
// 解绑自定义登录成功
});

WeixinAuthProvider

WeixinAuthProvider.signInWithRedirect()

接口描述

跳转到微信登录页面。

建议

推荐使用此接口搭配 WeixinAuthProvider.getRedirectResult() 完成完整的登录流程。

签名:signInWithRedirect(): void

示例代码

// 直接跳转到微信登录页面
app
.auth()
.weixinAuthProvider({
appid: "...",
scope: "snsapi_base"
})
.signInWithRedirect();

WeixinAuthProvider.getRedirectResult()

接口描述

微信登录页面重定向回来后,使用重定向的返回值登录,并获取登录态。

签名:getRedirectResult({ createUser?: boolean; syncUserInfo?: boolean }): Promise<LoginState | null>

参数名含义默认值
createUser当微信 openid 没有对应的云开发用户时,是否自动创建一个新的云开发用户true
syncUserInfo同步微信账号信息作为云开发用户信息false
为什么无法同步微信账号信息?

syncUserInfotrue ,并且网页授权类型为 snsapi_userinfo 或者 snsapi_login 时,才可以同步微信账号信息作为云开发用户信息。

示例代码

const provider = app.auth().weixinAuthProvider({
appid: "...",
scope: "snsapi_base"
});

// 假设我们有一个“微信登录”按钮,点击后跳转登录页面
document.getElementById("login").onclick = function () {
provider.signInWithRedirect();
};

// 如果页面含有微信的登录态,那么回调中会存在 LoginState
provider.getRedirectResult().then((loginState) => {
if (loginState) {
// 有登录态
}
});

WeixinAuthProvider.getLinkRedirectResult()

接口描述

获取微信重定向绑定结果。如果 withUnionIdtrue,且存在微信 UnionID,则会一同绑定微信 UnionID。

签名:getLinkRedirectResult({ withUnionId?: boolean }): Promise<void>

示例代码

// 用户以任意一种登录方式(除微信登录)登录云开发之后

// 获取 Provider
const auth = app.auth();
const provider = auth.weixinAuthProvider({
appid: "....",
scope: "snsapi_base"
});

// 重定向到提供方的页面进行登录
auth.currentUser.linkWithRedirect(provider);

用户在微信的页面登录之后,会被重定向回您的页面。然后,可以在页面加载时通过调用 Provider.getLinkRedirectResult() 来获取关联结果:

provider.getLinkRedirectResult().then((result) => {
// 关联成功
});

CustomAuthProvider

CustomAuthProvider.signIn()

接口描述

使用自定义登录凭据 ticket 登录云开发。

签名:signIn(ticket: string): Promise<void>

示例代码

// 将 your-envId 替换成您的环境 ID
const app = cloudbase.init({
env: "your-envId"
});

async function login() {
// 获取自定义登录 ticket
// 将 your-api 替换成获取 ticket 的 URL
const ticket = await fetch("your-api");

app
.auth({
persistence: "session"
})
.customAuthProvider()
.signIn(ticket)
.then(() => {
// 登录成功
})
.catch((err) => {
// 登录失败
});
}

login();

AnonymousAuthProvider

AnonymousAuthProvider.signIn()

接口描述

匿名登录云开发。

签名:signIn(): Promise<void>

示例代码

const app = cloudbase.init({
env: "xxxx-yyy"
});

app
.auth({
persistence: "session"
})
.anonymousAuthProvider()
.signIn()
.then(() => {
// 登录成功
})
.catch((err) => {
// 登录失败
});