Update nextjs non-interactive quickstart

articles/quickstart/webapp/nextjs/01-login.md

@@ -14,7 +14,7 @@ useCase: quickstart
 ---
 <!-- markdownlint-disable MD002 MD034 MD041 -->
 
-<%= include('../_includes/_getting_started', { library: 'Next.js', callback: 'http://localhost:3000/api/auth/callback' }) %>
+<%= include('../_includes/_getting_started', { library: 'Next.js', callback: 'http://localhost:3000/auth/callback' }) %>
 
 <%= include('../../../_includes/_logout_url', { returnTo: 'http://localhost:3000' }) %>
 
@@ -23,98 +23,142 @@ useCase: quickstart
 Run the following command within your project directory to install the Auth0 Next.js SDK:
 
 ```sh
-npm install @auth0/nextjs-auth0@3
+npm install @auth0/nextjs-auth0
 ```
 
 The SDK exposes methods and variables that help you integrate Auth0 with your Next.js application using <a href="https://nextjs.org/docs/app/building-your-application/routing/route-handlers" target="_blank" rel="noreferrer">Route Handlers</a> on the backend and <a href="https://react.dev/reference/react/useContext" target="_blank" rel="noreferrer">React Context</a> with <a href="https://react.dev/reference/react/hooks" target="_blank" rel="noreferrer">React Hooks</a> on the frontend.
 
 ### Configure the SDK
 
-In the root directory of your project, add the file `.env.local` with the following <a href="https://nextjs.org/docs/basic-features/environment-variables" target="_blank" rel="noreferrer">environment variables</a>:
+In the root directory of your project, create the file `.env.local` with the following <a href="https://nextjs.org/docs/basic-features/environment-variables" target="_blank" rel="noreferrer">environment variables</a>:
 
 ```sh
 AUTH0_SECRET='use [openssl rand -hex 32] to generate a 32 bytes value'
-AUTH0_BASE_URL='http://localhost:3000'
-AUTH0_ISSUER_BASE_URL='https://${account.namespace}'
+APP_BASE_URL='http://localhost:3000'
+AUTH0_DOMAIN='https://${account.namespace}'
 AUTH0_CLIENT_ID='${account.clientId}'
 AUTH0_CLIENT_SECRET='${account.clientSecret}'
+'If your application is API authorized add the variables AUTH0_AUDIENCE and AUTH0_SCOPE'
+AUTH0_AUDIENCE='your_auth_api_identifier'
+AUTH0_SCOPE='openid profile email read:shows' 
 ```
 
 - `AUTH0_SECRET`: A long secret value used to encrypt the session cookie. You can generate a suitable string using `openssl rand -hex 32` on the command line.
-- `AUTH0_BASE_URL`: The base URL of your application.
-- `AUTH0_ISSUER_BASE_URL`: The URL of your Auth0 tenant domain. If you are using a <a href="https://auth0.com/docs/custom-domains" target="_blank" rel="noreferrer">Custom Domain with Auth0</a>, set this to the value of your Custom Domain instead of the value reflected in the "Settings" tab.
-- `AUTH0_CLIENT_ID`: Your Auth0 application's Client ID.
-- `AUTH0_CLIENT_SECRET`: Your Auth0 application's Client Secret.
+- `APP_BASE_URL`: The base URL of your application
+- `AUTH0_DOMAIN`: The URL of your Auth0 tenant domain
+- `AUTH0_CLIENT_ID`: Your Auth0 application's Client ID
+- `AUTH0_CLIENT_SECRET`: Your Auth0 application's Client Secret
 
-The SDK will read these values from the Node.js process environment and automatically configure itself.
+The SDK will read these values from the Node.js process environment and configure itself automatically.
 
-### Add the dynamic API route handler
+::: note
+Manually add the values for `AUTH0_AUDIENCE` and `AUTH_SCOPE` to the file `lib/auth0.js`.  These values are not configured automatically.
+If you are using a <a href="https://auth0.com/docs/custom-domains" target="_blank" rel="noreferrer">Custom Domain with Auth0</a>, set `AUTH0_DOMAIN` to the value of your Custom Domain instead of the value reflected in the application "Settings" tab.
+:::
 
-Create a file at `app/api/auth/[auth0]/route.js`. This is your Route Handler file with a <a href="https://nextjs.org/docs/app/building-your-application/routing/route-handlers#dynamic-route-segments" target="_blank" rel="noreferrer">Dynamic Route Segment</a>.
+### Create the Auth0 SDK Client
 
