unduhan nextjs auth0 - pengunduhan kode sumber nextjs auth0

nextjs auth0

Kode sumber lainnya

v3.5.0

Unduh

Auth0 Next.js SDK adalah perpustakaan untuk mengimplementasikan otentikasi pengguna di aplikasi Next.js.

Dokumentasi - Memulai- Referensi API - Umpan Balik

Dokumentasi

QuickStart- panduan kami untuk menambahkan Auth0 ke aplikasi Next.js Anda.
FAQ - Pertanyaan yang sering diajukan tentang nextjs-auth0.
Contoh - banyak contoh untuk berbagai kasus penggunaan Anda.
Keamanan - Beberapa pemberitahuan keamanan penting yang harus Anda periksa.
Arsitektur - Tinjauan arsitektur SDK.
Pengujian - Beberapa bantuan dalam menguji aplikasi nextjs-auth0 Anda.
Penerapan - Bagaimana kami menerapkan aplikasi contoh kami ke Vercel.
Situs Dokumen - jelajahi situs dokumen kami dan pelajari lebih lanjut tentang Auth0.

Memulai

Instalasi

Menggunakan npm:

 npm instal @auth0/nextjs-auth0

Pustaka ini memerlukan Node.js 16 LTS dan versi LTS yang lebih baru.

Konfigurasi Auth0

Buat Aplikasi Web Reguler di Dasbor Auth0.

Jika Anda menggunakan aplikasi yang sudah ada , verifikasi bahwa Anda telah mengonfigurasi pengaturan berikut di Aplikasi Web Reguler Anda:
Klik pada tab "Pengaturan" di halaman aplikasi Anda.
Gulir ke bawah dan klik tautan "Tampilkan Pengaturan Lanjutan".
Di bawah "Pengaturan Lanjutan", klik pada tab "OAuth".
Pastikan "Algoritma Tanda Tangan JsonWebToken" diatur ke RS256 dan "Konforman OIDC" diaktifkan.

Selanjutnya, konfigurasikan URL berikut untuk aplikasi Anda di bagian "URI Aplikasi" pada halaman "Pengaturan":

URL Panggilan Balik yang Diizinkan : http://localhost:3000/api/auth/callback
URL Keluar yang Diizinkan : http://localhost:3000/

Catat nilai ID Klien , Rahasia Klien , dan Domain di bagian "Informasi Dasar". Anda akan memerlukan nilai-nilai ini pada langkah berikutnya.

Pengaturan Dasar

Konfigurasikan Aplikasi

Anda harus mengizinkan aplikasi Next.js Anda berkomunikasi dengan baik dengan Auth0. Anda dapat melakukannya dengan membuat file .env.local di bawah direktori proyek root Anda yang mendefinisikan nilai konfigurasi Auth0 yang diperlukan sebagai berikut:

 # Nilai rahasia panjang yang digunakan untuk mengenkripsi cookie sesiAUTH0_SECRET='LONG_RANDOM_VALUE'# Url dasar aplikasi AndaAUTH0_BASE_URL='http://localhost:3000'# Url domain penyewa Auth0 AndaAUTH0_ISSUER_BASE_URL='https://YOUR_AUTH0_DOMAIN.auth0 .com'# Klien aplikasi Auth0 Anda IDAUTH0_CLIENT_ID='YOUR_AUTH0_CLIENT_ID'# Rahasia Klien aplikasi Auth0 AndaAUTH0_CLIENT_SECRET='YOUR_AUTH0_CLIENT_SECRET'

Anda dapat menjalankan perintah berikut untuk menghasilkan string yang sesuai untuk nilai AUTH0_SECRET :

 simpul -e "konsol.log(crypto.randomBytes(32).toString('hex'))"

Anda dapat melihat daftar lengkap opsi konfigurasi Auth0 di bagian "Properti konfigurasi" pada dokumen "Konfigurasi modul".

Untuk detail selengkapnya tentang memuat variabel lingkungan di Next.js, kunjungi dokumen "Variabel Lingkungan".

Tambahkan handleAuth() ke aplikasi Anda, yang akan membuat pengendali rute berikut yang melakukan berbagai bagian alur autentikasi:

/api/auth/login : Aplikasi Next.js Anda mengalihkan pengguna ke penyedia identitas Anda agar mereka dapat masuk (Anda juga dapat meneruskan parameter returnTo untuk kembali ke URL relatif khusus setelah login, misalnya /api/auth/login?returnTo=/profile ).
/api/auth/callback : Penyedia identitas Anda mengarahkan pengguna ke rute ini setelah mereka berhasil masuk.
/api/auth/logout : Aplikasi Next.js Anda mengeluarkan pengguna.
/api/auth/me : Anda dapat mengambil informasi profil pengguna dalam format JSON.

