authkit nextjs

مكتبة AuthKit Next.js

توفر مكتبة AuthKit الخاصة بـ Next.js مساعدين مناسبين للمصادقة وإدارة الجلسة باستخدام WorkOS وAuthKit مع Next.js.

ملاحظة: هذه المكتبة مخصصة للاستخدام مع جهاز توجيه التطبيقات Next.js.

تثبيت

تثبيت الحزمة مع:

 npm i @workos-inc/authkit-nextjs

أو

 yarn add @workos-inc/authkit-nextjs

فيديو تعليمي

ما قبل الرحلة

تأكد من وجود القيم التالية في ملف متغيرات البيئة .env.local الخاص بك. يمكن العثور على معرف العميل ومفتاح API في لوحة معلومات WorkOS، ويمكن أيضًا تكوين URI لإعادة التوجيه هناك.

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 هو المفتاح الخاص المستخدم لتشفير ملف تعريف ارتباط الجلسة. ويجب أن يكون طوله 32 حرفًا على الأقل. يمكنك استخدام منشئ 1Password أو مكتبة openssl لإنشاء كلمة مرور قوية عبر سطر الأوامر:

 openssl rand -base64 24

لاستخدام طريقة signOut ، ستحتاج إلى تعيين الصفحة الرئيسية لتطبيقك في إعدادات لوحة تحكم WorkOS ضمن "عمليات إعادة التوجيه".

التكوين الاختياري

تعد بعض متغيرات البيئة اختيارية ويمكن استخدامها لتصحيح أخطاء إعدادات ملفات تعريف الارتباط أو تكوينها.

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 لمشاركة جلسات WorkOS بين التطبيقات/المجالات. ملاحظة: يجب أن تكون WORKOS_COOKIE_PASSWORD هي نفسها عبر التطبيقات/المجالات. ليست هناك حاجة لمعظم حالات الاستخدام.

يثبت

طريق رد الاتصال

يتطلب WorkOS أن يكون لديك عنوان URL لرد الاتصال لإعادة توجيه المستخدمين إليه بعد المصادقة عليهم. في تطبيق Next.js، اكشف عن مسار واجهة برمجة التطبيقات وأضف ما يلي.

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

export const GET = handleAuth ( ) ;

تأكد من أن هذا المسار يطابق المتغير WORKOS_REDIRECT_URI وURI لإعادة التوجيه الذي تم تكوينه في لوحة معلومات WorkOS الخاصة بك. على سبيل المثال، إذا كان URI الخاص بإعادة التوجيه هو http://localhost:3000/auth/callback ، فيمكنك وضع الكود أعلاه في /app/auth/callback/route.ts .

يمكنك أيضًا التحكم في اسم المسار الذي سيتم إرسال المستخدم إليه بعد تسجيل الدخول عن طريق تمرير خيار returnPathname إلى handleAuth كما يلي:

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

يمكن استخدام handleAuth مع عدة خيارات.

خيار	تقصير	وصف
returnPathname	/	اسم المسار الذي سيتم إعادة توجيه المستخدم إليه بعد تسجيل الدخول
baseURL	undefined	عنوان URL الأساسي المطلوب استخدامه لعنوان URI لإعادة التوجيه بدلاً من العنوان الموجود في الطلب. يكون هذا مفيدًا إذا كان التطبيق قيد التشغيل في حاوية مثل عامل الإرساء حيث يمكن أن يكون اسم المضيف مختلفًا عن الاسم الموجود في الطلب

الوسيطة

تعتمد هذه المكتبة على البرنامج الوسيط Next.js لتوفير إدارة الجلسة للمسارات. ضع ما يلي في ملف middleware.ts الخاص بك في جذر مشروعك:

 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' ] } ;

يمكن تكوين البرنامج الوسيط بعدة خيارات.

خيار	تقصير	وصف
redirectUri	undefined	يُستخدم في الحالات التي تحتاج فيها إلى تعيين URI الخاص بإعادة التوجيه ديناميكيًا (على سبيل المثال، عمليات نشر معاينة Vercel)
middlewareAuth	undefined	يُستخدم لتكوين خيارات مصادقة البرامج الوسيطة. راجع مصادقة البرامج الوسيطة لمزيد من التفاصيل.
debug	false	تمكين سجلات التصحيح.
signUpPaths	[]	يُستخدم لتحديد المسارات التي يجب أن تستخدم تلميح شاشة "التسجيل" عند إعادة التوجيه إلى AuthKit.

URI لإعادة التوجيه المخصص

في الحالات التي تحتاج فيها إلى تعيين URI الخاص بإعادة التوجيه ديناميكيًا (على سبيل المثال، عمليات نشر معاينة Vercel)، استخدم خيار redirectUri في 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 المخصصة لإعادة التوجيه عبر معرف URI لإعادة التوجيه الذي تم تكوينه في متغيرات البيئة.

