Auth Module Simple

Authentication support for Nuxt 3

## nuxt-simple-auth
[](https://www.npmjs.com/package/nuxt-simple-auth)  [](https://www.npmjs.com/package/nuxt-simple-auth) [][nuxt-href] [](https://github.com/sponsors/4sllan) - [发布说明](/CHANGELOG.md) ## 开始 ``` npx nuxi@latest module add nuxt-simple-auth ``` ## 设置 ### 安装 ### 配置 必须在 `nuxt.config.js` 文件中进行配置，将库添加到 **modules** 部分。 在 `auth` 属性中，定义 **strategies** 是 **必须的**，而 **cookies** 和 **CSRF** 设置是 **可选的**。 对于身份验证，`endpoints.login` 属性需要使用 **Laravel Passport**，它必须公开 `/oauth/token` 路由。 [Laravel Passport 文档 - 客户端凭证授权令牌](https://laravel.com/docs/12.x/passport#client-credentials-grant-tokens) 此路由必须返回包含以下属性的 JSON 响应： - `access_token` - `refresh_token` - `expires_in` 如果您选择使用 **2FA** 身份验证，该包需要配置 `endpoints.2fa`，这要求 **Laravel** 公开一个特定的路由。 此路由应返回包含以下属性的 JSON 响应： - `access_token` - `expires_in` `expires_in`：必须是 **2FA** 访问令牌过期的秒数。 **2FA** 验证通过后，令牌将自动作为 **Bearer Token** 添加到请求的 **headers** 中，名称为 `"2fa"`。 这允许 **Laravel APIs** 在受保护的路由上验证身份验证。 #### 示例 ``` export default defineNuxtConfig({ modules: [ 'nuxt-simple-auth' ], auth: { csrf: '/csrf-token', cookie: { options: { httpOnly: true, secure: true, sameSite: 'Lax', priority: 'high', }, prefix: '__Secure-auth.' }, strategies: { local: { redirect: { logout: "/auth", login: "/auth" }, user: { property: "profile", }, endpoints: { login: {url: "/oauth/token", method: "post", alias: "auth token"}, user: {url: "/api/profile", method: "get"}, "2fa": {url: "/api/send-token-2fa", method: "post"}, }, } } }, }); ``` ### 运行时配置 Nuxt 3 的 **runtimeConfig** 也必须进行配置以包含一个 `secret` 对象。 此对象应包含您的 **strategies** 的名称，并且在每个 strategy 中，以下键是 **必须的**： - [`client_id`](https://laravel.com/docs/12.x/passport#main-content) - [`client_secret`](https://laravel.com/docs/12.x/passport#main-content) - [`grant_type`](https://laravel.com/docs/12.x/passport#main-content) #### 配置示例： ``` export default defineNuxtConfig({ runtimeConfig: { secret: { local: { client_id: 'YOUR_CLIENT_ID', client_secret: 'YOUR_CLIENT_SECRET', grant_type: 'password', }, client: { client_id: 'YOUR_CLIENT_ID', client_secret: 'YOUR_CLIENT_SECRET', grant_type: 'authorization_code', } } } }); ``` ### 策略 **strategies** 配置遵循以下结构，以您选择的名称开始设置包。 列出了可用选项，指出了哪些是 **必须的**，哪些是 **可选的**。 #### 配置 - **`redirect`**：定义重定向的页面。_（必须）_ - `login`：_（可选）_ - `logout`：_（必须）_ - `callback`：_（可选）_ - `home`：_（可选）_ - **`endpoints`**：定义 Laravel 中配置的 API 路由。_（必须）_ - `login`：_（必须）_ - `url`：_（必须）_ - `method`：_（必须）_ - `alias`：_（可选）_ - `user`：包含用户数据。_（必须）_ - `url`：_（必须）_ - `method`：_（必须）_ - `"2fa"`：_（可选）_ - `url`：_（必须）_ - `method`：_（必须）_ - `alias`：_（可选）_ - `logout`：_（可选）_ - `alias`：_（可选）_ - **`user`**：包含用户数据的对象名称。_（可选）_ ``` strategies: { local: { redirect: { logout: "/auth", login: "/auth" }, user: { property: "profile", }, endpoints: { login: {url: "/oauth/token", method: "post", alias: "auth token"}, user: {url: "/api/profile", method: "get"}, "2fa": {url: "/api/send-token-2fa", method: "post"}, }, }, client:{ redirect: { logout: "/auth", login: "/auth" }, endpoints: { login: {url: "/oauth/token", method: "post"}, user: {url: "/api/profile", method: "get"}, "2fa": {url: "/api/send-token-2fa", method: "post"}, logout: {alias: 'logout client'} }, } } ``` **2FA** 是可选的，但如果包含在某个 "strategies" 中，它必须具有 URL 和方法才能启用 "_2fa" 中间件。此中间件不是全局的，可以在 Nuxt 页面上选择性地使用。 ``` definePageMeta({ middleware: ['auth', '_2fa'] }); ``` ### Cookie | 选项 | 描述 | |-------------|------------------------------------------------------------------------------------------------------------------------| | **prefix** | 用于构建令牌存储键的默认令牌前缀。 | | **options** | 额外的 cookie 选项，传递给 [cookie](https://github.com/jshttp/cookie?tab=readme-ov-file)。 | | **path** | cookie 可见的路径。默认为 `/`。 | | **expires** | 指定 cookie 的生命周期，以天数表示，或指定一个具体日期。默认为仅会话期间有效。 | | **maxAge** | 指定 Max-Aage 值的数字（以秒为单位）（最好是已过期的）。 | | **domain** | cookie 可见的域（以及扩展的子域）。默认为该域及其所有子域。 | | **secure** | 定义 cookie 是否需要安全协议 (HTTPS)。默认为 `false`，如果可能应设置为 `true`。 | ### 注意事项： - 默认情况下，`localhost` 上的前缀设置为 `"auth."` - **`__Secure-` 前缀：** 名称以 `__Secure-` 开头的 cookie（破折号是前缀的一部分）必须从安全页面 (HTTPS) 设置 secure 标志。 - **`__Host-` 前缀：** 名称以 `__Host-` 开头的 cookie 必须设置 secure 标志，必须源自安全页面 (HTTPS)，不能指定域（因此不会发送到子域），并且路径必须为 `/`。 ``` cookie: { options: { httpOnly: true, secure: true, sameSite: 'Lax', priority: 'high', //maxAge: 24 * 60 * 60 * 1000, }, prefix: '__Secure-auth.', } ``` ### 中间件 **nuxt-simple-auth** 包提供两个中间件：**"auth"** 和 **"_2fa"**。 它们 **不是全局的**，可以选择性地应用于 Nuxt 页面。 - **auth**：限制对受保护页面的访问，确保用户通过 **Laravel Passport** 进行了身份验证，包括在客户端和服务器端 (**SSR**)。 - **_2fa**：通过验证存储在 **cookies** 和 **sessionStorage** 中的值来增强身份验证，以验证 **双因素认证 (2FA)**，同样在客户端和服务器端 (**SSR**) 上工作。 ``` definePageMeta({ middleware: ['auth', '_2fa'] }); ``` ### 方法 | 方法 / Method | 描述 | |------------------------------------|----------------------------------------------------------------------------------------| | `loginWith(strategyName, ...args)` | 设置当前策略并尝试登录。返回一个 `Promise`。 | | `logout(strategyName)` | 登出，确保销毁 cookies 和状态。 | | `_2fa(strategyName, ...args)` | 尝试验证双因素认证 (**2FA**) 代码。返回一个 `Promise`。 | | `refreshToken(strategyName)` | | | `$auth.headers.set(name, value)` | 手动设置一个 HTTP header。 | | `$auth.headers.get(name)` | 获取一个 HTTP header 的值。 | ### 使用示例 #### `loginWith` ``` const {$auth} = useNuxtApp() $auth.loginWith('local', data) .then(response => { // Logic after login }) ``` #### `logout` ``` const {$auth} = useNuxtApp() $auth.logout('local') ``` #### `_2fa` ``` $auth._2fa('local', data).then(response => { // Logic after 2FA validation }) ``` #### Headers and Requests ``` $auth.headers.set('name', 'value') // Sets a header $auth.headers.get('name') // Retrieves a header const {data, pending, error, refresh} = useFetch(url, { headers: $auth.headers, }) ``` ## ⚖️ 许可证 由 [@4slan](https://github.com/4sllan) 基于 [MIT](/LICENSE) 发布。

标签：2FA, CMS安全, CSRF 防护, Full Stack, httpOnly Cookie, JavaScript, Laravel Passport, Laravel Sanctum, Nuxt 3, Nuxt 模块, OAuth2, SSR, Token 管理, TypeScript, Web 安全, 会话管理, 双因素认证, 域名收集, 安全插件, 服务端渲染, 用户登录, 自动化攻击, 自动化攻击, 认证模块