authkit nextjs

Perpustakaan AuthKit Next.js

Pustaka AuthKit untuk Next.js menyediakan bantuan praktis untuk autentikasi dan manajemen sesi menggunakan WorkOS & AuthKit dengan Next.js.

Catatan: Pustaka ini ditujukan untuk digunakan dengan Router Aplikasi Next.js.

Instalasi

Instal paket dengan:

 npm i @workos-inc/authkit-nextjs

atau

 yarn add @workos-inc/authkit-nextjs

Pelajaran video

Pra-penerbangan

Pastikan nilai berikut ada di file variabel lingkungan .env.local Anda. ID klien dan kunci API dapat ditemukan di dasbor WorkOS, dan URI pengalihan juga dapat dikonfigurasi di sana.

WORKOS_CLIENT_ID= " client_... " # retrieved from the WorkOS dashboard
WORKOS_API_KEY= " sk_test_... " # retrieved from the WorkOS dashboard
WORKOS_COOKIE_PASSWORD= " <your password> " # generate a secure password here
NEXT_PUBLIC_WORKOS_REDIRECT_URI= " http://localhost:3000/callback " # configured in the WorkOS dashboard

WORKOS_COOKIE_PASSWORD adalah kunci pribadi yang digunakan untuk mengenkripsi cookie sesi. Panjangnya minimal harus 32 karakter. Anda dapat menggunakan generator 1Password atau perpustakaan openssl untuk menghasilkan kata sandi yang kuat melalui baris perintah:

 openssl rand -base64 24

Untuk menggunakan metode signOut , Anda harus mengatur beranda aplikasi Anda di pengaturan dasbor WorkOS di bagian "Pengalihan".

Konfigurasi opsional

Variabel lingkungan tertentu bersifat opsional dan dapat digunakan untuk melakukan debug atau mengonfigurasi pengaturan cookie.

WORKOS_COOKIE_MAX_AGE= ' 600 ' # maximum age of the cookie in seconds. Defaults to 400 days, the maximum allowed in Chrome
WORKOS_COOKIE_DOMAIN= ' example.com '
WORKOS_COOKIE_NAME= ' authkit-cookie '
WORKOS_API_HOSTNAME= ' api.workos.com ' # base WorkOS API URL
WORKOS_API_HTTPS=true # whether to use HTTPS in API calls
WORKOS_API_PORT=3000 # port to use for API calls

WORKOS_COOKIE_DOMAIN dapat digunakan untuk berbagi sesi WorkOS antar aplikasi/domain. Catatan: WORKOS_COOKIE_PASSWORD harus sama di seluruh aplikasi/domain. Tidak diperlukan untuk sebagian besar kasus penggunaan.

Pengaturan

Rute panggilan balik

WorkOS mengharuskan Anda memiliki URL panggilan balik untuk mengalihkan pengguna kembali setelah mereka mengautentikasi. Di aplikasi Next.js Anda, tampilkan rute API dan tambahkan yang berikut ini.

 import { handleAuth } from '@workos-inc/authkit-nextjs' ;

export const GET = handleAuth ( ) ;

Pastikan rute ini cocok dengan variabel WORKOS_REDIRECT_URI dan URI pengalihan yang dikonfigurasi di dasbor WorkOS Anda. Misalnya jika URI pengalihan Anda adalah http://localhost:3000/auth/callback maka Anda akan memasukkan kode di atas ke dalam /app/auth/callback/route.ts .

Anda juga dapat mengontrol nama path yang akan dikirimi pengguna setelah masuk dengan meneruskan opsi returnPathname ke handleAuth seperti:

 export const GET = handleAuth ( { returnPathname : '/dashboard' } ) ;

handleAuth dapat digunakan dengan beberapa opsi.

Pilihan	Bawaan	Keterangan
returnPathname	/	Nama jalur untuk mengarahkan pengguna setelah masuk
baseURL	undefined	URL dasar yang akan digunakan untuk URI pengalihan, bukan yang ada dalam permintaan. Berguna jika aplikasi dijalankan dalam wadah seperti buruh pelabuhan yang nama hostnya bisa berbeda dari yang ada di permintaan

Perangkat Tengah

Pustaka ini mengandalkan middleware Next.js untuk menyediakan manajemen sesi untuk rute. Letakkan yang berikut ini di file middleware.ts di root proyek Anda:

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( ) ;

