Skip to content

feat: add Next.js server-side auth and HTTP-only cookie content #8224

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Feb 12, 2025
Merged

feat: add Next.js server-side auth and HTTP-only cookie content #8224

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
e032de5
feat: add Next.js server-side auth and HTTP-only cookie content
HuiSF Jan 29, 2025
437d9b8
chore: add required callouts
HuiSF Jan 30, 2025
0e0a7de
chore: resolve comments
HuiSF Jan 30, 2025
3b53898
chore: resolve comments
HuiSF Feb 3, 2025
ccca1a4
chore: resolve comments
HuiSF Feb 3, 2025
6c39640
chore: resolve comments
HuiSF Feb 4, 2025
4db9f25
chore: resolve comments
HuiSF Feb 4, 2025
8445d87
chore: rearrange content sectioins
HuiSF Feb 10, 2025
f54ca4e
chore: resolve comments
HuiSF Feb 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
236 changes: 217 additions & 19 deletions src/pages/[platform]/build-a-backend/server-side-rendering/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,21 +38,32 @@ Before you begin:

## Install the Amplify Next.js adapter

<Callout warning>

**Note:** Amplify JS v6 supports Next.js with the version range: `>=13.5.0 <16.0.0`.
Ensure you have the correct version to integrate with Amplify.

</Callout>

To use Amplify APIs server-side, you need to install the Amplify Next.js adapter in addition to the Amplify libraries:

```bash title="Terminal" showLineNumbers={false}
npm add aws-amplify @aws-amplify/adapter-nextjs
```

## Configure Amplify APIs for server-side usage
## Configure Amplify in Next.js

<BlockSwitcher>

<Block name="Configure Amplify for server-side usage">

You will need to create a `runWithAmplifyServerContextRunner` function to use Amplify APIs on the server-side of your Next.js app.
You will need to create a `runWithAmplifyServerContext` function to use Amplify APIs on the server-side of your Next.js app.

You can create an `amplifyServerUtils.ts` file under a `utils` folder in your codebase. In this file, you will import the Amplify backend outputs from the `amplify_outputs.json` file that is generated by the Amplify CLI, and use the `createServerRunner` function to create the `runWithAmplifyServerContextRunner` function.
You can create an `amplifyServerUtils.ts` file under a `utils` folder in your codebase. In this file, you will import the Amplify backend outputs from the `amplify_outputs.json` file that is generated by the Amplify CLI, and use the `createServerRunner` function to create the `runWithAmplifyServerContext` function.

For example, the `utils/amplifyServerUtils.ts` file may contain the following content:

```typescript
```typescript title="src/utils/amplifyServerUtils.ts"
import { createServerRunner } from '@aws-amplify/adapter-nextjs';
import outputs from '@/amplify_outputs.json';

