Skip to content

Commit 438f2d8

Browse files
committed
1 parent 2314296 commit 438f2d8

File tree

1 file changed

+18
-62
lines changed

1 file changed

+18
-62
lines changed

docs/authentication.md

Lines changed: 18 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,14 @@ Authentication verifies who a user is, while authorization controls what a user
88

99
## Authentication Patterns
1010

11-
The first step to identifying which authentication pattern you need is understanding the [data-fetching strategy](/docs/basic-features/data-fetching.md) you want. We can then determine which authentication providers support this strategy. There are two main patterns:
11+
The first step to identifying which authentication pattern you need is understanding the [data-fetching strategy](/docs/basic-features/data-fetching/overview.md) you want. We can then determine which authentication providers support this strategy. There are two main patterns:
1212

1313
- Use [static generation](/docs/basic-features/pages.md#static-generation-recommended) to server-render a loading state, followed by fetching user data client-side.
1414
- Fetch user data [server-side](/docs/basic-features/pages.md#server-side-rendering) to eliminate a flash of unauthenticated content.
1515

1616
### Authenticating Statically Generated Pages
1717

18-
Next.js automatically determines that a page is static if there are no blocking data requirements. This means the absence of [`getServerSideProps`](/docs/basic-features/data-fetching.md#getserversideprops-server-side-rendering) and `getInitialProps` in the page. Instead, your page can render a loading state from the server, followed by fetching the user client-side.
18+
Next.js automatically determines that a page is static if there are no blocking data requirements. This means the absence of [`getServerSideProps`](/docs/basic-features/data-fetching/get-server-side-props.md) and `getInitialProps` in the page. Instead, your page can render a loading state from the server, followed by fetching the user client-side.
1919

2020
One advantage of this pattern is it allows pages to be served from a global CDN and preloaded using [`next/link`](/docs/api-reference/next/link.md). In practice, this results in a faster TTI ([Time to Interactive](https://web.dev/interactive/)).
2121

@@ -48,11 +48,11 @@ const Profile = () => {
4848
export default Profile
4949
```
5050

51-
You can view this example in action [here](https://next-with-iron-session.vercel.app/). Check out the [`with-iron-session`](https://github.com/vercel/next.js/tree/canary/examples/with-iron-session) example to see how it works.
51+
You can view this [example in action](https://iron-session-example.vercel.app/). Check out the [`with-iron-session`](https://github.com/vercel/next.js/tree/canary/examples/with-iron-session) example to see how it works.
5252

5353
### Authenticating Server-Rendered Pages
5454

55-
If you export an `async` function called [`getServerSideProps`](/docs/basic-features/data-fetching.md#getserversideprops-server-side-rendering) from a page, Next.js will pre-render this page on each request using the data returned by `getServerSideProps`.
55+
If you export an `async` function called [`getServerSideProps`](/docs/basic-features/data-fetching/get-server-side-props.md) from a page, Next.js will pre-render this page on each request using the data returned by `getServerSideProps`.
5656

5757
```jsx
5858
export async function getServerSideProps(context) {
@@ -62,18 +62,16 @@ export async function getServerSideProps(context) {
6262
}
6363
```
6464

65-
Let's transform the profile example to use [server-side rendering](/docs/basic-features/pages#server-side-rendering). If there's a session, return `user` as a prop to the `Profile` component in the page. Notice there is not a loading skeleton in [this example](https://next-with-iron-session.vercel.app/).
65+
Let's transform the profile example to use [server-side rendering](/docs/basic-features/pages#server-side-rendering). If there's a session, return `user` as a prop to the `Profile` component in the page. Notice there is not a loading skeleton in [this example](https://iron-session-example.vercel.app/).
6666

6767
```jsx
6868
// pages/profile.js
6969

7070
import withSession from '../lib/session'
71-
import useUser from '../lib/useUser'
7271
import Layout from '../components/Layout'
7372

7473
export const getServerSideProps = withSession(async function ({ req, res }) {
75-
// Get the user's session based on the request
76-
const user = req.session.get('user')
74+
const { user } = req.session
7775

7876
if (!user) {
7977
return {
@@ -102,7 +100,7 @@ const Profile = ({ user }) => {
102100
export default Profile
103101
```
104102

105-
An advantage of this pattern is preventing a flash of unauthenticated content before redirecting. It's important to note fetching user data in `getServerSideProps` will block rendering until the request to your authentication provider resolves. To prevent creating a bottleneck and decreasing your TTFB ([Time to First Byte](https://web.dev/time-to-first-byte/)), you should ensure your authentication lookup is fast. Otherwise, consider [static generation](#authenticating-statically-generated-pages).
103+
An advantage of this pattern is preventing a flash of unauthenticated content before redirecting. It's important to note fetching user data in `getServerSideProps` will block rendering until the request to your authentication provider resolves. To prevent creating a bottleneck and increasing your TTFB ([Time to First Byte](https://web.dev/time-to-first-byte/)), you should ensure your authentication lookup is fast. Otherwise, consider [static generation](#authenticating-statically-generated-pages).
106104

107105
## Authentication Providers
108106

@@ -114,81 +112,39 @@ Now that we've discussed authentication patterns, let's look at specific provide
114112
<summary><b>Examples</b></summary>
115113
<ul>
116114
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-iron-session">with-iron-session</a></li>
117-
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-next-auth">with-next-auth</a></li>
115+
<li><a href="https://github.com/nextauthjs/next-auth-example">next-auth-example</a></li>
118116
</ul>
119117
</details>
120118

121119
If you have an existing database with user data, you'll likely want to utilize an open-source solution that's provider agnostic.
122120

123-
- If you need email/password log-in, use [`next-iron-session`](https://github.com/vercel/next.js/tree/canary/examples/with-iron-session).
124-
- If you need to persist session data on the server, use [`next-auth`](https://github.com/vercel/next.js/tree/canary/examples/with-next-auth).
125-
- If you need to support social login (Google, Facebook, etc.), use [`next-auth`](https://github.com/vercel/next.js/tree/canary/examples/with-next-auth).
126-
- If you want to use [JWTs](https://jwt.io/), use [`next-auth`](https://github.com/vercel/next.js/tree/canary/examples/with-next-auth).
121+
- If you want a low-level, encrypted, and stateless session utility use [`iron-session`](https://github.com/vercel/next.js/tree/canary/examples/with-iron-session).
122+
- If you want a full-featured authentication system with built-in providers (Google, Facebook, GitHub…), JWT, JWE, email/password, magic links and more… use [`next-auth`](https://github.com/nextauthjs/next-auth-example).
127123

128124
Both of these libraries support either authentication pattern. If you're interested in [Passport](http://www.passportjs.org/), we also have examples for it using secure and encrypted cookies:
129125

130126
- [with-passport](https://github.com/vercel/next.js/tree/canary/examples/with-passport)
131127
- [with-passport-and-next-connect](https://github.com/vercel/next.js/tree/canary/examples/with-passport-and-next-connect)
132128

133-
### Firebase
134-
135-
<details open>
136-
<summary><b>Examples</b></summary>
137-
<ul>
138-
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-firebase-authentication">with-firebase-authentication</a></li>
139-
</ul>
140-
</details>
141-
142-
When using Firebase Authentication, we recommend using the static generation pattern.
143-
144-
It is possible to use the Firebase Client SDK to generate an ID token and forward it directly to Firebase's REST API on the server to log-in. However, requests to Firebase might take some time to resolve, depending on your user's location.
129+
### Other Providers
145130

146-
You can either use [FirebaseUI](https://github.com/firebase/firebaseui-web-react) for a drop-in UI, or create your own with a [custom React hook](https://usehooks.com/useAuth/).
147-
148-
### Magic (Passwordless)
131+
To see examples with other authentication providers, check out the [examples folder](https://github.com/vercel/next.js/tree/canary/examples).
149132

150133
<details open>
151134
<summary><b>Examples</b></summary>
152135
<ul>
136+
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-firebase-authentication">with-firebase-authentication</a></li>
137+
<li><a href="https://github.com/vercel/examples/tree/main/solutions/auth-with-ory">auth-with-ory</a></li>
153138
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-magic">with-magic</a></li>
154-
</ul>
155-
</details>
156-
157-
[Magic](https://magic.link/), which uses [passwordless login](https://magic.link/), supports the static generation pattern. Similar to Firebase, a [unique identifier](https://w3c-ccg.github.io/did-primer/) has to be created on the client-side and then forwarded as a header to log-in. Then, Magic's Node SDK can be used to exchange the indentifier for a user's information.
158-
159-
### Auth0
160-
161-
<details open>
162-
<summary><b>Examples</b></summary>
163-
<ul>
164139
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/auth0">auth0</a></li>
165-
</ul>
166-
</details>
167-
168-
[Auth0](https://auth0.com/) can support both authentication patterns. You can also utilize [API routes](/docs/api-routes/introduction.md) for logging in/out and retrieving user information. After logging in using the [Auth0 SDK](https://github.com/auth0/nextjs-auth0), you can utilize static generation or `getServerSideProps` for server-side rendering.
169-
170-
### Supabase
171-
172-
<details open>
173-
<summary><b>Examples</b></summary>
174-
<ul>
175140
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-supabase-auth-realtime-db">with-supabase-auth-realtime-db</a></li>
176-
</ul>
177-
</details>
178-
179-
[Supabase](https://supabase.io/) is an open source Firebase alternative that supports many of its features, including authentication. It allows for row level security using JWT tokens and supports third party logins. Either authentication pattern is supported.
180-
181-
### Userbase
182-
183-
<details open>
184-
<summary><b>Examples</b></summary>
185-
<ul>
186141
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-userbase">with-userbase</a></li>
142+
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-supertokens">with-supertokens</a></li>
143+
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-nhost-auth-realtime-graphql">with-nhost-auth-realtime-graphql</a></li>
144+
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-clerk">with-clerk</a></li>
187145
</ul>
188146
</details>
189147

190-
[Userbase](https://userbase.com/) supports the static generation pattern for authentication. It's open source and allows for a high level of security with end-to-end encryption. You can learn more about it in their [official site](https://userbase.com/).
191-
192148
## Related
193149

194150
For more information on what to do next, we recommend the following sections:
@@ -201,7 +157,7 @@ For more information on what to do next, we recommend the following sections:
201157
</div>
202158

203159
<div class="card">
204-
<a href="/docs/basic-features/data-fetching.md">
160+
<a href="/docs/basic-features/data-fetching/overview.md">
205161
<b>Data Fetching:</b>
206162
<small>Learn more about data fetching in Next.js.</small>
207163
</a>

0 commit comments

Comments
 (0)