Lanjutkan penyiapan tergantung pada router Anda:

Perute Halaman
Router Aplikasi

Perute Halaman

Tambahkan Rute API Dinamis

Buat pengendali rute API dinamis di bawah direktori /pages/api :

Buat direktori auth di bawah direktori /pages/api/ .
Buat file [auth0].js di bawah direktori auth yang baru dibuat.

Jalur ke file rute API dinamis Anda adalah /pages/api/auth/[auth0].js . Isi file itu sebagai berikut:

 impor { handleAuth } dari '@auth0/nextjs-auth0';ekspor default handleAuth();

Tambahkan UserProvider ke Aplikasi Kustom

Gabungkan komponen pages/_app.js Anda dengan komponen UserProvider :

 // halaman/_app.jsimport Bereaksi dari 'reaksi';impor { UserProvider } dari '@auth0/nextjs-auth0/client';ekspor fungsi default Aplikasi({ Komponen, pageProps }) {
  kembali (<UserProvider> <Komponen {...pageProps} /></UserProvider>
  );}

Gunakan Otentikasi

Anda sekarang dapat menentukan apakah pengguna diautentikasi dengan memeriksa apakah objek user yang dikembalikan oleh hook useUser() telah ditentukan. Anda juga dapat masuk atau keluar pengguna Anda dari lapisan frontend aplikasi Next.js dengan mengarahkan mereka ke rute sesuai yang dibuat secara otomatis:

 // halaman/index.jsimport { useUser } dari '@auth0/nextjs-auth0/client';ekspor fungsi default Index() {
  const { pengguna, kesalahan, isLoading } = useUser();

  if (isLoading) mengembalikan <div>Memuat...</div>;
  jika (kesalahan) mengembalikan <div>{error.message}</div>;

  if (pengguna) {kembali ( <div>Selamat datang {user.name}! <a href="/api/auth/logout">Keluar</a> </div>);
  }

  kembali <a href="/api/auth/login">Masuk</a>;}

Aturan linting berikutnya mungkin menyarankan penggunaan komponen Link , bukan tag jangkar. Komponen Link dimaksudkan untuk melakukan transisi sisi klien antar halaman. Karena tautan mengarah ke rute API dan bukan ke laman, Anda harus menyimpannya sebagai tag jangkar.

Router Aplikasi

Lihat Menggunakan SDK ini dengan Komponen Server React sebelum melanjutkan.

Tambahkan Rute API Dinamis

Buat pengendali rute API dinamis yang mencakup semua hal di bawah direktori /app/api (sebenarnya Anda tidak perlu meletakkan rute API di bawah /api tetapi kami mempertahankan konvensi untuk kesederhanaan):

Buat direktori api di bawah direktori /app/ .
Buat direktori auth di bawah direktori /app/api/ yang baru dibuat.
Buat direktori [auth0] di bawah direktori auth yang baru dibuat.
Buat file route.js di bawah direktori [auth0] yang baru dibuat.

Jalur ke file rute API dinamis Anda adalah /app/api/auth/[auth0]/route.js . Isi file itu sebagai berikut:

 impor { handleAuth } dari '@auth0/nextjs-auth0';ekspor const GET = handleAuth();

Tambahkan `UserProvider` ke tata letak Anda

Gabungkan komponen app/layout.js Anda dengan komponen UserProvider :

 // app/layout.jsimport Bereaksi dari 'react';import { UserProvider } dari '@auth0/nextjs-auth0/client';ekspor fungsi default Aplikasi({ anak-anak }) {
  kembali (<UserProvider> <body>{children}</body></UserProvider>
  );}

Gunakan Otentikasi

Anda sekarang dapat menentukan apakah pengguna diautentikasi dengan memeriksa apakah objek user yang dikembalikan oleh hook useUser() telah ditentukan. Anda juga dapat masuk atau keluar pengguna Anda dari lapisan frontend aplikasi Next.js dengan mengarahkan mereka ke rute sesuai yang dibuat secara otomatis:

 // halaman/index.js'use client';import { useUser } dari '@auth0/nextjs-auth0/client';ekspor fungsi default Index() {
  const { pengguna, kesalahan, isLoading } = useUser();

  if (isLoading) mengembalikan <div>Memuat...</div>;
  jika (kesalahan) mengembalikan <div>{error.message}</div>;

  if (pengguna) {kembali ( <div>Selamat datang {user.name}! <a href="/api/auth/logout">Keluar</a> </div>);
  }

  kembali <a href="/api/auth/login">Masuk</a>;}

Aturan linting berikutnya mungkin menyarankan penggunaan komponen Link , bukan tag jangkar. Komponen Link dimaksudkan untuk melakukan transisi sisi klien antar halaman. Karena tautan mengarah ke rute API dan bukan ke laman, Anda harus menyimpannya sebagai tag jangkar.