// Match against pages that require auth
// Leave this out if you want auth on every resource (including images, css etc.)
export const config = { matcher : [ '/' , '/admin' ] } ;

Middleware dapat dikonfigurasi dengan beberapa opsi.

Pilihan	Bawaan	Keterangan
redirectUri	undefined	Digunakan jika Anda memerlukan URI pengalihan Anda disetel secara dinamis (misalnya penerapan pratinjau Vercel)
middlewareAuth	undefined	Digunakan untuk mengonfigurasi opsi autentikasi middleware. Lihat autentikasi middleware untuk detail selengkapnya.
debug	false	Mengaktifkan log debug.
signUpPaths	[]	Digunakan untuk menentukan jalur yang harus menggunakan petunjuk layar 'pendaftaran' saat mengalihkan ke AuthKit.

URI pengalihan khusus

Jika Anda memerlukan URI pengalihan untuk disetel secara dinamis (misalnya penerapan pratinjau Vercel), gunakan opsi redirectUri di authkitMiddleware :

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( {
  redirectUri : 'https://foo.example.com/callback' ,
} ) ;

// Match against pages that require auth
// Leave this out if you want auth on every resource (including images, css etc.)
export const config = { matcher : [ '/' , '/admin' ] } ;

URI pengalihan khusus akan digunakan melalui URI pengalihan yang dikonfigurasi dalam variabel lingkungan.

Penggunaan

Bungkus aplikasi Anda di AuthKitProvider

Gunakan AuthKitProvider untuk menggabungkan tata letak aplikasi Anda, yang menambahkan beberapa perlindungan untuk kasus edge autentikasi.

 import { AuthKitProvider } from '@workos-inc/authkit-nextjs' ;

export default function RootLayout ( { children } : { children : React . ReactNode } ) {
  return (
    < html lang = "en" >
      < body >
        < AuthKitProvider > { children } < / AuthKitProvider >
      < / body >
    < / html >
  ) ;
}

Dapatkan pengguna saat ini

Untuk halaman tempat Anda ingin menampilkan tampilan masuk dan keluar, gunakan withAuth untuk mengambil profil pengguna dari WorkOS.

 import Link from 'next/link' ;
import { getSignInUrl , getSignUpUrl , withAuth , signOut } from '@workos-inc/authkit-nextjs' ;

export default async function HomePage ( ) {
  // Retrieves the user from the session or returns `null` if no user is signed in
  const { user } = await withAuth ( ) ;

  if ( ! user ) {
    // Get the URL to redirect the user to AuthKit to sign in
    const signInUrl = await getSignInUrl ( ) ;

    // Get the URL to redirect the user to AuthKit to sign up
    const signUpUrl = await getSignUpUrl ( ) ;

    return (
      < >
        < Link href = { signInUrl } > Log in < / Link >
        < Link href = { signUpUrl } > Sign Up < / Link >
      < / >
    ) ;
  }

  return (
    < form
      action = { async ( ) => {
        'use server' ;
        await signOut ( ) ;
      } }
    >
      < p > Welcome back { user ?. firstName && `, ${ user ?. firstName } ` } < / p >
      < button type = "submit" > Sign out < / button >
    < / form >
  ) ;
}

Membutuhkan autentikasi

Untuk halaman yang mewajibkan pengguna masuk, Anda dapat menggunakan opsi ensureSignedIn :

 const { user } = await withAuth ( { ensureSignedIn : true } ) ;

Mengaktifkan ensureSignedIn akan mengarahkan pengguna ke AuthKit jika mereka mencoba mengakses halaman tanpa diautentikasi.

Otentikasi middleware

Perilaku default perpustakaan ini adalah meminta autentikasi melalui metode withAuth per halaman. Ada beberapa kasus penggunaan di mana Anda tidak ingin memanggil withAuth (misalnya, Anda tidak memerlukan data pengguna untuk halaman Anda) atau jika Anda lebih memilih pendekatan "aman secara default" di mana setiap rute yang ditentukan dalam pencocokan middleware dilindungi kecuali ditentukan lain. Dalam kasus tersebut, Anda dapat memilih untuk menggunakan autentikasi middleware:

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( {
  middlewareAuth : {
    enabled : true ,
    unauthenticatedPaths : [ '/' , '/about' ] ,
  } ,
} ) ;

