• 开源：开源且支持自部署。官方的free plan目前也足够了。
• 高灵活性：支持多种接入方式，无论是通过官方的auth UI快速集成，还是使用SDK和API自定义认证页面。
• 强大功能：不仅支持用户认证和授权，还采用JWT进行认证，基于Supabase的Row Level Security实现细粒度授权。同时，支持主流第三方认证提供商，包括匿名登录。
• 完善文档与活跃社区：文档齐全，社区活跃，提供丰富的SDK，对Next.js项目特别友好。
• 安全性：Supabase的认证模块基于Netlify开源的GoTrue项目，安全设计周全，值得信赖。

背景知识

用户认证

• 邮件和密码认证
• 无密码认证：比如OTP（one-time apssword、magiclink）
• OAUTH：比如google、git等
• SAML SSO

Session

type Session struct {
	ID     uuid.UUID `json:"-" db:"id"`
	UserID uuid.UUID `json:"user_id" db:"user_id"`

	// NotAfter is overriden by timeboxed sessions.
	NotAfter *time.Time `json:"not_after,omitempty" db:"not_after"`

	CreatedAt time.Time  `json:"created_at" db:"created_at"`
	UpdatedAt time.Time  `json:"updated_at" db:"updated_at"`
	FactorID  *uuid.UUID `json:"factor_id" db:"factor_id"`
	// 认证方法列表
	AMRClaims []AMRClaim `json:"amr,omitempty" has_many:"amr_claims"`
	// 认证等级：1、2、3次认证
	AAL       *string    `json:"aal" db:"aal"`

	RefreshedAt *time.Time `json:"refreshed_at,omitempty" db:"refreshed_at"`
	UserAgent   *string    `json:"user_agent,omitempty" db:"user_agent"`
	IP          *string    `json:"ip,omitempty" db:"ip"`

	Tag *string `json:"tag" db:"tag"`
}

• 登出：调用 supabase.auth.signOut() ，session中的数据会被清理。
• 用户reset-password。
• 用户无交互（inactive）：可以在auth相关的配置中指定inactive timeout。
• 最大时长限制：可以在auth相关配置中指定最大时长Time-box user sessions。
• 用户登入其他设备：可配置session数唯一，仅一台设备使用。

JWT

// AccessTokenClaims is a struct thats used for JWT claims
type AccessTokenClaims struct {
	// JWT标准claims, https://datatracker.ietf.org/doc/html/rfc7519#section-4.1
	jwt.StandardClaims
	Email                         string                 `json:"email"`
	Phone                         string                 `json:"phone"`
	// provider列表等
	AppMetaData                   map[string]interface{} `json:"app_metadata"`
	// 用户元数据
	UserMetaData                  map[string]interface{} `json:"user_metadata"`
	// authenticated
	Role                          string                 `json:"role"`
	// 认证等级: aal1, aal2（二次认证）, aal3。
	AuthenticatorAssuranceLevel   string                 `json:"aal,omitempty"`
	// 认证方式: mfa, password, magiclink等
	AuthenticationMethodReference []models.AMREntry      `json:"amr,omitempty"`
	// 认证会话ID，用于追踪认证记录
	SessionId                     string                 `json:"session_id,omitempty"`
	IsAnonymous                   bool                   `json:"is_anonymous"`
}

// 生成accesstoken
claims := &hooks.AccessTokenClaims{
		StandardClaims: jwt.StandardClaims{
			Subject:   user.ID.String(),
			Audience:  user.Aud,
			IssuedAt:  issuedAt.Unix(),
			ExpiresAt: expiresAt,
			Issuer:    config.JWT.Issuer,
		},
		Email:                         user.GetEmail(),
		Phone:                         user.GetPhone(),
		AppMetaData:                   user.AppMetaData,
		UserMetaData:                  user.UserMetaData,
		Role:                          user.Role,
		SessionId:                     sid,
		AuthenticatorAssuranceLevel:   aal.String(),
		AuthenticationMethodReference: amr,
		IsAnonymous:                   user.IsAnonymous,
	}
token = jwt.NewWithClaims(jwt.SigningMethodHS256, claims);

• access-token：用户凭证，有效时长可配置，建议时长不要超过1小时。可凭refresh-token定期刷新。
• refresh-token：不过期，但只允许使用一次(即refresh token rotaion)，目的主要是为了防止refresh_token被窃取。同时为避免网络异常、重复渲染等情况造成的不可用，Supabase提供了Refresh Token Reuse Detection机制来保障可靠性。
• expire：access-token过期时间。

身份验证

• supabase.auth.getUser ：该API会发起一次到Supabase· server的网络调用，在服务端去解析JWT的有效性。一般用于服务端。
• supabase.auth.getSession ：从localstorage取JWT以及加密session data。用于本地的登录校验。一般用于client端非敏感权限的判断（比如判断用户是否登录）。

接入流程

前置准备

• 创建Supabase项目，申请 NEXT_PUBLIC_SUPABASE_URL 、 NEXT_PUBLIC_SUPABASE_ANON_KEY 并写入项目环境变量。
• 配置confirm地址白名单以及邮件模板，指定用户signup、password-reset等场景的confirm邮件内容以及跳转地址。

http://127.0.0.1:3000/auth/reset-password/confirm
http://127.0.0.1:3000/auth/signup/confirm

<h2>Confirm your signup</h2>

<p>Follow this link to confirm your user:</p>
<p><a href="{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=signup&next={{ .RedirectTo }}">Confirm your mail</a></p>

