Skip to content

Commit

Permalink
Merge branch 'sidebase:main' into option-to-remove-server
Browse files Browse the repository at this point in the history
  • Loading branch information
@KyleSmith0905
KyleSmith0905 authored Dec 14, 2023
2 parents d7148df + 3171771 commit acc827d
Show file tree
Hide file tree
Showing 51 changed files with 1,427 additions and 241 deletions.
31 changes: 30 additions & 1 deletion .github/workflows/ci.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,36 @@ jobs:
# start prod-app and curl from it
- run: "timeout 60 pnpm start & (sleep 45 && curl --fail localhost:3000)"

test-playground-refresh:
runs-on: ubuntu-latest
defaults:
run:
working-directory: ./playground-refresh
steps:
- uses: actions/checkout@v3

- name: Use Node.js 16.14.2
uses: actions/setup-node@v3
with:
node-version: 16.14.2

- uses: pnpm/action-setup@v2
name: Install pnpm
id: pnpm-install
with:
version: 8

# Install deps
- run: pnpm i

# Check building
- run: pnpm build

# start prod-app and curl from it
- run: "timeout 60 pnpm start & (sleep 45 && curl --fail localhost:$PORT)"
env:
AUTH_ORIGIN: "http://localhost:3002"
PORT: 3002

test-playground-authjs:
runs-on: ubuntu-latest
Expand Down Expand Up @@ -97,5 +126,5 @@ jobs:
# start prod-app and curl from it
- run: "timeout 60 pnpm start & (sleep 45 && curl --fail localhost:$PORT)"
env:
AUTH_ORIGIN: 'http://localhost:3001'
AUTH_ORIGIN: "http://localhost:3001"
PORT: 3001
4 changes: 4 additions & 0 deletions SECURITY.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Reporting a security vulnerability

To report a security issue, please email `sidebase@sidestream.tech` with a description of the issue, the steps you took to create the
issue, affected versions, and if known, mitigations for the issue. Our vulnerability management team will acknowledge receiving your email within 3 working days. This project follows a 90 day disclosure timeline.
37 changes: 20 additions & 17 deletions docs/content/1.getting-started/1.index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,10 @@ These are the docs for the new v0.6 version of `nuxt-auth` with static Nuxt 3 an
- documentation, recipes and example code to get you started
::

`nuxt-auth` employs 2 providers to facilitate the act of authenticating a user:
`nuxt-auth` employs 3 providers to facilitate the act of authenticating a user:
::list{type="success"}
- `local`: Username and password authentication. `local` expects the endpoint to return a token that can be used to authenticate subsequent requests
- `refresh`: A extended version of the `local` provider, made for systems that require a token refresh.
- `authjs`: A `authjs` (`next-auth`) based provider that supports most OAuth- and Magic-URL sign-ins (think Slack or Notion). This provider also supports username and password based sign-in, but discourages from using it
::

Expand All @@ -44,26 +45,28 @@ Here's the source-code https://github.com/sidebase/nuxt-auth-example of the exam

To pick a provider you will first have to take into consideration the requirements of your use-case. Below is a small table to help you pick:

| | authjs | local |
|----------------------------------------------------------- |-------------------------------------: |------: |
| **Authentication Methods** | | |
| OAuth | ✅ (>50 providers) | ❌ |
| Magic URLs | ✅ | ❌ |
| Credential / Username + Password flow | 🚧 (if possible: use `local` instead) | ✅ |
| | | |
| **Features** | | |
| app `useAuth`-composable to sign-in, sign-out, ... | ✅ | ✅ |
| session-management: auto-refresh, refresh on refocus, ... | ✅ | ✅ |
| static apps ("nuxi generate") | ❌ | ✅ |
| guest mode | ✅ | ✅ |
| app-side middleware | ✅ | ✅ |
| server-side middleware | ✅ | ✅ |
| pre-made login-page | ✅ (impacts bundle-size) | ❌ |
| database-adapters, server-side callback-hooks | ✅ | ❌ |
| | authjs | local | refresh
|----------------------------------------------------------- |-------------------------------------: |------: | ------:
| **Authentication Methods** | | |
| OAuth | ✅ (>50 providers) | ❌ | ❌
| Magic URLs | ✅ | ❌ | ❌
| Credentials / Username + Password flow | 🚧 (if possible: use `local` instead) | ✅ | ✅
| Refresh tokens | ✅ | ❌ | ✅
| | | |
| **Features** | | |
| app `useAuth`-composable to sign-in, sign-out, ... | ✅ | ✅ | ✅
| session-management: auto-refresh, refresh on refocus, ... | ✅ | ✅ | ✅
| static apps ("nuxi generate") | ❌ | ✅ | ✅
| guest mode | ✅ | ✅ | ✅
| app-side middleware | ✅ | ✅ | ✅
| server-side middleware | ✅ | ✅ | ✅
| pre-made login-page | ✅ (impacts bundle-size) | ❌ | ❌
| database-adapters, server-side callback-hooks | ✅ | ❌ | ❌

In general one can say that picking:
- `authjs` is best suited for plug-and-play OAuth for established oauth-providers or magic-url based sign-ins
- `local` is best when you already have a backend that accepts username + password as a login or want to build a static application
- `refresh` if you would need to extend the functionality of the `local` provider, with a refresh token

### `authjs` Remarks

