本地提供商

本指南适用于使用本地提供商设置 @sidebase/nuxt-auth，当您已经有一个接受用户名 + 密码作为登录的后端，或者想要构建一个静态应用程序时，本地提供商是最合适的选择。本地提供商从 v0.9.0 版本开始也支持刷新令牌。

配置

local 提供商的完整配置包含在 nuxt.config.ts 文件中。在 auth 选项中，将您的提供商设置为 local。

export default defineNuxtConfig({
  modules: ['@sidebase/nuxt-auth'],
  auth: {
    provider: {
      type: 'local'
    }
  }
})

API 端点

之后，您可以定义将向其发出身份验证请求的端点

export default defineNuxtConfig({
  // ...Previous configuration
  runtimeConfig: {
    baseURL: '/api/auth'
  },
  auth: {
    originEnvKey: 'NUXT_BASE_URL',
    provider: {
      type: 'local',
      endpoints: {
        signIn: { path: '/login', method: 'post' },
        signOut: { path: '/logout', method: 'post' },
        signUp: { path: '/register', method: 'post' },
        getSession: { path: '/session', method: 'get' },
      }
    }
  }
})

每个端点都由一个对象组成，包含 path 和 method。当用户在您的应用程序内触发操作时，将向每个端点发出请求。当向 getSession 端点发出请求时，令牌将作为标头发送。您可以在下面配置标头和令牌。

在上面的示例中，我们使用 originEnvKey 定义了一个带有 baseURL 的运行时配置值，这将导致向以下 URL 发出请求

登录: /api/auth/login (POST)
登出 /api/auth/logout (POST)
注册: /api/auth/register (POST)
获取会话: /api/auth/session (GET)

您可以自定义每个端点以满足您的需求，或者通过将其设置为 false 来禁用它。例如，您可能想要禁用 signUp 端点。

export default defineNuxtConfig({
    auth: {
        provider: {
            type: 'local',
            endpoints: {
                signUp: false
            }
        }
    }
})

警告

您不能禁用 getSession 端点，因为 NuxtAuth 内部使用它来确定身份验证状态。

使用外部后端

您还可以设置您的端点来查询外部后端

export default defineNuxtConfig({
  // ...Previous configuration
  runtimeConfig: {
    baseURL: 'https://example.com/api'
  },
  auth: {
    originEnvKey: 'NUXT_BASE_URL',
    provider: {
      type: 'local',
      endpoints: {
        signIn: { path: '/auth/login', method: 'post' },
        signOut: { path: '/auth/logout', method: 'post' },
        signUp: { path: '/auth/register', method: 'post' },
        getSession: { path: '/user/session', method: 'get' },
      }
    }
  }
})

令牌

local 和 refresh 提供商都基于与您的后端交换访问令牌。NuxtAuth 期望 signIn 端点提供访问令牌，然后将其保存到会话中，以便对例如 getSession 的后续请求进行身份验证。

token 属性的配置取决于您的后端如何接受和返回数据。这些选项旨在尽可能地适应性强，以适应许多不同类型的后端。

export default defineNuxtConfig({
  // Previous configuration
  auth: {
    provider: {
      type: 'local',
      token: {
        signInResponseTokenPointer: '/token',
        type: 'Bearer',
        cookieName: 'auth.token',
        headerName: 'Authorization',
        maxAgeInSeconds: 1800,
        sameSiteAttribute: 'lax',
        cookieDomain: 'sidebase.io',
        secureCookieAttribute: false,
        httpOnlyCookieAttribute: false,
      }
    }
  }
})

`signInResponseTokenPointer`

类型: string
默认值: '/token'

如何从登录响应中提取身份验证令牌。

例如，如果您有一个像 { token: { bearer: 'THE_AUTH_TOKEN' }, timestamp: '2023' } 这样的响应对象，使用 signInResponseTokenPointer: '/token/bearer' 将导致 nuxt-auth 提取并存储 THE_AUTH_TOKEN。

这遵循 JSON Pointer 标准，请参阅 RFC6901： https://www.rfc-editor.org/rfc/rfc6901

`type`

请求中要使用的标头类型。这与 headerName 结合使用来构建 nuxt-auth 使用的最终身份验证标头，例如，用于通过 getSession 发出的请求。

类型: string
默认值: 'Bearer'

`cookieName`

指存储在 cookie 中时属性的名称。

类型: string
默认值: 'auth.token'

`headerName`

需要在身份验证的请求中使用的标头名称，例如，在 getSession 请求中使用。

类型: string
默认值: 'Authorization'

`maxAgeInSeconds`

存储身份验证令牌的最长时间。在过期时间之后，令牌将在应用程序端（即用户的浏览器中）自动删除。

注意：您的后端可能会更早/以不同的方式拒绝/过期令牌。

类型: number
默认值: 1800

`sameSiteAttribute`

Cookie 的 sameSite 策略。可以用作 CSRF 保护的一种形式。如果设置为 strict，则 cookie 将仅与对同一“站点”的请求一起传递。通常，这包括子域名。因此，由 app.mysite.com 设置的 sameSite: strict cookie 将传递给 api.mysite.com，但不会传递给 api.othersite.com。

请参阅此处的规范： https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7

类型: boolean | 'lax' | 'strict' | 'none' | undefined
默认值: 'lax'

`cookieDomain`

Cookie 域。请参阅此处的规范： https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.3

类型: string
默认值: ''

`secureCookieAttribute`

如果设置，cookie 将仅通过 HTTPS 协议发送。请参阅此处的规范： https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.5

类型: boolean
默认值: 'false'

`httpOnlyCookieAttribute`

如果设置，则无法从 JavaScript 访问 cookie。请参阅此处的规范： https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.6

