登录认证
#
app.auth()#
接口描述返回 Auth
对象
签名:auth({ persistence: string }): Auth
#
输入参数字段 | 类型 | 必填 | 说明 |
---|---|---|---|
persistence | string | 否 | 身份认证状态如何持久保留,有三个选项 local 、session 和 none ,默认为 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
字段 | 类型 | 必填 | 说明 |
---|---|---|---|
appid | string | 是 | 微信公众平台(或开放平台)应用的 appid。 |
scope | string | 是 | 网页授权类型,可选值为 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 替换成您的环境 IDconst 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
tip
此接口获取的是本地的登录态,并不会判断登录态是否过期,如果担心登录态过期建议使用对应的异步接口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>
tip
调用此接口会刷新本地登录态,不存在登录态过期问题。
#
示例代码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(() => { // 此时登录类型已经发生变化});
#
LoginStateLoginState
对象是对用户当前的登录态的抽象
#
LoginState.loginType类型:string
表示当前的登录类型
取值 | 含义 |
---|---|
"ANONYMOUS" | 匿名登录 |
"WECHAT" | 微信登录 |
"CUSTOM" | 自定义登录 |
#
LoginState.user类型:User | null
表示当前用户,具体请参考 User
如果没有登录,则为 null
#
LoginState.isAnonymousAuth类型:boolean
表示当前是否为匿名登录
#
LoginState.isCustomAuth类型:boolean
表示当前是否为自定义登录
#
LoginState.isWeixinAuth类型:boolean
表示当前是否为微信登录
#
LoginState.isUsernameAuth类型:boolean
表示当前是否为用户名密码登录
#
UserUser
对象是对云开发用户的抽象表示
#
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 为获取到的自定义登录 Ticketuser.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(() => { // 修改成功});
#
User.unlink()#
接口描述解绑某个登录方式。
签名: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 |
为什么无法同步微信账号信息?
当 syncUserInfo
为 true
,并且网页授权类型为 snsapi_userinfo
或者 snsapi_login
时,才可以同步微信账号信息作为云开发用户信息。
#
示例代码const provider = app.auth().weixinAuthProvider({ appid: "...", scope: "snsapi_base"});
// 假设我们有一个“微信登录”按钮,点击后跳转登录页面document.getElementById("login").onclick = function () { provider.signInWithRedirect();};
// 如果页面含有微信的登录态,那么回调中会存在 LoginStateprovider.getRedirectResult().then((loginState) => { if (loginState) { // 有登录态 }});
#
WeixinAuthProvider.getLinkRedirectResult()#
接口描述获取微信重定向绑定结果。如果 withUnionId
为 true
,且存在微信 UnionID,则会一同绑定微信 UnionID。
签名:getLinkRedirectResult({ withUnionId?: boolean }): Promise<void>
#
示例代码// 用户以任意一种登录方式(除微信登录)登录云开发之后
// 获取 Providerconst 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 替换成您的环境 IDconst 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) => { // 登录失败 });