Expand Down
18 changes: 11 additions & 7 deletions docs/content/1.getting-started/2.installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,27 +17,31 @@ pnpm i -D @sidebase/nuxt-auth
```
::

::alert{type="info"}
Note that we try our best to keep `nuxt-auth` stable, but it is also a fresh module that is in active development. If you want to be extra sure nothing breaks, you should pin the patch version, e.g., by using `--save-exact` when running the install command.
::

## Specifics: `authjs`-Provider

If you want to use the `authjs` provider, you have to install `next-auth`. With all package managers except `npm` you must manually install the peer dependency alongside `nuxt-auth`:
::code-group
```bash [yarn]
yarn add next-auth@4.21.1
yarn add next-auth@4.22.5
```
```bash [pnpm]
pnpm i next-auth@4.21.1
pnpm i next-auth@4.22.5
```
::

::alert{type="warning"}
Due to a breaking change in NextAuth, nuxt-auth is only compoatible with NextAuth versions under v4.23.0. We recommend pinning the version to `4.22.5`. See more [here](https://github.com/sidebase/nuxt-auth/issues/514).
::

::alert{type="info"}
Note that we try our best to keep `nuxt-auth` stable, but it is also a fresh module that is in active development. If you want to be extra sure nothing breaks, you should pin the patch version, e.g., by using `--save-exact` when running the install command.
::

You can find all available `next-auth` versions [on npm](https://www.npmjs.com/package/next-auth?activeTab=versions). You do not need to install any other peer-dependencies in order to use `nuxt-auth`.

If you are unsure which provider to choose, have a look at the [overview on the getting-started page](/nuxt-auth/v0.6/getting-started#which-provider-should-i-pick).

## Specifics: `local`-Provider
## Specifics: `local`/`refresh`-Provider

The `local` provider does not have any specific extra dependencies. However, you will need to make sure that you have a backend somewhere that provides username + password based authentication, [read more about this on the quick-start page](/nuxt-auth/v0.6/getting-started/quick-start).

Expand Down
64 changes: 63 additions & 1 deletion docs/content/1.getting-started/3.quick-start.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,16 @@ export default defineNuxtConfig({
}
})
```
```ts [refresh]
export default defineNuxtConfig({
modules: ['@sidebase/nuxt-auth'],
auth: {
provider: {
type: 'refresh'
}
}
})
```
::

Then continue with the provider-specific steps below.
Expand Down Expand Up @@ -91,20 +101,72 @@ and return a token that can be used to authenticate future requests in the respo
}
```

### Provider: `refresh`
::alert{type="info"}
The refresh provider is only available in version `0.6.3` and later
::

The refresh provider does not require any additional steps, as it relies on an already existing backend. By default, the `refresh` provider will try to reach this backend using the following default-configuration:
```ts
{
baseURL: '/api/auth',
endpoints: {
signIn: { path: '/login', method: 'post' },
signOut: { path: '/logout', method: 'post' },
signUp: { path: '/register', method: 'post' },
getSession: { path: '/session', method: 'get' }
refresh: { path: '/refresh', method: 'post' },
}
}
```

So when you call the `signIn` method, the endpoint `/api/auth/login` will be hit with the `username` and `password` you pass as a body-payload. You likely have to modify these parameters to fit to your backend - you can adjust these parameters in your `nuxt.config.ts` using the options [specified here](/nuxt-auth/v0.6/configuration/nuxt-config).

Note: The backend can also be in the same Nuxt 3 application, e.g., have a look at this example in the `nuxt-auth` repository:
- [full nuxt app](https://github.com/sidebase/nuxt-auth/tree/main/playground-refresh)
- its [backend](https://github.com/sidebase/nuxt-auth/tree/main/playground-refresh/server/api/auth)
- its [`nuxt.config.ts`](https://github.com/sidebase/nuxt-auth/blob/main/playground-refresh/nuxt.config.ts)

::alert{type="info"}
The linked example-implementation only serves as a starting-point and is not considered to be secure.
::

The backend must accept a request with a body like:
```ts
{
username: 'bernd@sidebase.io',
password: 'hunter2'
}
```

and return a token that can be used to authenticate future requests in the response body, e.g., like:
```ts
{
tokens: {
accessToken: 'eyBlaBlub'
refreshToken: 'eyBlaubwww'
}
}
```

So when you call the `refresh` method, the endpoint `/api/auth/refresh` will be hit with the `refreshToken` you pass as a body-payload. You likely have to modify these parameters to fit to your backend - you can adjust these parameters in your `nuxt.config.ts` using the options [specified here](/nuxt-auth/v0.6/configuration/nuxt-config).

## Finishing up

That's it! You can now use all user-related functionality, for example:

::code-group
```ts [Application side]
// file: e.g ~/pages/login.vue
const { status, data, signIn, signOut } = useAuth()
const { status, data, signIn, signOut, refresh } = useAuth()

status.value // Session status: `unauthenticated`, `loading`, `authenticated`
data.value // Session data, e.g., expiration, user.email, ...

await signIn() // Sign in the user
await refresh() // Refresh the token
await signOut() // Sign out the user

```
```ts [authjs: Server side]
// file: e.g: ~/server/api/session.get.ts
Expand Down
2 changes: 1 addition & 1 deletion docs/content/2.configuration/1.index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: "Overview of the configuration options of `nuxt-auth` for Vue / Nux
# Overview

Use the following places to configure how `nuxt-auth` behaves:
- `local` & `authjs`-provider: The [auth key in `nuxt.config.ts`](/nuxt-auth/v0.6/configuration/nuxt-config). Use it to configure the module itself, e.g., whether global page protection is enabled
- `local`/`refresh` & `authjs`-provider: The [auth key in `nuxt.config.ts`](/nuxt-auth/v0.6/configuration/nuxt-config). Use it to configure the module itself, e.g., whether global page protection is enabled
- `authjs`-provider: The [NuxtAuthHandler](/nuxt-auth/v0.6/configuration/nuxt-auth-handler). Use it to configure the `authjs` authentication behavior, e.g., what authentication providers to use.

See the detailed possible configuration options on the next pages.
Loading

0 comments on commit acc827d

Please sign in to comment.