Skip to content

Commit 83908a5

Browse files
aeneasraeneasr
authored
docs: add guide for NextAuth (#1730)
1 parent 1bd0138 commit 83908a5

File tree

3 files changed

+165
-3
lines changed

3 files changed

+165
-3
lines changed

‎docs/getting-started/integrate-auth/14_auth-js.mdx

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
id: auth-js
3+
title: Integrate authentication into Auth.js and NextAuth
4+
sidebar_label: Auth.js / NextAuth
5+
---
6+
7+
# Integrate authentication into Auth.js and NextAuth
8+
9+
This guide explains how to integrate Ory with [Auth.js](https://authjs.dev/), a flexible authentication library for Next.js
10+
applications. Auth.js supports multiple providers, including Ory Network.
11+
12+
Auth.js is the successor to NextAuth.js. The Ory provider works with both libraries.
13+
14+
Follow these steps to integrate Ory:
15+
16+
- Clone an example Next.js application
17+
- Create and configure an OAuth2 client in Ory
18+
- Configure Auth.js to use Ory
19+
- Test the authentication flow
20+
- Move the integration to production
21+
22+
```mdx-code-block
23+
import CodeFromRemote from "@theme/CodeFromRemote"
24+
import Tabs from "@theme/Tabs"
25+
import TabItem from "@theme/TabItem"
26+
```
27+
28+
## Clone and set up the example Next.js application
29+
30+
To set up the example application:
31+
32+
1. Open a terminal window.
33+
2. Run the following commands:
34+
35+
```shell-session
36+
git clone https://github.com/ory/next-auth-example.git
37+
cd next-auth-example
38+
npm install
39+
cp .env.local.example .env.local
40+
npx auth secret
41+
```
42+
43+
3. Open the `auth.ts` file.
44+
4. Check the `providers` array which uses Ory:
45+
46+
```mdx-code-block
47+
<CodeFromRemote lang="ts" src="https://github.com/ory/next-auth-example/blob/main/auth.ts" />
48+
```
49+
50+
## Create and configure an OAuth2 client in Ory Network
51+
52+
You must know your application's redirect URL. When running locally, the redirect URL is:
53+
54+
```
55+
http://localhost:3000/api/auth/callback/ory
56+
```
57+
58+
````mdx-code-block
59+
<Tabs>
60+
<TabItem value="console" label="Ory Console" default>
61+
62+
To create the client using the Ory Console:
63+
64+
1. Sign in to your Ory Network account.
65+
2. Create or select a project.
66+
3. Go to **OAuth 2**, select [**OAuth2 Clients**](https://console.ory.sh/projects/current/oauth), and select [**Create OAuth 2.0 Client**](https://console.ory.sh/projects/current/oauth/create).
67+
4. Select **Server App**.
68+
5. Enter a client name, for example, "NextAuth / Auth.js Example."
69+
6. Ensure the following scopes are selected:
70+
- `openid`
71+
- `offline_access`
72+
- `email`
73+
- `profile`
74+
7. Add the following to **Redirect URIs**:
75+
76+
```
77+
http://localhost:3000/api/auth/callback/ory
78+
```
79+
80+
8. Add the following to **Post Logout Redirect URIs**:
81+
82+
```
83+
http://localhost:3000/
84+
```
85+
86+
9. Select **Create Client**.
87+
10. Save the Client Secret as `ORY_CLIENT_SECRET` in your `.env.local` file.
88+
11. Save the Client ID as `ORY_CLIENT_ID` in your `.env.local` file.
89+
90+
</TabItem>
91+
92+
<TabItem value="cli" label="Ory CLI">
93+
94+
To create the client using the Ory CLI, run the following command:
95+
96+
```shell
97+
export ORY_PROJECT_ID= # Take this value from https://console.ory.sh/projects/current/get-started
98+
ory create oauth2-client --project $ORY_PROJECT_ID \
99+
--redirect-uri http://localhost:3000/api/auth/callback/ory \
100+
--name "NextAuth / Auth.js Example" \
101+
--scopes openid offline_access email profile \
102+
--skip-consent \
103+
--post-logout-callback http://localhost:3000/
104+
```
105+
106+
</TabItem>
107+
</Tabs>
108+
````
109+
110+
## Configure Auth.js to use Ory in the Next.js application
111+
112+
Update your `.env.local` file to match the example:
113+
114+
```mdx-code-block
115+
<CodeFromRemote lang="env" src="https://github.com/ory/next-auth-example/blob/main/env.local.example" />
116+
```
117+
118+
Also add your Ory SDK URL. You can find it in the [**Get started**](https://console.ory.sh/projects/current/get-started) section
119+
of the Ory Console.
120+
121+
## Test the authentication flow in your application
122+
123+
To run the application:
124+
125+
1. Open a terminal window.
126+
2. Run the following command:
127+
128+
```shell-session
129+
npm run dev
130+
```
131+
132+
3. Open your browser and go to `http://localhost:3000`.
133+
4. Select **Sign in** to start the authentication flow.
134+
135+
## Configure user sign-out with Ory
136+
137+
To sign out users, use the OpenID Connect logout flow:
138+
139+
```mdx-code-block
140+
<CodeFromRemote lang="js" src="https://github.com/ory/next-auth-example/blob/main/components/auth-components.tsx" showLink={true} startAt="export async function SignOut" />
141+
```
142+
143+
## Move the integration to production
144+
145+
Before deploying to production:
146+
147+
- Update the **Redirect URIs** and **Post Logout Redirect URIs** in your OAuth2 client settings to match your production domain.
148+
149+
## Troubleshoot common integration errors
150+
151+
### Resolve redirect URL mismatch errors
152+
153+
If you receive the following error:
154+
155+
```
156+
The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
157+
The 'redirect_uri' parameter does not match any of the OAuth 2.0 Client's pre-registered redirect URLs.
158+
```
159+
160+
Make sure that the redirect URL exactly matches the one registered in Ory. Use the browser’s network tab to inspect requests made
161+
to `/oauth2/auth`.

‎src/sidebar.ts

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -174,11 +174,12 @@ const quickstart: SidebarItemsConfig = [
174174
items: [
175175
"getting-started/integrate-auth/go",
176176
"getting-started/integrate-auth/php",
177-
"getting-started/integrate-auth/expressjs",
177+
"getting-started/integrate-auth/auth-js",
178+
"getting-started/integrate-auth/nextjs",
178179
"getting-started/integrate-auth/react",
179180
"getting-started/integrate-auth/react-native",
181+
"getting-started/integrate-auth/expressjs",
180182
"getting-started/integrate-auth/vue",
181-
"getting-started/integrate-auth/nextjs",
182183
"getting-started/integrate-auth/flutter-web-redirect",
183184
"getting-started/integrate-auth/dotnet",
184185
],

‎src/theme/CodeFromRemote.tsx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,7 @@ const CodeFromRemote = (props: {
123123
/>
124124
<div className={styles.link}>
125125
<a href={src + `#L${startLineNum}-L${endLineNum}`}>
126-
see full code on GitHub
126+
See full code on GitHub
127127
</a>
128128
</div>
129129
</div>

0 commit comments

Comments
 (0)