类型: boolean
默认值: 'false'

刷新

也可以传递单独的 refresh 配置来配置如何处理刷新令牌。

export default defineNuxtConfig({
  auth: {
    provider: {
      type: 'local',
      refresh: {
        isEnabled: true,
        endpoint: { path: '/refresh', method: 'post' },
        refreshOnlyToken: true,
        token: {
          signInResponseRefreshTokenPointer: '/refresh-token',
          refreshResponseTokenPointer: '',
          refreshRequestTokenPointer: '/refresh-token',
          cookieName: 'auth.token',
          maxAgeInSeconds: 1800,
          sameSiteAttribute: 'lax',
          secureCookieAttribute: false,
          cookieDomain: 'sidebase.io',
          httpOnlyCookieAttribute: false,
        }
      },
    }
  }
})

`isEnabled`

类型: boolean
默认值: false

本地提供商是否应自动发出 refresh 请求以检索新的 token。如果 isEnabled 设置为

false: 提供商的行为将类似于 v0.9.0 之前的 local 提供商
true: 提供商的行为将类似于 v0.9.0 之前的 refresh 提供商

`endpoint`

类型: boolean
默认值: { path: '/refresh', method: 'post' }

发出 refresh 请求的端点。refresh 端点的配置与其他端点的配置匹配。阅读更多此处。

export default defineNuxtConfig({
  auth: {
    provider: {
      type: 'local',
      refresh: {
        endpoint: {
          path: '/refresh',
          method: 'post'
        }
      }
    }
  }
})

`refreshOnlyToken`

类型: boolean
默认值: true

当 refreshOnlyToken 设置时，只会刷新 token，而 refreshToken 将保持不变。（当只有 login 端点返回 refreshToken 时，这很有用）

`token`

`signInResponseRefreshTokenPointer`

类型: string
默认值: '/refreshToken'

如何从登录响应中提取身份验证刷新令牌。

例如，将此设置为 /token/refreshToken 并从 signIn 端点返回类似 { token: { refreshToken: 'THE_REFRESH__TOKEN' }, timestamp: '2023' } 的对象将导致 nuxt-auth 提取并存储 THE_REFRESH__TOKEN。

这遵循 JSON Pointer 标准，请参阅其 RFC6901： https://www.rfc-editor.org/rfc/rfc6901

`refreshResponseTokenPointer`

类型: string
默认值: ''

如何从刷新响应中提取身份验证令牌。

例如，将此设置为 /token/bearer 并从 refresh 端点返回类似 { token: { bearer: 'THE_AUTH_TOKEN' }, timestamp: '2023' } 的对象将导致 nuxt-auth 提取并存储 THE_AUTH_TOKEN。

如果未设置，则将使用 token.signInResponseTokenPointer 代替。

这遵循 JSON Pointer 标准，请参阅其 RFC6901： https://www.rfc-editor.org/rfc/rfc6901

`refreshRequestTokenPointer`

类型: string
默认值: '/refreshToken'

如何获取刷新令牌。当您有外部后端签署令牌时，这尤其有用。请参阅此问题以获取更多信息： https://github.com/sidebase/nuxt-auth/issues/635。

`cookieName`

类型: string
默认值: 'auth.refresh-token'

它指的是存储在 cookie 中时属性的名称。

`maxAgeInSeconds`

类型: number
默认值: 1800

存储身份验证令牌的最长时间。在过期时间之后，令牌将在应用程序端（即用户的浏览器中）自动删除。

注意：您的后端可能会更早/以不同的方式拒绝/过期 refreshToken。

`cookieDomain`

类型: string
默认值: ''

Cookie 域。请参阅此处的规范： https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.3

`secureCookieAttribute`

如果设置，cookie 将仅通过 HTTPS 协议发送。请参阅此处的规范： https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.5

类型: boolean
默认值: 'false'

`httpOnlyCookieAttribute`

如果设置，则无法从 JavaScript 访问 cookie。请参阅此处的规范： https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.6

类型: boolean
默认值: 'false'

页面

配置用户在尝试访问未登录的受保护页面时应重定向到的登录页面的路径。此页面也不会被全局中间件阻止。

export default defineNuxtConfig({
  // previous configuration
  auth: {
    provider: {
      type: 'local',
      pages: {
        login: '/login'
      }
    }
  }
})

本地提供商 ​

配置 ​

API 端点 ​

使用外部后端 ​

令牌 ​

signInResponseTokenPointer ​

type ​

cookieName ​

headerName ​

maxAgeInSeconds ​

sameSiteAttribute ​

cookieDomain ​

secureCookieAttribute ​

httpOnlyCookieAttribute ​

刷新 ​

isEnabled ​

endpoint ​

refreshOnlyToken ​

token ​

signInResponseRefreshTokenPointer ​

refreshResponseTokenPointer ​

refreshRequestTokenPointer ​

cookieName ​

maxAgeInSeconds ​

cookieDomain ​

secureCookieAttribute ​

httpOnlyCookieAttribute ​

页面 ​

本地提供商

配置

API 端点

使用外部后端

令牌

`signInResponseTokenPointer`

`type`

`cookieName`

`headerName`

`maxAgeInSeconds`

`sameSiteAttribute`

`cookieDomain`

`secureCookieAttribute`

`httpOnlyCookieAttribute`

刷新

`isEnabled`

`endpoint`

`refreshOnlyToken`

`token`

`signInResponseRefreshTokenPointer`

`refreshResponseTokenPointer`

`refreshRequestTokenPointer`

`cookieName`

`maxAgeInSeconds`

`cookieDomain`

`secureCookieAttribute`

`httpOnlyCookieAttribute`

页面