https://github.com/4sllan/nuxt-simple-auth
AuthX
https://github.com/4sllan/nuxt-simple-auth
auth fecth laravel laravel-passport module nuxt nuxt-module nuxt3 security ssr token
Last synced: 3 months ago
JSON representation
AuthX
- Host: GitHub
- URL: https://github.com/4sllan/nuxt-simple-auth
- Owner: 4sllan
- License: mit
- Created: 2023-12-13T18:03:09.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-01T23:30:11.000Z (3 months ago)
- Last Synced: 2025-04-11T04:02:27.377Z (3 months ago)
- Topics: auth, fecth, laravel, laravel-passport, module, nuxt, nuxt-module, nuxt3, security, ssr, token
- Language: TypeScript
- Homepage:
- Size: 393 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
Auth Module Simple
Authentication support for Nuxt 3
## nuxt-simple-auth
[](https://www.npmjs.com/package/nuxt-simple-auth)
![GitHub License][license]
[](https://www.npmjs.com/package/nuxt-simple-auth)
[![Nuxt][nuxt-src]][nuxt-href]
[](https://github.com/sponsors/4sllan)
> **nuxt-simple-auth** is an authentication module for **Nuxt 3**, designed as an **open-source**, **robust**, and *
*feature-rich** package. It enables **cookie** validation and **CSRF** protection, seamlessly integrating with **Laravel
Passport**.\
> Additionally, it supports various cookie parameters for both **login** and **two-factor authentication (2FA)**.\
> It also includes **SSR authentication** support, ensuring that the user remains authenticated on both the **client**
> and the **server**.
> While the package is stable in terms of options and behavior, there are still improvements to be made, and some bugs
> may exist.
- [Release Notes](/CHANGELOG.md)
## Start
```sh
npx nuxi@latest module add nuxt-simple-auth
```
## Setup
### Installation
> **Add `nuxt-simple-auth` to the `modules` section in `nuxt.config.js`.**
### Configuration
The configuration must be done in the `nuxt.config.js` file by adding the library to the **modules** section.
In the `auth` property, defining **strategies** is **mandatory**, while **cookies** and **CSRF** settings are **optional
**.
For authentication, the `endpoints.login` property requires the use of **Laravel Passport**, which must expose
the `/oauth/token` route.
[Laravel Passport Documentation - Client Credentials Grant Tokens](https://laravel.com/docs/12.x/passport#client-credentials-grant-tokens)
This route must return a JSON response containing the following attributes:
- `access_token`
- `refresh_token`
- `expires_in`
If you choose to use **2FA** authentication, the package requires the configuration of `endpoints.2fa`, which mandates
that **Laravel** exposes a specific route.
This route should return a JSON response with the following attributes:
- `access_token`
- `expires_in`
`expires_in`: Must be the number of seconds until the **2FA** access token expires.
[//]: # (Example implementation in Laravel for the `TwoFactorAuthController` route controller:)
[//]: # ()
[//]: # (```php)
[//]: # (return response()->json([)
[//]: # ( 'access_token' => $twoFactorAuth->token,)
[//]: # ( 'expires_in' => $twoFactorAuth->expire_at->timestamp - now()->timestamp, // Number of seconds until expiration.)
[//]: # (]);)
[//]: # (```)
After **2FA** validation, the token will be automatically added to the **headers** of requests as a **Bearer Token**,
with the name `"2fa"`.
This allows **Laravel APIs** to validate authentication on protected routes.
#### Example
```js
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"},
},
}
}
},
});
```
### Runtime Config
The **runtimeConfig** of Nuxt 3 must also be configured to include a `secret` object.
This object should contain the names of your **strategies**, and within each strategy, the following keys are **required
**:
- [`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)
#### Example Configuration:
```js
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
The **strategies** configuration follows the structure below, starting with a name of your choice to set up the
package.
The available options are listed, indicating which are **required** and which are **optional**.
#### Configuration
- **`redirect`**: Defines the pages for redirection. _(Required)_
- `login`: _(Optional)_
- `logout`: _(Required)_
- `callback`: _(Optional)_
- `home`: _(Optional)_
- **`endpoints`**: Defines the API routes configured in Laravel. _(Required)_
- `login`: _(Required)_
- `url`: _(Required)_
- `method`: _(Required)_
- `alias`: _(Optional)_
- `user`: Contains user data. _(Required)_
- `url`: _(Required)_
- `method`: _(Required)_
- `"2fa"`: _(Optional)_
- `url`: _(Required)_
- `method`: _(Required)_
- `alias`: _(Optional)_
- `logout`: _(Optional)_
- `alias`: _(Optional)_
- **`user`**: Name of the object containing user data. _(Optional)_
---
``` js
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** is optional, but if included in one of the "strategies," it must have a URL and method to enable the "_2fa"
middleware. This middleware is not global and can be selectively used on Nuxt pages.
``` js
definePageMeta({
middleware: ['auth', '_2fa']
});
```
### Cookie
| Option | Description |
|-------------|-------------------------------------------------------------------------------------------------------------------------|
| **prefix** | Default token prefix used in constructing a key for token storage. |
| **options** | Additional cookie options, passed to [cookie](https://github.com/jshttp/cookie?tab=readme-ov-file). |
| **path** | Path where the cookie is visible. Default is `/`. |
| **expires** | Specifies the lifetime of the cookie in number of days or a specific date. Default is session-only. |
| **maxAge** | Specifies the number (in seconds) that will be the Max-Age value (preferably expired). |
| **domain** | Domain (and by extension subdomains) where the cookie is visible. Default is the domain and all subdomains. |
| **secure** | Defines whether the cookie requires a secure protocol (HTTPS). Default is `false`, should be set to `true` if possible. |
### Notes:
- By default, the prefix on `localhost` is set to `"auth."`
- **`__Secure-` prefix:** Cookies with names starting with `__Secure-` (dash is part of the prefix) must be set with the
secure flag from a secure page (HTTPS).
- **`__Host-` prefix:** Cookies with names starting with `__Host-` must be set with the secure flag, must originate from
a secure page (HTTPS), must not have a domain specified (and therefore are not sent to subdomains), and the path must
be `/`.
``` js
cookie: {
options: {
httpOnly: true,
secure: true,
sameSite: 'Lax',
priority: 'high',
//maxAge: 24 * 60 * 60 * 1000,
},
prefix: '__Secure-auth.',
}
```
### Middlewares
The **nuxt-simple-auth** package provides two middlewares: **"auth"** and **"_2fa"**.
They are **not global** and can be applied selectively to Nuxt pages.
- **auth**: Restricts access to protected pages, ensuring the user is authenticated via **Laravel Passport**, both on
the client and server (**SSR**).
- **_2fa**: Enhances authentication by verifying values stored in **cookies** and **sessionStorage** to validate *
*two-factor authentication (2FA)**, also working on both the client and server (**SSR**).
``` js
definePageMeta({
middleware: ['auth', '_2fa']
});
```
### Methods
| Método / Method | Description |
|------------------------------------|-----------------------------------------------------------------------------------------|
| `loginWith(strategyName, ...args)` | Sets the current strategy and attempts to log in. Returns a `Promise`. |
| `logout(strategyName)` | Logs out, ensuring the destruction of cookies and state. |
| `_2fa(strategyName, ...args)` | Attempts to validate the two-factor authentication (**2FA**) code. Returns a `Promise`. |
| `refreshToken(strategyName)` | |
| `$auth.headers.set(name, value)` | Sets an HTTP header manually. |
| `$auth.headers.get(name)` | Retrieves the value of an HTTP header. |
---
### Usage Examples
#### `loginWith`
```js
const {$auth} = useNuxtApp()
$auth.loginWith('local', data)
.then(response => {
// Logic after login
})
```
#### `logout`
```js
const {$auth} = useNuxtApp()
$auth.logout('local')
```
#### `_2fa`
```js
$auth._2fa('local', data).then(response => {
// Logic after 2FA validation
})
```
#### `Headers and Requests`
```js
$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,
})
```
## ⚖️ License
Released under [MIT](/LICENSE) by [@4slan](https://github.com/4sllan).
[license]: https://img.shields.io/github/license/4sllan/nuxt-simple-auth?style=flat-square&colorA=18181B&colorB=28CF8D
[nuxt-src]: https://img.shields.io/badge/Nuxt-18181B?logo=nuxt.js
[nuxt-href]: https://nuxt.com