-Then, import the `handleAuth` method from the SDK and call it from the `GET` export.
+Create a file at `lib/auth0.js` to add an instance of the Auth0 client. This instance provides methods for handling authentication, sesssions and user data. 
 
 ```javascript
-// app/api/auth/[auth0]/route.js
-import { handleAuth } from '@auth0/nextjs-auth0';
-
-export const GET = handleAuth();
+// lib/auth0.js
+
+import { Auth0Client } from "@auth0/nextjs-auth0/server";
+
+// Initialize the Auth0 client 
+export const auth0 = new Auth0Client({
+  // Options are loaded from environment variables by default
+  // Ensure necessary environment variables are properly set
+  // domain: process.env.AUTH0_DOMAIN,
+  // clientId: process.env.AUTH0_CLIENT_ID,
+  // clientSecret: process.env.AUTH0_CLIENT_SECRET,
+  // appBaseUrl: process.env.APP_BASE_URL,
+  // secret: process.env.AUTH0_SECRET,
+
+  authorizationParameters: {
+    // In v4, the AUTH0_SCOPE and AUTH0_AUDIENCE environment variables for API authorized applications are no longer automatically picked up by the SDK.
+    // Instead, we need to provide the values explicitly.
+    scope: process.env.AUTH0_SCOPE,
+    audience: process.env.AUTH0_AUDIENCE,
+  }
+});
 ```
 
-This creates the following routes:
-
-- `/api/auth/login`: The route used to perform login with Auth0.
-- `/api/auth/logout`: The route used to log the user out.
-- `/api/auth/callback`: The route Auth0 will redirect the user to after a successful login.
-- `/api/auth/me`: The route to fetch the user profile from.
 
-::: note
-This QuickStart targets the Next.js <a href="https://nextjs.org/docs/app" target="_blank" rel="noreferrer">App Router</a>. If you're using the <a href="https://nextjs.org/docs/pages" target="_blank" rel="noreferrer">Pages Router</a>, check out the example in the SDK's <a href="https://github.com/auth0/nextjs-auth0#page-router" target="_blank" rel="noreferrer">README</a>.
-:::
-
-### Add the `UserProvider` component
+### Add the dynamic API route handler
 
-On the frontend side, the SDK uses React Context to manage the authentication state of your users. To make that state available to all your pages, you need to override the <a href="https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required" target="_blank" rel="noreferrer">Root Layout component</a> and wrap the `<body>` tag with a `UserProvider` in the file `app/layout.jsx`. 
+Create a file at `app/api/shows/route.js`. This is your route Handler file using <a href="https://nextjs.org/docs/app/building-your-application/routing/route-handlers#dynamic-route-segments" target="_blank" rel="noreferrer">Dynamic Route Segment</a>. The file declares a `GET` export to call the `shows()` method from the SDK to create the API routes. import the `handleAuth` method from the SDK and call it from the `GET` export.
 
-Create the file `app/layout.jsx` as follows:
+```javascript
+// app/api/shows/route.js
+import { NextResponse } from 'next/server';
+import { auth0 } from '../../../lib/auth0';
+
+export const GET = async function shows() {
+  try {
+    const session = await auth0.getSession();
+
+    if (!session) {
+      return NextResponse.json(
+        { error: 'Not authenticated' },
+        { status: 401 }
+      );
+    }
+
+    const res = new NextResponse();
+    const { token: accessToken } = await auth0.getAccessToken();
+    const apiPort = process.env.API_PORT || 3001;
+    const response = await fetch(`http://localhost:${apiPort}/api/shows`, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`
+      }
+    });
+    const shows = await response.json();
+
+    return NextResponse.json(shows, res);
+  } catch (error) {
+    return NextResponse.json({ error: error.message }, { status: error.status || 500 });
+  }
+};
+```
 
-```jsx
-// app/layout.jsx
-import { UserProvider } from '@auth0/nextjs-auth0/client';
+Upon execution, the following routes are available:
 