接入

注册（signup）

1. web请求signup页面，next server下发signup页，里面包含一个含表单的页面。
2. web：用户输入signup相关字段，web端参数合法性校验，通过next action将form参数提交给next server。
3. next server action：校验参数合法性，然后调用 supabase.auth.signUp() ，通过supbase 服务端给用户发送confirm邮件。返回web发送成功。
   [text] Copy

   http://localhost:3000/signup/confirm?token_hash=pkce_xxxxxx&type=signup

   同时也会下发一个 sb-xxxxxx-auth-token-code-verifier的cookie给到web。具体作何使用（注册流程跟Oauth的PKCE有何关系？）

   注意：Signup需要指定redirect地址为结果页面的地址。因为OTP的第一跳地址为模板中配置的 auth/confirm ，然后才会被redirect到我们指定的redirect地址。

4. web：通知已发送邮件，需要用户去邮箱确认。

1. web：用户通过邮件点击confirm地址，query参数中包括一个一次性的token_hash以及操作类型op_type，以及redirect地址（上面的next参数）。
2. next.js server action：通用的confirm action，主要校验hash-token的有效性并下发cookie。然后跳转到redirect页。
3. next.js server page：注册结果展示。

1. sb-xxxxxx-auth-token-code-verifier 这里的作用是什么？

NEXT_LOCALE=zh-CN; 
_ga=GA1.1.1259344727.1718294160; 
_ga_V8MB0D7SQD=GS1.1.1718294160.1.1.1718294177.0.0.0; 
sb-isejhdrfjxyjopdeicns-auth-token-code-verifier=%22a48e28fe9386515dbb5eb9d9b50c5111d51f7c17a0fb2908e2216ba3e31cdf95f91f4653b1d26b39e1e9d7deafbb6ee1e376ec2d3a692e9d%22

登录（signin）

1. web请求登录页，next.js server 登录page返回ssr登录页，里面包含一个含表单的页面。
2. web: 用户输入sigin相关字段（email、password），web端参数合法性校验，通过next action将form参数提交给next server。
3. next server action：校验参数合法性，然后调用 supabase.auth.signInWithPassword(formData) 完成登录，返回成功、失败。登录成功SDK会下发auth token到cookie中（key格式为 sb-xxxxxx-auth-token）。
   [javascript] Copy

   async signInWithPassword(
     credentials: SignInWithPasswordCredentials
   ): Promise<AuthTokenResponsePassword> {
   	res = await _request(this.fetch, 'POST', `${this.url}/token?grant_type=password`, {
   	    headers: this.headers,
   	    body: {
   	      email,
   	      password,
   	      gotrue_meta_security: { captcha_token: options?.captchaToken },
   	    },
   	    xform: _sessionResponsePassword,
   	  })
   	const { data, error } = res
   	if (data.session) {
   	  await this._saveSession(data.session)
   	  await this._notifyAllSubscribers('SIGNED_IN', data.session)
   	}
   }
   
   private async _saveSession(session: Session) {
     this._debug('#_saveSession()', session)
     // _saveSession is always called whenever a new session has been acquired
     // so we can safely suppress the warning returned by future getSession calls
     this.suppressGetSessionWarning = true
     await setItemAsync(this.storage, this.storageKey, session)
   }
   
   // Storage helpers
   export const setItemAsync = async (
     storage: SupportedStorage,
     key: string,
     data: any
   ): Promise<void> => {
     await storage.setItem(key, JSON.stringify(data))
   }

4. web: 展示响应结果，然后跳转到登录结果页面。
   1. 官网demo中，是在action下发了redirect结果。一样的效果。
   2. 跳转是否必须？ 不是，可以不跳转。在action就已经下发了token到cookie，此时已经处于登录状态。

密码重置（reset password）

登出（logout）

async function signout() {
  "use server";

  // getSession():
  // Since the unencoded session data is retrieved from the local storage medium, 
  // do not rely on it as a source of trusted data on the server. It could be tampered with by the sender. 
  // If you need verified, trustworthy user data, call getUser instead.
  const supabase = createClient()
  const {
    data: { session },
  } = await supabase.auth.getSession()

  if (session) {
    await supabase.auth.signOut()
  }

  console.log("Signed out")
  redirect("/")
}

其它细节

• 通过 verifyOtp 获得的session与通过signInWithPassword 获得的登录token/session有何不同？

• 为何OTP邮件的第一跳地址必须是通用confirm（代理），然后再跳转对应场景的结果页？

Good to know: HTTP does not allow setting cookies after streaming starts, so you must use .set() in a Server Action or Route Handler.

• 注意在middleware中增加getUser的调用，因为每次页面访问都可能会更新cookie（refreshtoken）。
• 业务逻辑中可能会有大量的getUser调用。处于性能考虑和频率限制的可能，next项目中建议使用react-cache进行一次封装。
• 如何查看API文档？参考swagger文档，可以使用petstore查看。
• supabase该如何部署？可以使用官方的免费版本，也可以自行部署。免费版本一段时间后会自动停掉（pause），需要手工recover，所以推荐使用自部署版本，功能上没有大的差异。个人项目一台腾讯云的轻量服务器足矣，部署方式可以参考这里 supbase-docker 。嫌麻烦的推荐官方付费版本。

结语

参考资料

• Setting up Server-Side Auth for Next.js
• Authentication in Next.js with Supabase Auth and PKCE