本地提供商
本指南适用于使用本地提供商设置 @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'
}
}
}
})