-export default function RootLayout({ children }) {
-  return (
-    <html lang="en">
-    <UserProvider>
-      <body>{children}</body>
-    </UserProvider>
-    </html>
-  );
-}
-```
+- `/auth/login`: The route to perform login with Auth0
+- `/auth/logout`: The route to log the user out
+- `/auth/callback`: The route Auth0 will redirect the user to after a successful login
+- `/auth/profile`: The route to fetch the user profile
+- `/auth/access-token`: The route to verify the user's session and return an <a href="https://auth0.com/docs/secure/tokens/access-tokens" target="_blank" rel="noreferrer">access token</a> (which automatically refreshes if a refresh token is available)
+- `/auth/backchannel-logout`: The route to receive a `logout_token` when a configured Back-Channel Logout initiator occurs
 
-The authentication state exposed by `UserProvider` can be accessed in any Client Component using the `useUser()` hook.
+To learn more about routing in Auth0, read <a href="https://auth0.com/blog/auth0-stable-support-for-nextjs-app-router/" target="_blank" rel="noreferrer"> Add the dynamic API route</a>.
 
-:::panel Checkpoint
-Now that you have added the dynamic route and `UserProvider`, run your application to verify that your application is not throwing any errors related to Auth0.
-:::
+:::note
+The `/auth/access-token` route is enabled by default. If your clients do not need access tokens, you can disable the route by editing the file `lib/auth0.js` and adding `enableAccessTokenEndpoint = false` to the instance of the Auth0 client. :::
 
 ## Add Login to Your Application
 
-Users can now log in to your application by visiting the `/api/auth/login` route provided by the SDK. Add a link that points to the login route using an **anchor tag**. Clicking it redirects your users to the Auth0 Universal Login Page, where Auth0 can authenticate them. Upon successful authentication, Auth0 will redirect your users back to your application.
-
-:::note
-Next linting rules might suggest using the `Link` component instead of an anchor tag. The `Link` component is meant to perform <a href="https://nextjs.org/docs/api-reference/next/link" target="_blank" rel="noreferrer">client-side transitions between pages</a>. As the link points to an API route and not to a page, you should keep it as an anchor tag.
-:::
+Users can now log in to your application at `/auth/login` route provided by the SDK. Use an **anchor tag** to add a link to the login route to redirect your users to the Auth0 Universal Login Page, where Auth0 can authenticate them. Upon successful authentication, Auth0 redirects your users back to your application.
 
 ```html
-<a href="/api/auth/login">Login</a>
+<a href="/auth/login">Login</a>
 ```
 
+:::note
+Next.js suggests using <a href="https://nextjs.org/docs/api-reference/next/link" target="_blank" rel="noreferrer">Link</a> components instead of anchor tags, but since these are API routes and not pages, anchor tags are needed.
+:::
+
 :::panel Checkpoint
-Add the login link to your application. When you click it, verify that your Next.js application redirects you to the <a href="https://auth0.com/universal-login" target="_blank" rel="noreferrer">Auth0 Universal Login</a> page and that you can now log in or sign up using a username and password or a social provider.
+Add the login link to your application. Select it and verify that your Next.js application redirects you to the <a href="https://auth0.com/universal-login" target="_blank" rel="noreferrer">Auth0 Universal Login</a> page and that you can now log in or sign up using a username and password or a social provider.
 
 Once that's complete, verify that Auth0 redirects back to your application.
+
+If you are following along with the sample app project from the top of this page, run the command:
+
+```sh
+npm i && npm run dev 
+```
+and visit http://localhost:3000 in your browser.
 :::
 
 ![Auth0 Universal Login](/media/quickstarts/universal-login.png)
@@ -123,14 +167,14 @@ Once that's complete, verify that Auth0 redirects back to your application.
 
 ## Add Logout to Your Application
 
-Now that you can log in to your Next.js application, you need <a href="https://auth0.com/docs/logout/log-users-out-of-auth0" target="_blank" rel="noreferrer">a way to log out</a>. Add a link that points to the `/api/auth/logout` API route. Clicking it redirects your users to your <a href="https://auth0.com/docs/api/authentication?javascript#logout" target="_blank" rel="noreferrer">Auth0 logout endpoint</a> (`https://YOUR_DOMAIN/v2/logout`) and then immediately redirects them back to your application.
+Now that you can log in to your Next.js application, you need <a href="https://auth0.com/docs/logout/log-users-out-of-auth0" target="_blank" rel="noreferrer">a way to log out</a>. Add a link that points to the `/auth/logout` API route. To learn more, read <a href="https://auth0.com/docs/authenticate/login/logout/log-users-out-of-auth0" target="_blank" rel="noreferrer">Log Users out of Auth0 with OIDC Endpoint</a>.
 
 ```html
-<a href="/api/auth/logout">Logout</a>
+<a href="/auth/logout">Logout</a>
 ```
 
 :::panel Checkpoint
-Add the logout link to your application. When you click it, verify that your Next.js application redirects you to the address you specified as one of the "Allowed Logout URLs" in the "Settings".
+Add the logout link to your application. When you select it, verify that your Next.js application redirects you to the address you specified as one of the "Allowed Logout URLs" in the application "Settings".
 :::
 
 ## Show User Profile Information
