From b22c038173bf214a25bcdc4396d305caf7b243df Mon Sep 17 00:00:00 2001 From: Sagara Gunathunga Date: Wed, 27 Nov 2024 16:46:15 +1300 Subject: [PATCH 1/9] Adding Next.JS QSG for Asgardeo and IS --- en/asgardeo/docs/quick-starts/nextjs.md | 312 +++++++++++++++++ .../7.0.0/docs/quick-starts/nextjs.md | 320 ++++++++++++++++++ 2 files changed, 632 insertions(+) create mode 100644 en/asgardeo/docs/quick-starts/nextjs.md create mode 100644 en/identity-server/7.0.0/docs/quick-starts/nextjs.md diff --git a/en/asgardeo/docs/quick-starts/nextjs.md b/en/asgardeo/docs/quick-starts/nextjs.md new file mode 100644 index 0000000000..334305c4ba --- /dev/null +++ b/en/asgardeo/docs/quick-starts/nextjs.md @@ -0,0 +1,312 @@ +--- +template: templates/quick-start.html +heading: Next.JS Quickstart +description: Welcome to the Next.js Quickstart guide! In this document, you will learn to build a Next.js app, add user login and display user profile information using Asgardeo. +what_you_will_learn: + - Create new Next.js app + - Install Asgardeo provider for Auth.js + - Add user login and logout + - Display user profile information +prerequisites: + - About 15 minutes + - Asgardeo account + - Install a JS package manager + - A favorite text editor or IDE +# source_code: Next.js App Sample +whats_next: + # - Try out {{ product_name }} complete React guide + # - Try out {{product_name}} user onboarding complete guide for React + # - Read security best practices for React app guide +--- +## Configure an Application in {{ product_name }} + +- Sign into {{ product_name }} console and navigate to **Applications > New Application.** +- Select **Traditional Web Application** and complete the wizard popup by providing a suitable name and an authorized redirect URL.(*Ensure that the protocol remains set to OpenID Connect (OIDC).)* + +*Example:* + +- *Name - asgardeo-nextjs* +- *Authorized redirect URL - http://localhost:3000/api/auth/callback/asgardeo* + + + +!!! Info + + The authorized redirect URL determines where {{product_name}} should send users after they successfully log in. Typically, this will be the web address where your app is hosted. For this guide, we'll use ` http://localhost:3000/api/auth/callback/asgardeo`, as the authorized redirect URL . + +!!! note + + Make a note of the following values from the **Protocol** and **Info** tabs of the registered application. You will need them during the **Step 4** + + - **`client-id`** from the **Protocol** tab. + - **`client-secret`** from the **Protocol** tab. + - **`issuer`** from from the **Info** tab. + +## Create a Next.js app + +Create your new Next.js app. + +=== "npm" + + ``` bash + npx create-next-app@latest --typescript asgardeo-nextjs + + cd asgardeo-nextjs + + npm install + + npm run dev + ``` + +=== "yarn" + + ``` bash + yarn create next-app --typescript asgardeo-nextjs + + cd asgardeo-nextjs + + yran install + + yarn dev + ``` + +=== "pnpm" + + ``` bash + pnpm create next-app --typescript asgardeo-nextjs + + cd asgardeo-nextjs + + pnpm install + + pnpm run dev + ``` + +## Install Auth.js library + +Auth.js is a lightweight JavaScript library designed for simplifying authentication workflows in web application. The [Asgardeo provider for Auth.js](https://authjs.dev/reference/core/providers/asgardeo){:target="_blank"} offers all the components and hooks you need to integrate your app with {{product_name}}.To get started, simply add Auth.js library to the project. Make sure to stop the dev server started in the previous step. + +=== "npm" + + ``` bash + npm install next-auth@beta + ``` + +=== "yarn" + + ``` bash + yarn add next-auth@beta + ``` + +=== "pnpm" + + ``` bash + pnpm add next-auth@beta + ``` + +Next, generate **`AUTH_SECRET`** environment variable. + +=== "npm" + + ``` bash + npx auth secret + + ``` +=== "yarn" + + ``` bash + yarn dlx auth secret + ``` + +=== "pnpm" + + ``` bash + pnpm dlx auth secret + ``` + +Add following entries to the .env or .env.local file, and make sure to replace the placeholders in the following code with the **`client-id`**, **`client-secret`** and **`issuer`** values you copied in **Step-1** during the application registration in the {{product_name}} console. + + +```bash title=".env.local" + AUTH_ASGARDEO_ID="" + AUTH_ASGARDEO_SECRET="" + AUTH_ASGARDEO_ISSUER="" + +``` + + + +## Create the `auth.js` configuration File + +Create a file called `/src/auth.ts'`. + +```bash + +touch /src/auth.ts + +``` + +Add {{product_name}} as a provider in the `/src/auth.ts'` file. + +```javascript title="auth.ts" +import NextAuth from "next-auth" +import Asgardeo from "next-auth/providers/asgardeo" + +export const { handlers, signIn, signOut, auth } = NextAuth({ + providers: [Asgardeo({ + issuer: process.env.AUTH_ASGARDEO_ISSUER + })], +}) + +``` + + + +Create a Route Handler file in the `src/app/api/auth/[...nextauth]/route.ts` location. + +```bash +mkdir -p src/app/api/auth/\[...nextauth\] + +touch mkdir -p src/app/api/auth/\[...nextauth\]/route.ts + +``` + +!!! Note + The directory `src/app/api/auth/[...nextauth]/route.ts` in a Next.js project is used to define a dynamic API route for handling authentication. The `[...nextauth]` is a catch-all route that processes multiple authentication-related requests such as sign-in, sign-out, and session management. The route.ts file specifies the logic for these operations, typically by exporting handlers for HTTP methods like GET and POST. This setup centralizes authentication logic, supports OAuth providers like Google or GitHub, and integrates seamlessly into Next.js applications for secure and scalable authentication workflows. + + +Update the `src/app/api/auth/[...nextauth]/route.ts` file with the following code. + +```javascript title="route.ts" +import { handlers } from "@/auth" +export const { GET, POST } = handlers +``` + + +Next, create `src/middleware.ts` file with the following code. + +```bash + +touch mkdir -p src/middleware.ts + +``` + + +```javascript title="middleware.ts" +export { auth as middleware } from "@/auth" + +``` + + +## Add login and logout link to your app + +Replace the existing content of the `page.tsx` file with following content to add login and logout features from Auth.JS. + +```javascript title="page.tsx" +import { auth, signIn, signOut } from "@/auth" + +export default async function Home() { + const session = await auth(); + + return ( +
+ { + !session ? ( +
{ + "use server" + await signIn("asgardeo") + }} + > + +
+ ) : ( + <> +

You are now signed in!

+ +
{ + "use server" + await signOut() + }} + > + +
+ + ) + } +
+ ); +} +``` + +Visit your app's homepage at [http://localhost:3000](http://localhost:3000). + +!!! Important + + You need to create a test user in {{ product_name }} by following this [guide]({{ base_path }}/guides/users/manage-users/#onboard-single-user){:target="_blank"} to tryout login and logout features. + +## Display logged in user details + +Modified the code as below to see logged in user details. + +```javascript title="auth.ts" hl_lines="14-29" + +import NextAuth from "next-auth" +import Asgardeo from "next-auth/providers/asgardeo" + +declare module "next-auth" { + interface User { + username?: string; + } +} + +export const { handlers, signIn, signOut, auth } = NextAuth({ + providers: [Asgardeo({ + issuer: process.env.AUTH_ASGARDEO_ISSUER + })], + callbacks: { + async jwt({ token, profile }) { + if (profile) { + token.username = profile.username; + } + + return token; + }, + async session({ session, token }) { + if (token) { + session.user.username = token.username as string; + } + + return session; + } + } +}) + +``` + +Then, update `page.tsx` with the following highlighted line to display the username of logged in user. + +```javascript title="page.tsx" hl_lines="4" + +... + <> +