Menggunakan SDK ini dengan React Server Components

Komponen Server di Direktori Aplikasi (termasuk Halaman dan Tata Letak) tidak dapat menulis ke cookie.

Jika Anda hanya mengandalkan Komponen Server untuk membaca dan memperbarui sesi Anda, Anda harus mengetahui hal berikut:

Jika Anda memiliki sesi bergulir (default untuk SDK ini), masa berlakunya tidak akan diperbarui saat pengguna mengunjungi situs Anda. Jadi sesi ini mungkin berakhir lebih cepat dari yang Anda harapkan (Anda dapat menggunakan withMiddlewareAuthRequired untuk memitigasi hal ini).
Jika Anda menyegarkan token akses, token akses baru tidak akan dipertahankan dalam sesi tersebut. Jadi upaya selanjutnya untuk mendapatkan token akses akan selalu mengakibatkan penyegaran token akses yang kedaluwarsa dalam sesi tersebut.
Jika Anda membuat pembaruan lain pada sesi tersebut, pembaruan tersebut tidak akan dipertahankan di antara permintaan.

Cookie dapat ditulis dari middleware, pengendali rute, dan tindakan server.

Untuk contoh komprehensif lainnya, lihat dokumen EXAMPLES.md.

Referensi API

pelayan

Untuk Node

import * from @auth0/nextjs-auth0

Untuk waktu proses Edge

import * from @auth0/nextjs-auth0/edge

Opsi Konfigurasi dan variabel Lingkungan
initAuth0
menanganiAuth
menanganiLogin
menangani Panggilan Balik
menanganiLogout
menanganiProfil
denganApiAuthDiperlukan
denganPageAuthDiperlukan
dapatkanSesi
pembaruanSesi
dapatkanAccessToken
withMiddlewareAuthRequired (khusus Edge)

Klien (untuk Browser)

import * from @auth0/nextjs-auth0/client

Penyedia Pengguna
gunakanPengguna
denganPageAuthDiperlukan

Menguji pembantu

import * from @auth0/nextjs-auth0/testing

menghasilkanSessionCookie

Kunjungi Dokumen API yang dibuat secara otomatis untuk detail selengkapnya

Cookie dan Keamanan

Semua cookie akan disetel ke HttpOnly, SameSite=Lax dan akan disetel ke Secure jika AUTH0_BASE_URL aplikasi adalah https .

Pengaturan HttpOnly akan memastikan bahwa JavaScript sisi klien tidak dapat mengakses cookie untuk mengurangi permukaan serangan serangan XSS.

Pengaturan SameSite=Lax akan membantu mengurangi serangan CSRF. Pelajari lebih lanjut tentang SameSite dengan membaca postingan blog "Perubahan Perilaku Browser Mendatang: Yang Perlu Diketahui Pengembang".

Caching dan Keamanan

Banyak penyedia hosting akan menawarkan untuk menyimpan konten Anda dalam cache agar dapat menyajikan data kepada pengguna Anda secepat mungkin. Misalnya Vercel akan menyimpan konten Anda dalam cache di Vercel Edge Network untuk semua konten statis dan Fungsi Tanpa Server jika Anda menyediakan header cache yang diperlukan pada respons Anda.

Biasanya merupakan ide yang buruk untuk menyimpan respons apa pun dalam cache yang memerlukan autentikasi, meskipun konten respons tampak aman untuk di-cache, mungkin ada data lain dalam respons yang tidak aman.

SDK ini menawarkan sesi bergulir secara default, yang berarti bahwa respons apa pun yang membaca sesi tersebut akan memiliki header Set-Cookie untuk memperbarui masa berlaku cookie. Vercel dan kemungkinan penyedia hosting lainnya menyertakan header Set-Cookie dalam respons yang di-cache, jadi meskipun menurut Anda konten respons dapat di-cache secara publik, header Set-Cookie respons tidak bisa.

Periksa aturan caching penyedia hosting Anda, namun secara umum Anda tidak boleh menyimpan respons yang memerlukan autentikasi atau bahkan menyentuh sesi untuk memeriksa autentikasi (misalnya saat menggunakan withApiAuthRequired , withPageAuthRequired atau bahkan hanya getSession atau getAccessToken ).

Penanganan Kesalahan dan Keamanan

Kesalahan yang berasal dari Auth0 dalam panggilan balik redirect_uri mungkin berisi masukan pengguna yang tercermin melalui error OpenID Connect dan parameter kueri error_description . Oleh karena itu, kami melakukan pelolosan dasar pada properti message , error dan error_description dari IdentityProviderError .