@@ -143,25 +187,45 @@ The profile information is available through the `user` property exposed by the
 
 ```jsx
 'use client';
-
-import { useUser } from '@auth0/nextjs-auth0/client';
-
-export default function ProfileClient() {
-  const { user, error, isLoading } = useUser();
-
-  if (isLoading) return <div>Loading...</div>;
-  if (error) return <div>{error.message}</div>;
-
+import React from 'react';
+import { Row, Col } from 'reactstrap';
+import { useUser } from '@auth0/nextjs-auth0';
+import Loading from '../../components/Loading';
+import Highlight from '../../components/Highlight';
+
+export default function Profile() {
+  const { user, isLoading } = useUser();
   return (
-    user && (
-      <div>
-        <img src={user.picture} alt={user.name} />
-        <h2>{user.name}</h2>
-        <p>{user.email}</p>
-      </div>
-    )
+    <>
+      {isLoading && <Loading />}
+      {user && (
+        <>
+          <Row className="align-items-center profile-header mb-5 text-center text-md-left" data-testid="profile">
+            <Col md={2}>
+              <img
+                src={user.picture}
+                alt="Profile"
+                className="rounded-circle img-fluid profile-picture mb-3 mb-md-0"
+                decode="async"
+                data-testid="profile-picture"
+              />
+            </Col>
+            <Col md>
+              <h2 data-testid="profile-name">{user.name}</h2>
+              <p className="lead text-muted" data-testid="profile-email">
+                {user.email}
+              </p>
+            </Col>
+          </Row>
+          <Row data-testid="profile-json">
+            <Highlight>{JSON.stringify(user, null, 2)}</Highlight>
+          </Row>
+        </>
+      )}
+    </>
   );
 }
+
 ```
 
 The `user` property contains sensitive information and artifacts related to the user's identity. As such, its availability depends on the user's authentication status. To prevent any render errors:
@@ -175,21 +239,13 @@ The `user` property contains sensitive information and artifacts related to the
 The profile information is available through the `user` property exposed by the `getSession` function. Take this <a href="https://nextjs.org/docs/getting-started/react-essentials#server-components" target="_blank" rel="noreferrer">Server Component</a> as an example of how to use it:
 
 ```jsx
-import { getSession } from '@auth0/nextjs-auth0';
+import { auth0 } from "@/lib/auth0";
 
 export default async function ProfileServer() {
-  const { user } = await getSession();
-
-  return (
-      user && (
-          <div>
-            <img src={user.picture} alt={user.name} />
-            <h2>{user.name}</h2>
-            <p>{user.email}</p>
-          </div>
-      )
-  );
+  const { user } = await auth0.getSession(); 
+  return ( user && ( <div> <img src={user.picture} alt={user.name}/> <h2>{user.name}</h2> <p>{user.email}</p> </div> )  ); 
 }
+
 ```
 
 :::panel Checkpoint
@@ -198,9 +254,4 @@ Verify that you can display the `user.name` or <a href="https://auth0.com/docs/u
 
 ## What's next?
 
-We put together a few examples of how to use <a href="https://github.com/auth0/nextjs-auth0" target="_blank" rel="noreferrer">nextjs-auth0</a> in more advanced use cases:
-
-- <a href="https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#protecting-a-server-side-rendered-ssr-page" target="_blank" rel="noreferrer">Protecting a Server Side Rendered (SSR) Page</a>
-- <a href="https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#protecting-a-client-side-rendered-csr-page" target="_blank" rel="noreferrer">Protecting a Client Side Rendered (CSR) Page</a>
-- <a href="https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#protect-an-api-route" target="_blank" rel="noreferrer">Protect an API Route</a>
-- <a href="https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#access-an-external-api-from-an-api-route" target="_blank" rel="noreferrer">Access an External API from an API Route</a>
+We put together a few <a href="https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md" target="_blank" rel="noreferrer">examples</a> on how to use <a href="https://github.com/auth0/nextjs-auth0" target="_blank" rel="noreferrer">nextjs-auth0</a> for more advanced use cases.

articles/quickstart/webapp/nextjs/download.md

@@ -4,7 +4,7 @@ To run the sample follow these steps:
 
 1) Set the **Allowed Callback URLs** in the <a href="${manage_url}/#/applications/${account.clientId}/settings" target="_blank" rel="noreferrer">Application Settings</a> to
 ```text
-http://localhost:3000/api/auth/callback
+http://localhost:3000/auth/callback
 ```
 
 2) Set **Allowed Logout URLs** in the <a href="${manage_url}/#/applications/${account.clientId}/settings" target="_blank" rel="noreferrer">Application Settings</a> to

articles/quickstart/webapp/nextjs/index.yml

@@ -23,7 +23,7 @@ seo_alias: nextjs
 show_releases: true
 show_steps: true
 requirements:
-  - Next.js 13.4+
+  - Next.js 15.2.4+
 default_article: 01-login
 articles:
   - 01-login