Skip to content

Commit

Permalink
4.0.0-beta.10 (#1833)
Browse files Browse the repository at this point in the history
  • Loading branch information
@guabu
guabu authored Dec 10, 2024
1 parent 726a8ed commit fed3bf4
Show file tree
Hide file tree
Showing 16 changed files with 1,199 additions and 104 deletions.
60 changes: 46 additions & 14 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
### 1. Install the SDK

```shell
npm i @auth0/[email protected].9
npm i @auth0/[email protected].10
```

### 2. Add the environment variables
Expand Down Expand Up @@ -109,19 +109,21 @@ export default async function Home() {

You can customize the client by using the options below:

| Option | Type | Description |
| ----------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| domain | `string` | The Auth0 domain for the tenant (e.g.: `example.us.auth0.com`). If it's not specified, it will be loaded from the `AUTH0_DOMAIN` environment variable. |
| clientId | `string` | The Auth0 client ID. If it's not specified, it will be loaded from the `AUTH0_CLIENT_ID` environment variable. |
| clientSecret | `string` | The Auth0 client secret. If it's not specified, it will be loaded from the `AUTH0_CLIENT_SECRET` environment variable. |
| authorizationParameters | `AuthorizationParameters` | The authorization parameters to pass to the `/authorize` endpoint. See [Passing authorization parameters](#passing-authorization-parameters) for more details. |
| appBaseUrl | `string` | The URL of your application (e.g.: `http://localhost:3000`). If it's not specified, it will be loaded from the `APP_BASE_URL` environment variable. |
| secret | `string` | A 32-byte, hex-encoded secret used for encrypting cookies. If it's not specified, it will be loaded from the `AUTH0_SECRET` environment variable. |
| signInReturnToPath | `string` | The path to redirect the user to after successfully authenticating. Defaults to `/`. |
| session | `SessionConfiguration` | Configure the session timeouts and whether to use rolling sessions or not. See [Session configuration](#session-configuration) for additional details. |
| beforeSessionSaved | `BeforeSessionSavedHook` | A method to manipulate the session before persisting it. See [beforeSessionSaved](#beforesessionsaved) for additional details. |
| onCallback | `OnCallbackHook` | A method to handle errors or manage redirects after attempting to authenticate. See [onCallback](#oncallback) for additional details. |
| sessionStore | `SessionStore` | A custom session store implementation used to persist sessions to a data store. See [Database sessions](#database-sessions) for additional details. |
| Option | Type | Description |
| --------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| domain | `string` | The Auth0 domain for the tenant (e.g.: `example.us.auth0.com`). If it's not specified, it will be loaded from the `AUTH0_DOMAIN` environment variable. |
| clientId | `string` | The Auth0 client ID. If it's not specified, it will be loaded from the `AUTH0_CLIENT_ID` environment variable. |
| clientSecret | `string` | The Auth0 client secret. If it's not specified, it will be loaded from the `AUTH0_CLIENT_SECRET` environment variable. |
| authorizationParameters | `AuthorizationParameters` | The authorization parameters to pass to the `/authorize` endpoint. See [Passing authorization parameters](#passing-authorization-parameters) for more details. |
| appBaseUrl | `string` | The URL of your application (e.g.: `http://localhost:3000`). If it's not specified, it will be loaded from the `APP_BASE_URL` environment variable. |
| secret | `string` | A 32-byte, hex-encoded secret used for encrypting cookies. If it's not specified, it will be loaded from the `AUTH0_SECRET` environment variable. |
| signInReturnToPath | `string` | The path to redirect the user to after successfully authenticating. Defaults to `/`. |
| session | `SessionConfiguration` | Configure the session timeouts and whether to use rolling sessions or not. See [Session configuration](#session-configuration) for additional details. |
| beforeSessionSaved | `BeforeSessionSavedHook` | A method to manipulate the session before persisting it. See [beforeSessionSaved](#beforesessionsaved) for additional details. |
| onCallback | `OnCallbackHook` | A method to handle errors or manage redirects after attempting to authenticate. See [onCallback](#oncallback) for additional details. |
| sessionStore | `SessionStore` | A custom session store implementation used to persist sessions to a data store. See [Database sessions](#database-sessions) for additional details. |
| pushedAuthorizationRequests | `boolean` | Configure the SDK to use the Pushed Authorization Requests (PAR) protocol when communicating with the authorization server. |
| routes | `Routes` | Configure the paths for the authentication routes. See [Custom routes](#custom-routes) for additional details. |

## Passing authorization parameters

Expand Down Expand Up @@ -519,3 +521,33 @@ The SDK mounts 6 routes:
4. `/auth/profile`: the route to check the user's session and return their attributes
5. `/auth/access-token`: the route to check the user's session and return an access token (which will be automatically refreshed if a refresh token is available)
6. `/auth/backchannel-logout`: the route that will receive a `logout_token` when a configured Back-Channel Logout initiator occurs

### Custom routes

The default paths can be set using the `routes` configuration option. For example, when instantiating the client:

```ts
import { Auth0Client } from "@auth0/nextjs-auth0/server"

export const auth0 = new Auth0Client({
routes: {
login: "/login",
logout: "/logout",
callback: "/callback",
backChannelLogout: "/backchannel-logout",
},
})
```

To configure the profile and access token routes, you must use the `NEXT_PUBLIC_PROFILE_ROUTE` and `NEXT_PUBLIC_ACCESS_TOKEN_ROUTE`, respectively. For example:

```
# .env.local
# required environment variables...
NEXT_PUBLIC_PROFILE_ROUTE=/api/me
NEXT_PUBLIC_ACCESS_TOKEN_ROUTE=/api/auth/token
```

> [!IMPORTANT]
> Updating the route paths will also require updating the **Allowed Callback URLs** and **Allowed Logout URLs** configured in the [Auth0 Dashboard](https://manage.auth0.com) for your client.
241 changes: 241 additions & 0 deletions V4_MIGRATION_GUIDE.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,241 @@
# V4 Migration Guide

Guide to migrating from `3.x` to `4.x`.

## Environment variables

The following environment variables are required in v4:

```
AUTH0_DOMAIN
AUTH0_CLIENT_ID
AUTH0_CLIENT_SECRET
AUTH0_SECRET
APP_BASE_URL
```

Of the required variables, the following have changed from v3:

- `AUTH0_BASE_URL` has been renamed to `APP_BASE_URL` (e.g.: `http://localhost:3000`)
- `AUTH0_ISSUER_BASE_URL` has been renamed to `AUTH0_DOMAIN` and does **not** accept a scheme (e.g.: `example.us.auth0.com`)

All other configuration must be specified via the `Auth0Client` constructor.

## Routes

Previously, it was required to set up a dynamic Route Handler to mount the authentication endpoints to handle requests.

For example, in v3 when using the App Router, you were required to create a Route Handler, under `/app/api/auth/[auth0]/route.ts`, with the following contents:

```ts
import { handleAuth } from "@auth0/nextjs-auth0"

export const GET = handleAuth()
```

In v4, the routes are now mounted automatically by the middleware:

```ts
import type { NextRequest } from "next/server"

import { auth0 } from "./lib/auth0"

export async function middleware(request: NextRequest) {
return await auth0.middleware(request)
}
```

For a complete example, see [the Getting Started section](https://github.com/auth0/nextjs-auth0/tree/v4?tab=readme-ov-file#getting-started).

Additionally, in v4, the mounted routes drop the `/api` prefix. For example, the default login route is now `/auth/login` instead of `/api/auth/login`. To link to the login route, it would now be: `<a href="/auth/login">Log in</a>`.

> [!NOTE]
> If you are using an existing client, you will need to update your **Allowed Callback URLs** accordingly.
The complete list of routes mounted by the SDK can be found [here](https://github.com/auth0/nextjs-auth0/tree/v4?tab=readme-ov-file#routes).

## Auth0 middleware

In v4, the Auth0 middleware is a central component of the SDK. It serves a number of core functions such as registering the required authentication endpoints, providing rolling sessions functionality, keeping access tokens fresh, etc.

When configuring your application to use v4 of the SDK, it is now **required** to mount the middleware:

```ts
// middleware.ts

import type { NextRequest } from "next/server"

import { auth0 } from "./lib/auth0"

export async function middleware(request: NextRequest) {
return await auth0.middleware(request)
}

export const config = {
matcher: [
/*
* Match all request paths except for the ones starting with:
* - _next/static (static files)
* - _next/image (image optimization files)
* - favicon.ico, sitemap.xml, robots.txt (metadata files)
*/
"/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
],
}
```

See [the Getting Started section](https://github.com/auth0/nextjs-auth0/tree/v4?tab=readme-ov-file#getting-started) for details on how to configure the middleware.

### Protecting routes

By default, **the middleware does not protect any routes**. To protect a page, you can use the `getSession()` handler in the middleware, like so:

```ts
export async function middleware(request: NextRequest) {
const authRes = await auth0.middleware(request)

// authentication routes — let the middleware handle it
if (request.nextUrl.pathname.startsWith("/auth")) {
return authRes
}

const { origin } = new URL(request.url)
const session = await auth0.getSession()

// user does not have a session — redirect to login
if (!session) {
return NextResponse.redirect(`${origin}/auth/login`)
}

return authRes
}
```

> [!NOTE]
> We recommend keeping the security checks as close as possible to the data source you're accessing. This is also in-line with [the recommendations from the Next.js team](https://nextjs.org/docs/app/building-your-application/authentication#optimistic-checks-with-middleware-optional).
## `<UserProvider />`

The `<UserProvider />` has been renamed to `<Auth0Provider />`.

Previously, when setting up your application to use v3 of the SDK, it was required to wrap your layout in the `<UserProvider />`. **This is no longer required by default.**

If you would like to pass an initial user during server rendering to be available to the `useUser()` hook, you can wrap your components with the new `<Auth0Provider />` ([see example](https://github.com/auth0/nextjs-auth0/tree/v4?tab=readme-ov-file#auth0provider-)).

## Rolling sessions

In v4, rolling sessions are enabled by default and are handled automatically by the middleware with no additional configuration required.

See the [session configuration section](https://github.com/auth0/nextjs-auth0/tree/v4?tab=readme-ov-file#session-configuration) for additional details on how to configure it.

## `withPageAuthRequired` and `withApiAuthRequired`

`withPageAuthRequired` and `withApiAuthRequired` have been removed from v4 of the SDK. Instead, we recommend adding a `getSession()` check or relying on `useUser()` hook where you would have previously used the helpers.

On the server-side, the `getSession()` method can be used to check if the user is authenticated:

```tsx
function Page() {
const session = await getSession()

if (!session) {
// the user will be redirected to authenticate and then taken to the
// /dashboard route after successfully being authenticated
return redirect('/auth/login?returnTo=/dashboard')
}

return <h1>Hello, {session.user.name}</h1>
}
```

The `getSession()` method can be used in the App Router in Server Components, Server Routes (APIs), Server Actions, and middleware.

In the Pages Router, the `getSession(req)` method takes a request object and can be used in `getServerSideProps`, API routes, and middleware.

Read more about [accessing the authenticated user here](https://github.com/guabu/nextjs-auth0/tree/v4?tab=readme-ov-file#accessing-the-authenticated-user).

In the browser, you can rely on the `useUser()` hook to check if the user is authenticated. For example:

```tsx
"use client"

import { useUser } from "@auth0/nextjs-auth0"

export default function Profile() {
const { user, isLoading, error } = useUser()

if (isLoading) return <div>Loading...</div>
if (!user) return <div>Not authenticated!</div>

return (
<main>
<h1>Profile</h1>
<div>
<pre>{JSON.stringify(user, null, 2)}</pre>
</div>
</main>
)
}
```

## Passing custom authorization parameters

In v3, custom authorization parameters required specifying a custom handler, like so:

```ts
import { handleAuth, handleLogin } from "@auth0/nextjs-auth0"

export default handleAuth({
login: handleLogin({
authorizationParams: { audience: "urn:my-api" },
}),
})
```

In v4, you can simply append the authorization parameters to the query parameter of the login endpoint and they will be automatically fowarded to the `/authorize` endpoint, like so:

```html
<a href="/auth/login?audience=urn:my-api">Login</a>
```

Or alternatively, it can be statically configured when initializing the SDK, like so:

```ts
export const auth0 = new Auth0Client({
authorizationParameters: {
scope: "openid profile email",
audience: "urn:custom:api",
},
})
```

Read more about [passing authorization parameters](https://github.com/auth0/nextjs-auth0/tree/v4?tab=readme-ov-file#passing-authorization-parameters).

## ID token claims

In v3, any claims added to the ID token were automatically propagated to the `user` object in the session. This resulted in the large cookies that exceeded browser limits.

In v4, by default, the only claims that are persisted in the `user` object of session are:

- `sub`
- `name`
- `nickname`
- `given_name`
- `family_name`
- `picture`
- `email`
- `email_verified`
- `org_id`

If you'd like to customize the `user` object to include additional custom claims from the ID token, you can use the `beforeSessionSaved` hook (see [beforeSessionSaved hook](https://github.com/guabu/nextjs-auth0/tree/v4?tab=readme-ov-file#beforesessionsaved))

## Additional changes

- By default, v4 is edge-compatible and as such there is no longer a `@auth0/nextjs-auth0/edge` export.
- Cookie chunking has been removed
- If the cookie size exceeds the browser limit of 4096 bytes, a warning will be logged
- To store large session data, please use a [custom data store](https://github.com/auth0/nextjs-auth0/tree/v4?tab=readme-ov-file#database-sessions) with a SessionStore implementation
- All cookies set by the SDK default to `SameSite=Lax`
- `touchSession` method was removed. The middleware enables rolling sessions by default and can be configured via the [session configuration](https://github.com/auth0/nextjs-auth0/tree/v4?tab=readme-ov-file#session-configuration).
- `updateSession` method was removed.
- `getAccessToken` can now be called in React Server Components.
25 changes: 22 additions & 3 deletions package.json
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
{
"name": "@auth0/nextjs-auth0",
"version": "4.0.0-beta.9",
"version": "4.0.0-beta.10",
"description": "Auth0 Next.js SDK",
"main": "dist/index.js",
"scripts": {
"build": "tsc",
"build:watch": "tsc -w",
Expand Down Expand Up @@ -69,5 +68,25 @@
},
"publishConfig": {
"access": "public"
}
},
"typesVersions": {
"*": {
"types": [
"./dist/types/index.d.ts"
],
"server": [
"./dist/server/index.d.ts"
],
"errors": [
"./dist/errors/index.d.ts"
],
"*": [
"./dist/client/*",
"./dist/client/index.d.ts"
]
}
},
"files": [
"dist"
]
}
4 changes: 3 additions & 1 deletion src/client/helpers/get-access-token.ts
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
import { AccessTokenError } from "../../errors"

export async function getAccessToken() {
const tokenRes = await fetch("/auth/access-token")
const tokenRes = await fetch(
process.env.NEXT_PUBLIC_ACCESS_TOKEN_ROUTE || "/auth/access-token"
)

if (!tokenRes.ok) {
// try to parse it as JSON and throw the error from the API
Expand Down
2 changes: 1 addition & 1 deletion src/client/hooks/use-user.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import type { User } from "../../types"

export function useUser() {
const { data, error, isLoading } = useSWR<User, Error, string>(
"/auth/profile",
process.env.NEXT_PUBLIC_PROFILE_ROUTE || "/auth/profile",
(...args) =>
fetch(...args).then((res) => {
if (!res.ok) {
Expand Down
Loading

0 comments on commit fed3bf4

Please sign in to comment.