Cookie Authentication

Usage

By default, the module provides configuration to integrate seamlessly with Laravel Sanctum authentication based on the XSRF token.

To explicitly set this authentication mode, update sanctum.mode configuration property to cookie.

You can check the official Laravel documentation here - SPA Authentication.

How it works

First, you need to authenticate a user by submitting credentials to endpoints.login endpoint:

const { login } = useSanctumAuth()

const credentials = {
    email: "john@doe.com",
    password: "password",
    remember: true,
}

await login(credentials)

The client will be automatically redirected to redirect.onLogin route of your application.

Once the module has an authentication state, it will take care of requesting a CSRF cookie from the API and passing it as an XSRF header to each subsequent request as well as passing all other headers and cookies from CSR to SSR requests.

You can also extend default interceptors and add your information into headers or cookie collections.

To check other available methods, please refer to the composables section.

SSR streaming support

The module is compatible with Nuxt's experimental.ssrStreaming mode.

With streaming enabled, the response headers are committed with the HTML shell before the page finishes rendering, so cookies received later during SSR cannot be forwarded to the client directly. To keep the authentication flow working, the module:

1. Initializes the CSRF cookie during plugin setup, while the response headers are still writable
2. Queues any cookies received after the headers are committed and writes the non-HttpOnly ones to the client after hydration
3. Re-establishes HttpOnly session cookies with an additional credentialed CSRF request, which makes the browser store them natively

Make sure your CSRF endpoint does not respond with a session cookie, or your session cookie is not HttpOnly, so the module can forward it to the browser after hydration. In the latter case, an extra CSRF request will be sent on the first load to restore the session.

Laravel configuration

Your Laravel API should be configured properly to support Nuxt domain and share cookies:

• The Nuxt application domain should be registered in stateful domain list (SANCTUM_STATEFUL_DOMAINS)
• The Nuxt application domain should be registered in config/cors.php in allowed_origins domain list
• Also config/cors.php configuration should have support_credentials=true
• Sanctum statefulApi middleware should be enabled
• The top-level domain should be used for the session (SESSION_DOMAIN=.domain.com), or localhost during development (without port)

If you notice incorrect behavior of the module or authentication flow, feel free to raise an issue!