认证

AdonisJS 附带一个强大且安全的认证系统，你可以使用它来登录和认证应用程序的用户。无论是服务器渲染的应用程序、SPA 客户端还是移动应用程序，你都可以为它们设置认证。

认证包围绕守卫和提供者构建。

守卫是特定登录类型的端到端实现。例如，session 守卫允许你使用 cookies 和 session 认证用户。同时，access_tokens 守卫使你能够使用令牌认证客户端。
提供者用于从数据库中查找用户和令牌。你可以使用内置提供者或实现自己的提供者。

TIP

为确保应用程序的安全性，我们正确地对用户密码和令牌进行哈希处理。此外，AdonisJS 的安全原语受到计时攻击和会话固定攻击的保护。

Auth 包不支持的功能

auth 包专注于认证 HTTP 请求，以下功能不在其范围内。

用户注册功能，如注册表单、电子邮件验证和帐户激活。
帐户管理功能，如密码恢复或电子邮件更新。
分配角色或验证权限。相反，使用 bouncer 在应用程序中实现授权检查。

选择认证守卫

以下内置认证守卫为你提供最直接的用户认证工作流，同时不会影响应用程序的安全性。此外，你可以为自定义需求构建自己的认证守卫。

Session

session 守卫使用 @adonisjs/session 包在 session 存储中跟踪登录用户状态。

Session 和 cookies 在互联网上已经存在很长时间，对大多数应用程序都很有效。我们建议在以下情况使用 session 守卫：

如果你正在创建服务器渲染的 Web 应用程序。
或者，一个 AdonisJS API，其客户端在同一顶级域上。例如，api.example.com 和 example.com。

访问令牌

访问令牌是成功登录后发给用户的加密安全随机令牌（也称为不透明访问令牌）。你可以将访问令牌用于 AdonisJS 服务器无法写入/读取 cookies 的应用程序。例如：

原生移动应用程序。
托管在与 AdonisJS API 服务器不同域上的 Web 应用程序。

使用访问令牌时，你的客户端应用程序有责任安全地存储它们。访问令牌提供对应用程序的无限制访问（代表用户），泄露它们可能导致安全问题。

Basic auth

basic auth 守卫是 HTTP 认证框架的实现，其中客户端必须通过 Authorization 头以 base64 编码字符串的形式传递用户凭据。

实现安全登录系统有比基本认证更好的方法。但是，你可以在应用程序处于活跃开发阶段时临时使用它。

选择用户提供者

如本指南前面所述，用户提供者负责在认证过程中查找用户。

用户提供者是守卫特定的；例如，session 守卫的用户提供者负责通过其 ID 查找用户，而访问令牌守卫的用户提供者还负责验证访问令牌。

我们为内置守卫提供 Lucid 用户提供者，它使用 Lucid 模型查找用户、生成令牌和验证令牌。

安装

认证系统预配置在 web 和 api 入门套件中。但是，你可以按如下方式在应用程序中手动安装和配置它。

# 使用 session 守卫配置（默认）
node ace add @adonisjs/auth --guard=session

# 使用访问令牌守卫配置
node ace add @adonisjs/auth --guard=access_tokens

# 使用 basic auth 守卫配置
node ace add @adonisjs/auth --guard=basic_auth

:::disclosure

使用检测到的包管理器安装 @adonisjs/auth 包。

在 adonisrc.ts 文件中注册以下服务提供者。

{
  providers: [
    // ...其他提供者
    () => import('@adonisjs/auth/auth_provider')
  ]
}

在 start/kernel.ts 文件中创建并注册以下中间件。

router.use([
  () => import('@adonisjs/auth/initialize_auth_middleware')
])

router.named({
  auth: () => import('#middleware/auth_middleware'),
  // 仅在使用 session 守卫时
  guest: () => import('#middleware/guest_middleware')
})

在 app/models 目录中创建 user 模型。
为 users 表创建数据库迁移。
为选定的守卫创建数据库迁移。 :::

Initialize auth 中间件

在设置期间，我们在你的应用程序中注册 @adonisjs/auth/initialize_auth_middleware。该中间件负责创建 Authenticator 类的实例，并通过 ctx.auth 属性与请求的其余部分共享它。

请注意，initialize auth 中间件不会认证请求或保护路由。它仅用于初始化认证器并与请求的其余部分共享。你必须使用 auth 中间件来保护路由。

此外，相同的认证器实例与 Edge 模板共享（如果你的应用程序使用 Edge），你可以使用 auth 属性访问它。例如：

edge

@if(auth.isAuthenticated)
  <p> 你好 {{ auth.user.email }} </p>
@end

创建 users 表

configure 命令在 database/migrations 目录中为 users 表创建数据库迁移。请随时打开此文件并根据你的应用程序需求进行更改。

默认情况下，会创建以下列。

import { BaseSchema } from '@adonisjs/lucid/schema'

export default class extends BaseSchema {
  protected tableName = 'users'

  async up() {
    this.schema.createTable(this.tableName, (table) => {
      table.increments('id').notNullable()
      table.string('full_name').nullable()
      table.string('email', 254).notNullable().unique()
      table.string('password').notNullable()

      table.timestamp('created_at').notNullable()
      table.timestamp('updated_at').nullable()
    })
  }

  async down() {
    this.schema.dropTable(this.tableName)
  }
}

此外，如果你在 users 表中定义、重命名或删除列，请更新 User 模型。

后续步骤

了解如何在不影响应用程序安全性的情况下验证用户凭据。
使用 session 守卫进行有状态认证。
使用访问令牌守卫进行基于令牌的认证。

认证 ​

Auth 包不支持的功能 ​

选择认证守卫 ​

Session ​

访问令牌 ​

Basic auth ​

选择用户提供者 ​

安装 ​

Initialize auth 中间件 ​

创建 users 表 ​

后续步骤 ​

认证