الاستخدام

لف تطبيقك في AuthKitProvider

استخدم AuthKitProvider لتغليف تخطيط التطبيق الخاص بك، مما يضيف بعض الحماية لحالات المصادقة الطرفية.

 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 >
  ) ;
}

احصل على المستخدم الحالي

بالنسبة للصفحات التي تريد عرض طريقة عرض تسجيل الدخول وتسجيل الخروج منها، استخدم withAuth لاسترداد ملف تعريف المستخدم من 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 >
  ) ;
}

تتطلب المصادقة

بالنسبة للصفحات التي يكون فيها تسجيل دخول المستخدم إلزاميًا، يمكنك استخدام خيار ensureSignedIn :

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

سيؤدي تمكين ensureSignedIn إلى إعادة توجيه المستخدمين إلى AuthKit إذا حاولوا الوصول إلى الصفحة دون أن تتم مصادقتهم.

مصادقة الوسيطة

السلوك الافتراضي لهذه المكتبة هو طلب المصادقة عبر طريقة withAuth على أساس كل صفحة. هناك بعض حالات الاستخدام التي لا تريد فيها الاتصال withAuth (على سبيل المثال، لا تحتاج إلى بيانات المستخدم لصفحتك) أو إذا كنت تفضل أسلوب "آمن افتراضيًا" حيث يكون كل مسار محدد في أداة مطابقة البرامج الوسيطة الخاصة بك محميًا ما لم ينص على خلاف ذلك. في هذه الحالات، يمكنك الاشتراك في استخدام مصادقة البرامج الوسيطة بدلاً من ذلك:

 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' ] } ;

في المثال أعلاه، ستتطلب صفحة /admin من المستخدم تسجيل الدخول، بينما يمكن الوصول إلى / و /about دون تسجيل الدخول.

يستخدم unauthenticatedPaths نفس المنطق الشامل مثل مُطابق Next.js.

استرداد الجلسة في البرامج الوسيطة

في بعض الأحيان يكون من المفيد التحقق من جلسة المستخدم إذا كنت تريد إنشاء برامج وسيطة مخصصة. ستقوم طريقة المساعد getSession باسترداد الجلسة من ملف تعريف الارتباط والتحقق من رمز الوصول.

 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*' ] } ;

تسجيل الخروج

استخدم طريقة signOut لتسجيل خروج المستخدم الحالي الذي قام بتسجيل الدخول وإعادة التوجيه إلى الصفحة الرئيسية لتطبيقك. يتم تعيين إعادة توجيه الصفحة الرئيسية في إعدادات لوحة معلومات WorkOS ضمن "إعادة التوجيه".

تصور انتحال شخصية

اعرض مكون Impersonation في تطبيقك بحيث يكون واضحًا عندما ينتحل شخص ما شخصية مستخدم. سيعرض المكون إطارًا يحتوي على بعض المعلومات حول المستخدم الذي تم انتحاله، بالإضافة إلى زر لإيقاف الانتحال.

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

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

احصل على رمز الوصول

في بعض الأحيان يكون من المفيد الحصول على رمز الوصول مباشرةً، على سبيل المثال، لتقديم طلبات API إلى خدمة أخرى.

 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 > ;
}

تحديث الجلسة

استخدم أسلوب refreshSession في إجراء الخادم أو معالج المسار لجلب أحدث تفاصيل الجلسة، بما في ذلك أي تغييرات على أدوار المستخدم أو أذوناته.

يمكن تمرير معلمة organizationId إلى refreshSession لتبديل الجلسة إلى مؤسسة مختلفة. إذا لم يتم ترخيص الجلسة الحالية للمؤسسة التالية، فسيتم إرجاع خطأ مصادقة مناسب.

مسارات التسجيل

يمكن تمرير خيار signUpPaths إلى authkitMiddleware لتحديد المسارات التي يجب أن تستخدم تلميح شاشة "التسجيل" عند إعادة التوجيه إلى AuthKit. يعد هذا مفيدًا في الحالات التي تريد فيها التعامل مع المسار الذي يتطلب المصادقة كصفحة تسجيل.

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

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

تصحيح الأخطاء

لتمكين سجلات التصحيح، قم بتهيئة البرنامج الوسيط مع تمكين علامة التصحيح.

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

export default authkitMiddleware ( { debug : true } ) ;

استكشاف الأخطاء وإصلاحها

خطأ NEXT_REDIRECT عند استخدام كتل المحاولة/الالتقاط

سيؤدي التفاف استدعاء withAuth({ ensureSignedIn: true }) في كتلة محاولة/التقاط إلى حدوث خطأ NEXT_REDIRECT . وذلك لأن withAuth سيحاول إعادة توجيه المستخدم إلى AuthKit إذا لم يتم اكتشاف أي جلسة ويجب استدعاء عمليات إعادة التوجيه في التالي خارج محاولة/التقاط.