NuxtAuth

Appearance

Star 0

Local provider ​

This guide is for setting up @sidebase/nuxt-auth with the Local Provider, which is best suited for when you already have a backend that accepts username + password as a login or want to build a static application. The Local Provider also supports refresh tokens since v0.9.0.

Configuration ​

The entire configuration for the local provider is contained inside the nuxt.config.ts. Inside the auth options, set your provider to local.

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

API endpoints ​

Afterwards, you can define the endpoints to which the authentication requests will be made:

ts
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' },
      }
    }
  }
})

Each endpoint, consists of an object, with a path and method. When a user triggers an action inside your application a request will be made to each endpoint. When a request is made to the getSession endpoint, a token will be sent as a header. You can configure the headers and token below.

In the example above, we define a runtime config value with the baseURL using the originEnvKey, which results in requests being made to the following URLs:

  • Sign in: /api/auth/login (POST)
  • Sign out /api/auth/logout (POST)
  • Sign up: /api/auth/register (POST)
  • Get Session: /api/auth/session (GET)

You can customize each endpoint to fit your needs or disable it by setting it to false. For example you may want to disable the signUp endpoint.

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

WARNING

You cannot disable the getSession endpoint, as NuxtAuth internally uses it to determine the authentication status.

Using an external backend ​

You can also set your endpoints to query an external backend:

ts
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' },
      }
    }
  }
})

Token ​

The local and refresh providers are both based on exchanging access tokens with your backend. NuxtAuth expects an access token to be provided by the signIn endpoint, which will then be saved into the session to authenticate further requests to e.g. getSession.

The configuration of the token properties depend on how your backend accepts and returns data. The options are designed to be as adaptable as possible, to account for many different types of backends.

ts
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 ​

  • Type: string
  • Default: '/token'

How to extract the authentication-token from the sign-in response.

For example, if you have a response object like { token: { bearer: 'THE_AUTH_TOKEN' }, timestamp: '2023' }, using signInResponseTokenPointer: '/token/bearer' will result in nuxt-auth extracting and storing THE_AUTH_TOKEN.

This follows the JSON Pointer standard, see it's RFC6901 here: https://www.rfc-editor.org/rfc/rfc6901

type ​

Header type to be used in requests. This in combination with headerName is used to construct the final authentication-header nuxt-auth uses, e.g. for requests via getSession.

  • Type: string
  • Default: 'Bearer'

cookieName ​

Refers to the name of the property when it is stored in a cookie.

  • Type: string
  • Default: 'auth.token'

headerName ​

Header name to be used in requests that need to be authenticated, e.g., to be used in the getSession request.

  • Type: string
  • Default: 'Authorization'

maxAgeInSeconds ​

Maximum age to store the authentication token for. After the expiry time the token is automatically deleted on the application side, i.e. in the user's browser.

Note: Your backend may reject / expire the token earlier / differently.

  • Type: number
  • Default: 1800

sameSiteAttribute ​

The cookie sameSite policy. Can be used as a form of CSRF protection. If set to strict, the cookie will only be passed with requests to the same 'site'. Typically, this includes subdomains. So, a sameSite: strict cookie set by app.mysite.com will be passed to api.mysite.com, but not api.othersite.com.

See the specification here: https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7

  • Type: boolean | 'lax' | 'strict' | 'none' | undefined
  • Default: 'lax'

cookieDomain ​

The cookie domain. See the specification here: https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.3

  • Type: string
  • Default: ''

secureCookieAttribute ​

If set, the cookie will be only sent through HTTPS protocol. See the specification here : https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.5

  • Type: boolean
  • Default: 'false'

httpOnlyCookieAttribute ​

If set, the cookie will not be accessible from JavaScript. See the specification here : https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.6

  • Type: boolean
  • Default: 'false'

Refresh ​

A seperate refresh configuration can also be passed to configure how the refresh token is handled.

ts
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 ​

  • Type: boolean
  • Default: false

If the local provider should make automatic refresh requests to retrieve a new new token. If isEnabled is set to:

  • false: The provider will behave like the local provider prior to v0.9.0
  • true: The provider will behave like the refresh provider prior tov0.9.0

endpoint ​

  • Type: boolean
  • Default: { path: '/refresh', method: 'post' }

The endpoint to which refresh requests are made. The configuration of the refresh endpoint matches the configuration of the other endpoints. Read more here.

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

refreshOnlyToken ​

  • Type: boolean
  • Default: true

When refreshOnlyToken is set, only the token will be refreshed and the refreshToken will stay the same. (This is helpful when only the login endpoint returns a refreshToken)

token ​

signInResponseRefreshTokenPointer ​

  • Type: string
  • Default: '/refreshToken'

How to extract the authentication-refreshToken from the sign-in response.

E.g., setting this to /token/refreshToken and returning an object like { token: { refreshToken: 'THE_REFRESH__TOKEN' }, timestamp: '2023' } from the signIn endpoint will result in nuxt-auth extracting and storing THE_REFRESH__TOKEN.

This follows the JSON Pointer standard, see its RFC6901 here: https://www.rfc-editor.org/rfc/rfc6901

refreshResponseTokenPointer ​

  • Type: string
  • Default: ''

How to extract the authentication-token from the refresh response.

E.g., setting this to /token/bearer and returning an object like { token: { bearer: 'THE_AUTH_TOKEN' }, timestamp: '2023' } from the refresh endpoint will result in nuxt-auth extracting and storing THE_AUTH_TOKEN.

If not set, token.signInResponseTokenPointer will be used instead.

This follows the JSON Pointer standard, see its RFC6901 here: https://www.rfc-editor.org/rfc/rfc6901

refreshRequestTokenPointer ​

  • Type: string
  • Default: '/refreshToken'

How to do a fetch for the refresh token. This is especially useful when you have an external backend signing tokens. Refer to this issue to get more information: https://github.com/sidebase/nuxt-auth/issues/635.

cookieName ​

  • Type: string
  • Default: 'auth.refresh-token'

It refers to the name of the property when it is stored in a cookie.

maxAgeInSeconds ​

  • Type: number
  • Default: 1800

Maximum age to store the authentication token for. After the expiry time the token is automatically deleted on the application side, i.e. in the user's browser.

Note: Your backend may reject / expire the refreshToken earlier / differently.

cookieDomain ​

  • Type: string
  • Default: ''

The cookie domain. See the specification here: https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.3

secureCookieAttribute ​

If set, the cookie will be only sent through HTTPS protocol. See the specification here : https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.5

  • Type: boolean
  • Default: 'false'

httpOnlyCookieAttribute ​

If set, the cookie will not be accessible from JavaScript. See the specification here : https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.6

  • Type: boolean
  • Default: 'false'

Pages ​

Configure the path of the login-page that the user should be redirected to, when they try to access a protected page without being logged in. This page will also not be blocked by the global middleware.

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

Released under the MIT License.

Developed by SIDESTREAM