Namun, jika Anda menulis pengendali kesalahan Anda sendiri, Anda tidak boleh merender properti error message , atau error dan error_description tanpa menggunakan mesin templating yang akan menghindarinya dengan benar untuk konteks HTML lain terlebih dahulu.

Jalur Dasar dan Perutean Internasional

Dengan Next.js Anda dapat menerapkan aplikasi Next.js di bawah sub-jalur domain menggunakan Base Path dan melayani rute internasionalisasi (i18n) menggunakan Perutean Internasional.

Jika Anda menggunakan fitur ini, url aplikasi Anda akan berubah sehingga url ke rute nextjs-auth0 akan berubah. Untuk mengakomodasi hal ini ada berbagai tempat di SDK yang dapat Anda sesuaikan urlnya.

Misalnya, jika basePath: '/foo' Anda harus menambahkan ini ke loginUrl dan profileUrl yang ditentukan dalam Auth0Provider Anda :

 // _app.jsxfunction Aplikasi({ Komponen, pageProps }) {
  kembali (<UserProvider loginUrl="/foo/api/auth/login" profileUrl="/foo/api/auth/me"> <Komponen {...pageProps} /></UserProvider>
  );}

Selain itu, tautan apa pun untuk masuk atau keluar harus menyertakan basePath :

 <a href="/foo/api/auth/login">Masuk</a><br /><a href="/foo/api/auth/logout">Keluar</a>

Anda harus mengonfigurasi baseUrl (atau variabel lingkungan AUTH0_BASE_URL ). Misalnya:

 # .env.localAUTH0_BASE_URL=http://localhost:3000/foo

Untuk halaman mana pun yang dilindungi dengan Sisi Server withPageAuthRequired, Anda harus memperbarui parameter returnTo bergantung pada basePath dan locale jika perlu.

 // ./pages/my-ssr-page.jsxexport default MySsrPage = () => <></>;const getFullReturnTo = (ctx) => {
  // TODO: implementasikan getFullReturnTo berdasarkan ctx.resolvedUrl, ctx.locale
  // dan pengaturan basePath dan i18n next.config.js Anda.
  return '/foo/en-US/my-ssr-page';};ekspor const getServerSideProps = (ctx) => {
  const returnTo = getFullReturnTo(ctx.req);
  kembali denganPageAuthRequired({ returnTo })(ctx);};

Perbandingan dengan Auth0 React SDK

Kami juga menyediakan Auth0 React SDK, auth0-react, yang mungkin cocok untuk aplikasi Next.js Anda.

Model keamanan SPA yang digunakan oleh auth0-react berbeda dengan model keamanan Aplikasi Web yang digunakan oleh SDK ini. Singkatnya, SDK ini melindungi halaman dan rute API dengan sesi cookie (lihat "Cookie dan Keamanan"). Pustaka SPA seperti auth0-react akan menyimpan token ID pengguna dan token akses langsung di browser dan menggunakannya untuk mengakses API eksternal secara langsung.

Anda harus menyadari implikasi keamanan dari kedua model tersebut. Namun, auth0-react mungkin lebih sesuai dengan kebutuhan Anda jika Anda memenuhi salah satu skenario berikut:

Anda menggunakan Ekspor HTML Statis dengan Next.js.
Anda tidak perlu mengakses data pengguna selama rendering sisi server.
Anda ingin mendapatkan token akses dan memanggil API eksternal langsung dari lapisan frontend daripada menggunakan rute API Next.js sebagai proksi untuk memanggil API eksternal.

Pengujian

Secara default, SDK membuat dan mengelola instance tunggal agar dapat dijalankan seumur hidup aplikasi. Saat menguji aplikasi, Anda mungkin perlu menyetel ulang instance ini, sehingga statusnya tidak bocor di antara pengujian.

Jika Anda menggunakan Jest, sebaiknya gunakan jest.resetModules() setelah setiap pengujian. Alternatifnya, Anda dapat mencoba membuat instance SDK Anda sendiri, sehingga dapat dibuat ulang di antara pengujian.

Untuk pengujian ujung ke ujung, lihat bagaimana kami menggunakan Penyedia OIDC tiruan.

Menyebarkan

Untuk penerapannya, lihat bagaimana kami menerapkan aplikasi contoh kami ke Vercel.

Berkontribusi

Kami menghargai masukan dan kontribusi pada repo ini! Sebelum memulai, harap baca yang berikut ini:

Pedoman kontribusi umum Auth0
Pedoman kode etik Auth0
Panduan kontribusi repo ini

Pelaporan Kerentanan

Harap jangan laporkan kerentanan keamanan pada pelacak masalah GitHub publik. Program Pengungkapan yang Bertanggung Jawab merinci prosedur untuk mengungkapkan masalah keamanan.