// Match against pages that require auth
// Leave this out if you want auth on every resource (including images, css etc.)
export const config = { matcher : [ '/' , '/admin/:path*' , '/about' ] } ;

Pada contoh di atas halaman /admin mengharuskan pengguna untuk login, sedangkan / dan /about dapat diakses tanpa login.

unauthenticatedPaths menggunakan logika glob yang sama dengan pencocokan Next.js.

Ambil sesi di middleware

Terkadang berguna untuk memeriksa sesi pengguna jika Anda ingin membuat middleware khusus. Metode pembantu getSession akan mengambil sesi dari cookie dan memverifikasi token akses.

 import { authkitMiddleware , getSession } from '@workos-inc/authkit-nextjs' ;
import { NextRequest , NextFetchEvent } from 'next/server' ;

export default async function middleware ( request : NextRequest , event : NextFetchEvent ) {
  // authkitMiddleware will handle refreshing the session if the access token has expired
  const response = await authkitMiddleware ( ) ( request , event ) ;

  // If session is undefined, the user is not authenticated
  const session = await getSession ( response ) ;

  // ...add additional middleware logic here

  return response ;
}

// Match against pages that require auth
export const config = { matcher : [ '/' , '/account/:path*' ] } ;

Keluar

Gunakan metode signOut untuk mengeluarkan pengguna yang masuk saat ini dan mengalihkan ke beranda aplikasi Anda. Pengalihan beranda diatur di pengaturan dasbor WorkOS Anda di bawah "Pengalihan".

Memvisualisasikan peniruan identitas

Render komponen Impersonation di aplikasi Anda sehingga jelas ketika seseorang meniru identitas pengguna. Komponen akan menampilkan bingkai dengan beberapa informasi tentang pengguna yang ditiru, serta tombol untuk berhenti meniru identitas.

 import { Impersonation } from '@workos-inc/authkit-nextjs' ;

export default function App ( ) {
  return (
    < div >
      < Impersonation / >
      { /* Your app content */ }
    < / div >
  ) ;
}

Dapatkan token akses

Terkadang berguna untuk mendapatkan token akses secara langsung, misalnya untuk membuat permintaan API ke layanan lain.

 import { withAuth } from '@workos-inc/authkit-nextjs' ;

export default async function HomePage ( ) {
  const { accessToken } = await withAuth ( ) ;

  if ( ! accessToken ) {
    return < div > Not signed in < / div > ;
  }

  const serviceData = await fetch ( '/api/path' , {
    headers : {
      Authorization : `Bearer ${ accessToken } ` ,
    } ,
  } ) ;

  return < div > { serviceData } < / div > ;
}

Menyegarkan sesi

Gunakan metode refreshSession dalam tindakan server atau pengendali rute untuk mengambil detail sesi terbaru, termasuk perubahan apa pun pada peran atau izin pengguna.

Parameter organizationId dapat diteruskan ke refreshSession untuk mengalihkan sesi ke organisasi lain. Jika sesi saat ini tidak diotorisasi untuk organisasi berikutnya, kesalahan otentikasi yang sesuai akan dikembalikan.

Jalur pendaftaran

Opsi signUpPaths dapat diteruskan ke authkitMiddleware untuk menentukan jalur yang harus menggunakan petunjuk layar 'pendaftaran' saat mengalihkan ke AuthKit. Ini berguna jika Anda ingin jalur yang mewajibkan autentikasi diperlakukan sebagai halaman pendaftaran.

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( {
  signUpPaths : [ '/account/sign-up' , '/dashboard/:path*' ] ,
} ) ;

Men-debug

Untuk mengaktifkan log debug, inisialisasi middleware dengan tanda debug diaktifkan.

 import { authkitMiddleware } from '@workos-inc/authkit-nextjs' ;

export default authkitMiddleware ( { debug : true } ) ;

Pemecahan masalah

Kesalahan NEXT_REDIRECT saat menggunakan blok coba/tangkap

Membungkus panggilan withAuth({ ensureSignedIn: true }) dalam blok coba/tangkap akan menyebabkan kesalahan NEXT_REDIRECT . Ini karena withAuth akan mencoba mengalihkan pengguna ke AuthKit jika tidak ada sesi yang terdeteksi dan pengalihan di Berikutnya harus dipanggil di luar coba/tangkap.