Expand All @@ -64,16 +75,21 @@ export const { runWithAmplifyServerContext } = createServerRunner({
You can use the exported `runWithAmplifyServerContext` function to call Amplify APIs within isolated request contexts. You can review examples under the [Calling Amplify category APIs on the server side](#calling-amplify-category-apis-on-the-server-side) section.

<Callout>
**TIP:** You only need to call the `createServerRunner` function once and reuse the `runWithAmplifyServerContext` function throughout.
**Tip:** You only need to call the `createServerRunner` function once and reuse the `runWithAmplifyServerContext` function throughout.
</Callout>

## Configure Amplify library for client-side usage
</Block>
<Block name="Configure Amplify for client-side usage">

<Callout>
**Tip**: You only need do this step if you are using Amplify APIs on the client side of your Next.js app, for example, calling Amplify Auth `signIn` API to sign in a user, or use GraphQL subscriptions on the client side.
</Callout>

When you use the Amplify library on the client-side of your Next.js app, you will need to configure Amplify by calling the `Amplify.configure` as you would to use Amplify in a single-page application.

<Callout>

**NOTE:** To use the Amplify library on the client side in a Next.js app, you will need to set `ssr` to `true` when calling `Amplify.configure`. This instructs the Amplify library to store tokens in the cookie store of a browser. Cookies will be sent along with requests to your Next.js server for authentication.
**Note:** To use the Amplify library on the client side in a Next.js app, you will need to set `ssr` to `true` when calling `Amplify.configure`. This instructs the Amplify library to store tokens in the cookie store of a browser. Cookies will be sent along with requests to your Next.js server for authentication.

</Callout>

Expand All @@ -96,6 +112,12 @@ export default function RootLayoutThatConfiguresAmplifyOnTheClient({
}
```

<Callout warning>

Make sure you call `Amplify.configure` as early as possible in your application’s life-cycle. A missing configuration or `NoCredentials` error is thrown if `Amplify.configure` has not been called before other Amplify JavaScript APIs. Review the [Library Not Configured Troubleshooting guide](/gen1/[platform]/build-a-backend/troubleshooting/library-not-configured/) for possible causes of this issue.

</Callout>

<Callout>

To avoid repetitive calls to `Amplify.configure`, you can call it once in a top-level client-side rendered layout component.
Expand All @@ -108,7 +130,7 @@ If you're using the Next.js App Router, you can create a client component to con

`ConfigureAmplifyClientSide.ts`:

```typescript
```tsx title="src/components/ConfigureAmplifyClientSide.tsx"
'use client';

import { Amplify } from 'aws-amplify';
Expand All @@ -123,7 +145,7 @@ export default function ConfigureAmplifyClientSide() {

`layout.tsx`:

```jsx
```tsx title="src/app/layout.tsx"
import ConfigureAmplifyClientSide from '@/components/ConfigureAmplifyClientSide';
import './globals.css';

Expand Down Expand Up @@ -154,15 +176,194 @@ export default function RootLayout({

</Accordion>

</Block>

</BlockSwitcher>



## Authentication with Next.js server-side runtime

You can use the Amplify Auth category APIs to sign up and sign in your end users on the client side. When you set `ssr: true` when calling `Amplify.configure`, the Amplify library uses cookies to store tokens which will be sent along with HTTP requests to your Next.js app server.
### (Experimental) Perform authentication on the server side and enable HttpOnly cookies

<Callout warning>

**Warning:** This feature is experimental and may change in future releases.

Once you enable the server-side sign-in feature, auth tokens are stored in HttpOnly cookies and you may not change the HttpOnly attribute. Since these cookies are inaccessible from client-side scripts, you won’t be able to use any Amplify JS APIs on the client side. Therefore, you don’t need to configure Amplify on the client side. You can keep using [these Amplify JS server-side APIs](/[platform]/build-a-backend/server-side-rendering/#supported-apis-for-nextjs-server-side-usage) on the server side.

</Callout>

Additional setup is required to enable server-side authentication flows in your Next.js app.

#### Step 1 - Specify the origin of your app in environment variables

Add the following environment variable to your Next.js app. For example in a `.env` file:

```shell title=".env" showLineNumbers={false}
AMPLIFY_APP_ORIGIN=https://myapp.com
```

Ensure this environment variable is accessible in your Next.js app's server runtime.

<Callout info>

**Note:** Token cookies are transmitted via server-side authentication flows. In production environments, it is recommended to use HTTPS as the origin for enhanced security.

</Callout>

#### Step 2 - Export the `createAuthRouteHandlers` function

The `createAuthRouteHandlers` function is created by the `createServerRunner` function call when you configure Amplify for server-side usage. You can export this function from your `amplifyServerUtils.ts` file. You can also configure cookie attributes with the `runtimeOptions` parameter.

```typescript title="src/utils/amplifyServerUtils.ts"
import { createServerRunner } from '@aws-amplify/adapter-nextjs';
import outputs from '@/amplify_outputs.json';

export const {
runWithAmplifyServerContext,
// highlight-start
createAuthRouteHandlers,
// highlight-end
} = createServerRunner({
config: outputs,
// highlight-start
runtimeOptions: {
cookies: {
domain: '.myapp.com', // making cookies available to all subdomains
sameSite: 'strict',
maxAge: 60 * 60 * 24 * 7 // 7 days
}
}
// highlight-end
});
```

#### Step 3 - Set up the Auth API routes

Create an API route using the `createAuthRouteHandlers` function. For example:

<BlockSwitcher>
<Block name="App router">
```typescript title="src/app/api/auth/[slug]/route.ts"
import { createAuthRouteHandlers } from "@/utils/amplifyServerUtils";

export const GET = createAuthRouteHandlers({
redirectOnSignInComplete: "/home",
redirectOnSignOutComplete: "/sign-in",
});
```
</Block>
<Block name="Pages router">
```typescript title="src/pages/api/auth/[slug].ts"
import { createAuthRouteHandlers } from "@/utils/amplifyServerUtils";

export default createAuthRouteHandlers({
redirectOnSignInComplete: "/home",
redirectOnSignOutComplete: "/sign-in",
});
```
</Block>
</BlockSwitcher>

With the above example, Amplify generates the following API routes:

| API Routes | What it does |
| --------------------------------------------------- | ------------------------------------------------------------ |
| `/api/auth/sign-up` | Upon navigating an end user to this route, they’ll be redirected to the Amazon Cognito Managed Login sign-up form. After sign-up and sign-in, they’ll be redirected back to the route `/api/auth/sign-in-callback`. |
| `/api/auth/sign-in` | Upon navigating an end user to this route, they’ll be redirected to the Amazon Cognito Managed Login sign-in form. After sign-in, they’ll be redirected back to the route `/api/auth/sign-in-callback`. |
| `/api/auth/sign-in?provider=<social-provider-name>` | Upon navigating an end user to this route, they’ll be redirected first to the Amazon Cognito Managed Login and then the specified social provider sign-in page. After sign-in, they’ll be redirected back to the route `/api/auth/sign-in-callback`. |
| `/api/auth/sign-out` | Upon navigating an end user to this route, the end user will be signed out and redirected to the route `/api/auth/sign-out-callback`. |
| `/api/auth/sign-in-callback` | Amazon Cognito Managed Login redirects an end user back to this route after signing in. Amplify exchanges auth tokens and stores them as HttpOnly cookies in the browser cookie store, then redirects the end user back to the route specified by the `redirectOnSignInComplete` parameter. |
| `/api/auth/sign-out-callback` | Amazon Cognito Managed Login redirects an end user back to this route after signing out, Amplify revokes access token and refresh token and removes token cookies from browser cookie store, then redirects the end user back to the route specified by the `redirectOnSignOutComplete` parameter. |

<Callout info>

**Note:** A signing-out call involves multiple steps, including signing out from Amazon Cognito Managed Login, revoking tokens, and removing cookies. If the user closes the browser during the process, the following may occur:

1. auth token have not been revoked - user remains signed in
2. auth token have been revoked but cookies have not been removed - cookies will be removed when the user visits the app again

</Callout>

#### Step 4 - Provide the redirect URLs to the Auth Resource in Amplify

You can provide the callback API routes as the redirect URLs in the Auth resource configuration. For example:

```ts title="amplify/auth/resource.ts"
export const auth = defineAuth({
loginWith: {
email: true,
// highlight-start
externalProviders: {
callbackUrls: ["https://myapp.com/api/auth/sign-in-callback"],
logoutUrls: ["https://myapp.com/api/auth/sign-out-callback"],
},
// highlight-end
},
});
```

This enables Amazon Cognito Hosted UI to support the server-side authentication flows. You may upgrade to the latest Amazon Cognito Managed Login Branding to customize the sign-in and sign-up pages. See [Amazon Cognito user pool managed login](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-managed-login.html) for more information.

#### Step 5 - Use Anchor link for initiating server-side authentication flows
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just minor nit: I think the example here could be just one page server side on page.tsx example. Rather than these button components.

Since i think these components are just given and not told where to use it. And new to next devs can put it on client side as well.

Copy link
Member Author

@HuiSF HuiSF Feb 11, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately using anchor link directly in page.tsx trigger Next eslint rules, and it recommends to use Link component provided by Next.js, which enforces to prefetch linked resource and causes unexpected errors. So we give button example to ensure it works out of box.


### Manage Auth session with the Next.js Middleware
Use HTML anchor links to navigate users to the sign-in and sign-up routes. For example:

<BlockSwitcher>
<Block name="Sign in button">
```tsx title="src/components/SignInButton.tsx"
export const SignInButton() {
return (
<a href="/api/auth/sign-in">
Sign In
</a>
);
}
```
</Block>
<Block name="Sign in with Google button">
```tsx title="src/components/SignInWithGoogleButton.tsx"
export const SignInWithGoogleButton() {
return (
<a href="/api/auth/sign-in?provider=Google">
Sign In with Google
</a>
);
}
```
</Block>
<Block name="Sign up button">
```tsx title="src/components/SignUpButton.tsx"
export const SignUpButton() {
return (
<a href="/api/auth/sign-up">
Sign Up
</a>
);
}
```
</Block>
<Block name="Sign out button">
```tsx title="src/components/SignOutButton.tsx"
export const SignOutButton() {
return (
<a href="/api/auth/sign-out">
Sign Out
</a>
);
}
```
</Block>
</BlockSwitcher>

When an end user clicks on the buttons above, a corresponding server-side authentication flow will be initiated.

### Validate user session with the Next.js Middleware

You can use the `fetchAuthSession` API to check the auth sessions that are attached to the incoming requests in the middleware of your Next.js app to protect your routes. For example:

```typescript
```typescript title="src/middleware.ts"
import { fetchAuthSession } from 'aws-amplify/auth/server';
import { NextRequest, NextResponse } from 'next/server';
import { runWithAmplifyServerContext } from '@/utils/amplifyServerUtils';
Expand Down Expand Up @@ -211,7 +412,7 @@ In this example, if the incoming request is not associated with a valid user ses

<Callout>

**NOTE:** When calling `fetchAuthSession` with a `response` context, it will send the refreshed tokens (if any) back to the client via the `Set-Cookie` header in the response.
**Note:** When calling `fetchAuthSession` with a `response` context, it will send the refreshed tokens (if any) back to the client via the `Set-Cookie` header in the response.

</Callout>

Expand All @@ -226,7 +427,7 @@ For the **GraphQL API** category, review [Connect to data from Server-side Runti

<Callout>

**NOTE:** A subset of Amplify APIs can now be called on the server side of a Next.js app. These APIs are exported from the `/server` sub paths. See [the full list](#supported-apis-for-nextjs-server-side-usage) of supported APIs.
**Note:** A subset of Amplify APIs can now be called on the server side of a Next.js app. These APIs are exported from the `/server` sub paths. See [the full list](#supported-apis-for-nextjs-server-side-usage) of supported APIs.

</Callout>

Expand Down Expand Up @@ -274,10 +475,7 @@ export default async function AuthGetCurrentUserServer() {
});

return (
<AuthFetchResult
description="The API is called on the server side."
data={currentUser}
/>
<p>{`Hello, ${currentUser.username}`}</p>
);
} catch (error) {
console.error(error);
Expand Down Expand Up @@ -325,7 +523,7 @@ export default async function StaticallyRenderedPage() {

<Callout>

**NOTE:** The URL returned by the `getUrl` API expires in the above example. You may want to specify the `revalidate` parameter to rerender the page as required to ensure the URL gets regenerated.
**Note:** The URL returned by the `getUrl` API expires in the above example. You may want to specify the `revalidate` parameter to rerender the page as required to ensure the URL gets regenerated.

</Callout>

Expand Down
Loading
Loading