You are now signed in!

+

hello {session.user?.username}

+
{ + "use server" + await signOut() + }} + > + +
+ + +... + +``` + + + + diff --git a/en/identity-server/7.0.0/docs/quick-starts/nextjs.md b/en/identity-server/7.0.0/docs/quick-starts/nextjs.md new file mode 100644 index 0000000000..f3a64b8dbe --- /dev/null +++ b/en/identity-server/7.0.0/docs/quick-starts/nextjs.md @@ -0,0 +1,320 @@ +--- +template: templates/quick-start.html +heading: Next.JS Quickstart +description: Welcome to the Next.js Quickstart guide! In this document, you will learn to build a Next.js app, add user login and display user profile information using WSO2 Identity Server. +what_you_will_learn: + - Create new Next.js app + - Install Asgardeo provider for Auth.js + - Add user login and logout + - Display user profile information +prerequisites: + - About 15 minutes + - Set-up WSO2 Identity Server + - Install a JS package manager + - A favorite text editor or IDE +# source_code: Next.js App Sample +whats_next: + # - Try out {{ product_name }} complete React guide + # - Try out {{product_name}} user onboarding complete guide for React + # - Read security best practices for React app guide +--- + + +## Configure an Application in {{ product_name }} + +- Sign into {{ product_name }} console and navigate to **Applications > New Application.** +- Select **Traditional Web Application** and complete the wizard popup by providing a suitable name and an authorized redirect URL.(*Ensure that the protocol remains set to OpenID Connect (OIDC).)* + +*Example:* + +- *Name - wso2is-nextjs* +- *Authorized redirect URL - http://localhost:3000/api/auth/callback/asgardeo* + + + +!!! Info + + The authorized redirect URL determines where {{product_name}} should send users after they successfully log in. Typically, this will be the web address where your app is hosted. For this guide, we'll use ` http://localhost:3000/api/auth/callback/asgardeo`, as the authorized redirect URL . + +!!! note + + Make a note of the following values from the **Protocol** and **Info** tabs of the registered application. You will need them during the **Step 4** + + - **`client-id`** from the **Protocol** tab. + - **`client-secret`** from the **Protocol** tab. + - **`issuer`** from from the **Info** tab. + +## Create a Next.js app + +Create your new Next.js app. + +=== "npm" + + ``` bash + npx create-next-app@latest --typescript wso2is-nextjs + + cd wso2is-nextjs + + npm install + + npm run dev + ``` + +=== "yarn" + + ``` bash + yarn create next-app --typescript wso2is-nextjs + + cd wso2is-nextjs + + yran install + + yarn dev + ``` + +=== "pnpm" + + ``` bash + pnpm create next-app --typescript wso2is-nextjs + + cd wso2is-nextjs + + pnpm install + + pnpm run dev + ``` + +## Install Auth.js library + +Auth.js is a lightweight JavaScript library designed for simplifying authentication workflows in web application. The [Asgardeo provider for Auth.js](https://authjs.dev/reference/core/providers/asgardeo){:target="_blank"} offers all the components and hooks you need to integrate your app with {{product_name}}.To get started, simply add Auth.js library to the project. Make sure to stop the dev server started in the previous step. + + +!!! Info + + Asgardeo-branded SDKs and such as Asgardeo provider for Auth.js used in this guide can be used to build apps to work with the all [WSO2 identity suite](https://wso2.com/identity-and-access-management/){:target="_blank"} of products that includes [WSO2 Identity Server (WSO2 IS)](https://wso2.com/identity-server/){:target="_blank"}, WSO2 [Private Identity Cloud (WSO2 PIC)](https://wso2.com/private-identity-cloud/){:target="_blank"} and [Asgardeo](https://wso2.com/asgardeo/){:target="_blank"}. + + +=== "npm" + + ``` bash + npm install next-auth@beta + ``` + +=== "yarn" + + ``` bash + yarn add next-auth@beta + ``` + +=== "pnpm" + + ``` bash + pnpm add next-auth@beta + ``` + +Next, generate **`AUTH_SECRET`** environment variable. + +=== "npm" + + ``` bash + npx auth secret + + ``` +=== "yarn" + + ``` bash + yarn dlx auth secret + ``` + +=== "pnpm" + + ``` bash + pnpm dlx auth secret + ``` + +Add following entries to the .env or .env.local file, and make sure to replace the placeholders in the following code with the **`client-id`**, **`client-secret`** and **`issuer`** values you copied in **Step-1** during the application registration in the {{product_name}} console. + + +```bash title=".env.local" + AUTH_ASGARDEO_ID="" + AUTH_ASGARDEO_SECRET="" + AUTH_ASGARDEO_ISSUER="" + +``` + + + +## Create the `auth.js` configuration File + +Create a file called `/src/auth.ts'`. + +```bash + +touch /src/auth.ts + +``` + +Add {{product_name}} as a provider in the `/src/auth.ts'` file. + +```javascript title="auth.ts" +import NextAuth from "next-auth" +import Asgardeo from "next-auth/providers/asgardeo" + +export const { handlers, signIn, signOut, auth } = NextAuth({ + providers: [Asgardeo({ + issuer: process.env.AUTH_ASGARDEO_ISSUER + })], +}) + +``` + + + +Create a Route Handler file in the `src/app/api/auth/[...nextauth]/route.ts` location. + +```bash +mkdir -p src/app/api/auth/\[...nextauth\] + +touch mkdir -p src/app/api/auth/\[...nextauth\]/route.ts + +``` + +!!! Note + The directory `src/app/api/auth/[...nextauth]/route.ts` in a Next.js project is used to define a dynamic API route for handling authentication. The `[...nextauth]` is a catch-all route that processes multiple authentication-related requests such as sign-in, sign-out, and session management. The route.ts file specifies the logic for these operations, typically by exporting handlers for HTTP methods like GET and POST. This setup centralizes authentication logic, supports OAuth providers like Google or GitHub, and integrates seamlessly into Next.js applications for secure and scalable authentication workflows. + + +Update the `src/app/api/auth/[...nextauth]/route.ts` file with the following code. + +```javascript title="route.ts" +import { handlers } from "@/auth" +export const { GET, POST } = handlers +``` + + +Next, create `src/middleware.ts` file with the following code. + +```bash + +touch mkdir -p src/middleware.ts + +``` + + +```javascript title="middleware.ts" +export { auth as middleware } from "@/auth" + +``` + + +## Add login and logout link to your app + +Replace the existing content of the `page.tsx` file with following content to add login and logout features from Auth.JS. + +```javascript title="page.tsx" +import { auth, signIn, signOut } from "@/auth" + +export default async function Home() { + const session = await auth(); + + return ( +
+ { + !session ? ( +
{ + "use server" + await signIn("asgardeo") + }} + > + +
+ ) : ( + <> +

You are now signed in!

+ +
{ + "use server" + await signOut() + }} + > + +
+ + ) + } +
+ ); +} +``` + +Visit your app's homepage at [http://localhost:3000](http://localhost:3000). + +!!! Important + + You need to create a test user in {{ product_name }} by following this [guide]({{ base_path }}/guides/users/manage-users/#onboard-single-user){:target="_blank"} to tryout login and logout features. + +## Display logged in user details + +Modified the code as below to see logged in user details. + +```javascript title="auth.ts" hl_lines="14-29" + +import NextAuth from "next-auth" +import Asgardeo from "next-auth/providers/asgardeo" + +declare module "next-auth" { + interface User { + username?: string; + } +} + +export const { handlers, signIn, signOut, auth } = NextAuth({ + providers: [Asgardeo({ + issuer: process.env.AUTH_ASGARDEO_ISSUER + })], + callbacks: { + async jwt({ token, profile }) { + if (profile) { + token.username = profile.username; + } + + return token; + }, + async session({ session, token }) { + if (token) { + session.user.username = token.username as string; + } + + return session; + } + } +}) + +``` + +Then, update `page.tsx` with the following highlighted line to display the username of logged in user. + +```javascript title="page.tsx" hl_lines="4" + +... + <> +

You are now signed in!

+

hello {session.user?.username}

+
{ + "use server" + await signOut() + }} + > + +
+ + +... + +``` + + + + From f8175036fcaa4a769336cb3736eafa9e0e92f81b Mon Sep 17 00:00:00 2001 From: Sagara Date: Fri, 29 Nov 2024 18:52:12 +1300 Subject: [PATCH 2/9] Update en/asgardeo/docs/quick-starts/nextjs.md Co-authored-by: Pavindu Lakshan --- en/asgardeo/docs/quick-starts/nextjs.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/en/asgardeo/docs/quick-starts/nextjs.md b/en/asgardeo/docs/quick-starts/nextjs.md index 334305c4ba..757a9ce2ad 100644 --- a/en/asgardeo/docs/quick-starts/nextjs.md +++ b/en/asgardeo/docs/quick-starts/nextjs.md @@ -307,6 +307,3 @@ Then, update `page.tsx` with the following highlighted line to display the usern ``` - - - From 25b799b922ae4abbc599c40fbd52b5270e42fc16 Mon Sep 17 00:00:00 2001 From: Sagara Date: Fri, 29 Nov 2024 18:52:43 +1300 Subject: [PATCH 3/9] Update en/asgardeo/docs/quick-starts/nextjs.md Co-authored-by: Pavindu Lakshan --- en/asgardeo/docs/quick-starts/nextjs.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/en/asgardeo/docs/quick-starts/nextjs.md b/en/asgardeo/docs/quick-starts/nextjs.md index 757a9ce2ad..270911afef 100644 --- a/en/asgardeo/docs/quick-starts/nextjs.md +++ b/en/asgardeo/docs/quick-starts/nextjs.md @@ -290,19 +290,18 @@ Then, update `page.tsx` with the following highlighted line to display the usern ```javascript title="page.tsx" hl_lines="4" ... - <> -

You are now signed in!

-

hello {session.user?.username}

-
{ - "use server" - await signOut() - }} - > - -
- - +<> +

You are now signed in!

+

hello {session.user?.username}

+
{ + "use server" + await signOut() + }} + > + +
+ ... ``` From 8d207783a46a00b556747ca709fcf6d6bc3cb3dc Mon Sep 17 00:00:00 2001 From: Sagara Date: Fri, 29 Nov 2024 18:52:54 +1300 Subject: [PATCH 4/9] Update en/asgardeo/docs/quick-starts/nextjs.md Co-authored-by: Pavindu Lakshan --- en/asgardeo/docs/quick-starts/nextjs.md | 1 - 1 file changed, 1 deletion(-) diff --git a/en/asgardeo/docs/quick-starts/nextjs.md b/en/asgardeo/docs/quick-starts/nextjs.md index 270911afef..9366cd03d9 100644 --- a/en/asgardeo/docs/quick-starts/nextjs.md +++ b/en/asgardeo/docs/quick-starts/nextjs.md @@ -182,7 +182,6 @@ import { handlers } from "@/auth" export const { GET, POST } = handlers ``` - Next, create `src/middleware.ts` file with the following code. ```bash From 8a1e247a7283982a4946809c8569e3804aa380c8 Mon Sep 17 00:00:00 2001 From: Sagara Date: Fri, 29 Nov 2024 18:53:15 +1300 Subject: [PATCH 5/9] Update en/asgardeo/docs/quick-starts/nextjs.md Co-authored-by: Pavindu Lakshan --- en/asgardeo/docs/quick-starts/nextjs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/asgardeo/docs/quick-starts/nextjs.md b/en/asgardeo/docs/quick-starts/nextjs.md index 9366cd03d9..67542ff720 100644 --- a/en/asgardeo/docs/quick-starts/nextjs.md +++ b/en/asgardeo/docs/quick-starts/nextjs.md @@ -172,7 +172,7 @@ touch mkdir -p src/app/api/auth/\[...nextauth\]/route.ts ``` !!! Note - The directory `src/app/api/auth/[...nextauth]/route.ts` in a Next.js project is used to define a dynamic API route for handling authentication. The `[...nextauth]` is a catch-all route that processes multiple authentication-related requests such as sign-in, sign-out, and session management. The route.ts file specifies the logic for these operations, typically by exporting handlers for HTTP methods like GET and POST. This setup centralizes authentication logic, supports OAuth providers like Google or GitHub, and integrates seamlessly into Next.js applications for secure and scalable authentication workflows. + The directory `src/app/api/auth/[...nextauth]/route.ts` in a Next.js project is used to define a dynamic API route for handling authentication. The `[...nextauth]` is a catch-all route that processes multiple authentication-related requests such as sign-in, sign-out, and session management. The `route.ts` file specifies the logic for these operations, typically by exporting handlers for HTTP methods like GET and POST. This setup centralizes authentication logic, supports OAuth providers like Google or GitHub, and integrates seamlessly into Next.js applications for secure and scalable authentication workflows. Update the `src/app/api/auth/[...nextauth]/route.ts` file with the following code. From 63ddc7937df2d3a5a05918c089ce1c75f8034762 Mon Sep 17 00:00:00 2001 From: Sagara Date: Fri, 29 Nov 2024 18:53:55 +1300 Subject: [PATCH 6/9] Update en/asgardeo/docs/quick-starts/nextjs.md Co-authored-by: Pavindu Lakshan --- en/asgardeo/docs/quick-starts/nextjs.md | 1 - 1 file changed, 1 deletion(-) diff --git a/en/asgardeo/docs/quick-starts/nextjs.md b/en/asgardeo/docs/quick-starts/nextjs.md index 67542ff720..1f68d04cbc 100644 --- a/en/asgardeo/docs/quick-starts/nextjs.md +++ b/en/asgardeo/docs/quick-starts/nextjs.md @@ -168,7 +168,6 @@ Create a Route Handler file in the `src/app/api/auth/[...nextauth]/route.ts` loc mkdir -p src/app/api/auth/\[...nextauth\] touch mkdir -p src/app/api/auth/\[...nextauth\]/route.ts - ``` !!! Note From 50436825e60697a5ab14e008188b472800ed8f51 Mon Sep 17 00:00:00 2001 From: Sagara Date: Fri, 29 Nov 2024 18:54:11 +1300 Subject: [PATCH 7/9] Update en/asgardeo/docs/quick-starts/nextjs.md Co-authored-by: Pavindu Lakshan --- en/asgardeo/docs/quick-starts/nextjs.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/en/asgardeo/docs/quick-starts/nextjs.md b/en/asgardeo/docs/quick-starts/nextjs.md index 1f68d04cbc..28e7f566a7 100644 --- a/en/asgardeo/docs/quick-starts/nextjs.md +++ b/en/asgardeo/docs/quick-starts/nextjs.md @@ -160,8 +160,6 @@ export const { handlers, signIn, signOut, auth } = NextAuth({ ``` - - Create a Route Handler file in the `src/app/api/auth/[...nextauth]/route.ts` location. ```bash From dc4696cbbbf2b0c609c370c05e7a7191e08492cd Mon Sep 17 00:00:00 2001 From: Sagara Date: Fri, 29 Nov 2024 18:54:20 +1300 Subject: [PATCH 8/9] Update en/identity-server/7.0.0/docs/quick-starts/nextjs.md Co-authored-by: Omal Vindula <42619922+DonOmalVindula@users.noreply.github.com> --- en/identity-server/7.0.0/docs/quick-starts/nextjs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/identity-server/7.0.0/docs/quick-starts/nextjs.md b/en/identity-server/7.0.0/docs/quick-starts/nextjs.md index f3a64b8dbe..37bf11860d 100644 --- a/en/identity-server/7.0.0/docs/quick-starts/nextjs.md +++ b/en/identity-server/7.0.0/docs/quick-starts/nextjs.md @@ -67,7 +67,7 @@ Create your new Next.js app. cd wso2is-nextjs - yran install + yarn install yarn dev ``` From 3d5b4143214a6d2726988d3dbe86807165fac140 Mon Sep 17 00:00:00 2001 From: Sagara Date: Fri, 29 Nov 2024 18:54:33 +1300 Subject: [PATCH 9/9] Update en/asgardeo/docs/quick-starts/nextjs.md Co-authored-by: Omal Vindula <42619922+DonOmalVindula@users.noreply.github.com> --- en/asgardeo/docs/quick-starts/nextjs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/asgardeo/docs/quick-starts/nextjs.md b/en/asgardeo/docs/quick-starts/nextjs.md index 28e7f566a7..2bb2067362 100644 --- a/en/asgardeo/docs/quick-starts/nextjs.md +++ b/en/asgardeo/docs/quick-starts/nextjs.md @@ -65,7 +65,7 @@ Create your new Next.js app. cd asgardeo-nextjs - yran install + yarn install yarn dev ```