كيفية تنفيذ Google OAuth 2.0 في Next.js 15 باستخدام NextAuth: أكمل البرنامج التعليمي لعام 2026

يعد OAuth 2.0 with Google أسرع طريقة لإضافة المصادقة إلى تطبيق Next.js – حيث يقوم المستخدمون بتسجيل الدخول باستخدام حساب Google الخاص بهم، مما يلغي إدارة كلمات المرور ويقلل الاحتكاك. في عام 2026،NextAuth v5 (Auth.js) يوفر التكامل الأنظف لجهاز توجيه التطبيقات Next.js 15. يغطي هذا البرنامج التعليمي التنفيذ الكامل.

المتطلبات

• مشروع Next.js 15 (جهاز توجيه التطبيقات)
• حساب جوجل كلاود كونسول (مجاني)
• قاعدة بيانات PostgreSQL (اختيارية، للجلسات المستمرة)

الخطوة 1: إعداد بيانات اعتماد Google OAuth

1. اذهب إلىconsole.cloud.google.com
2. أنشئ مشروعًا جديدًا (أو اختر مشروعًا موجودًا)
3. انتقل إلىواجهات برمجة التطبيقات والخدمات → بيانات الاعتماد → إنشاء بيانات الاعتماد → معرف عميل OAuth
4. نوع التطبيق :تطبيق ويب
5. عناوين URL لإعادة التوجيه المعتمدة:http://localhost:3000/api/auth/callback/google
6. أضف معرف URI للإنتاج عند النشر:https://yourdomain.com/api/auth/callback/google
7. احفظ وانسخمعرف العميل وسر العميل

الخطوة 2: تثبيت NextAuth v5

npm install next-auth@beta
# or
pnpm add next-auth@beta

الخطوة 3: تكوين Auth.js

إنشاءauth.ts في جذر مشروعك:

import NextAuth from "next-auth";
import Google from "next-auth/providers/google";

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    Google({
      clientId:     process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
  ],
  callbacks: {
    async session({ session, token }) {
      // Add user ID to session
      if (token.sub) {
        session.user.id = token.sub;
      }
      return session;
    },
    async jwt({ token, account, profile }) {
      if (account) {
        token.accessToken = account.access_token;
      }
      return token;
    },
  },
  pages: {
    signIn: "/login",    // custom sign-in page
    error:  "/auth/error",
  },
});

الخطوة 4: إنشاء معالج المسار

إنشاءapp/api/auth/[...nextauth]/route.ts:

import { handlers } from "@/auth";
export const { GET, POST } = handlers;

الخطوة 5: متغيرات البيئة

# .env.local
GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here
AUTH_SECRET=generate_with_openssl_rand_base64_32

# Generate AUTH_SECRET:
# openssl rand -base64 32

الخطوة 6: إضافة تسجيل الدخول/الخروج إلى واجهة المستخدم

// components/AuthButtons.tsx
import { signIn, signOut } from "@/auth";

export function SignInButton() {
  return (
    <form action={async () => {
      "use server";
      await signIn("google");
    }}>
      <button type="submit">Sign in with Google</button>
    </form>
  );
}

export function SignOutButton() {
  return (
    <form action={async () => {
      "use server";
      await signOut({ redirectTo: "/" });
    }}>
      <button type="submit">Sign out</button>
    </form>
  );
}

الخطوة 7: الوصول إلى الجلسة في مكونات الخادم

// app/dashboard/page.tsx
import { auth } from "@/auth";
import { redirect } from "next/navigation";

export default async function Dashboard() {
  const session = await auth();

  if (!session?.user) {
    redirect("/login");
  }

  return (
    <main>
      <h1>Welcome, {session.user.name}!</h1>
      <img src={session.user.image!} alt="avatar" width={40} height={40} />
      <p>Email: {session.user.email}</p>
    </main>
  );
}

الخطوة 8: حماية المسارات باستخدام البرامج الوسيطة

// middleware.ts
import { auth } from "@/auth";
import { NextResponse } from "next/server";

export default auth((req) => {
  const isLoggedIn = !!req.auth;
  const isProtected = req.nextUrl.pathname.startsWith("/dashboard");

  if (isProtected && !isLoggedIn) {
    const loginUrl = new URL("/login", req.url);
    loginUrl.searchParams.set("callbackUrl", req.nextUrl.href);
    return NextResponse.redirect(loginUrl);
  }
  return NextResponse.next();
});

export const config = {
  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
};

الخطوة 9: تكامل قاعدة البيانات (اختياري لكن موصى به)

npm install @auth/prisma-adapter @prisma/client prisma

// auth.ts with database adapter
import { PrismaAdapter } from "@auth/prisma-adapter";
import { db } from "@/lib/db";  // your Prisma client

export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(db),
  session: { strategy: "database" },  // store sessions in DB
  providers: [Google(...)],
});

تسمح جلسات قاعدة البيانات بإبطال الجلسات من جانب الخادم (مفيدة لحظر المستخدمين أو تسجيل الخروج القسري) واستمرار تسجيل الدخول عبر عمليات إعادة تشغيل الخادم – غير ممكن مع جلسات JWT فقط.

الخطوة 10: الوصول إلى الجلسة في مكونات العميل

// Wrap your app with SessionProvider in layout.tsx
// app/layout.tsx
import { SessionProvider } from "next-auth/react";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <SessionProvider>{children}</SessionProvider>
      </body>
    </html>
  );
}

// Client component using session
"use client";
import { useSession } from "next-auth/react";

export function UserAvatar() {
  const { data: session, status } = useSession();

  if (status === "loading") return <Skeleton />;
  if (!session) return <SignInButton />;

  return <img src={session.user.image!} alt={session.user.name!} />;
}

الأسئلة المتداولة

س: جلسات JWT مقابل جلسات قاعدة البيانات – ما الذي يجب أن أستخدمه؟
ج: JWT للتطبيقات البسيطة التي لا تحتاج فيها إلى إبطال الجلسة من جانب الخادم. قاعدة بيانات للتطبيقات التي تحتاج فيها إلى إلغاء الجلسات، أو تدقيق تسجيلات الدخول، أو تخزين تفضيلات المستخدم المرتبطة بالجلسات.

س: كيف يمكنني إضافة المزيد من موفري OAuth؟
ج: قم بالاستيراد والإضافة إلى مجموعة الموفرين:import GitHub from "next-auth/providers/github". يدعم NextAuth أكثر من 70 موفرًا بنفس النمط.

س: كيف يمكنني تقييد تسجيل الدخول على نطاقات بريد إلكتروني معينة؟
ج: استخدمsignIn رد الاتصال:async signIn({ user }) { return user.email?.endsWith("@company.com") ?? false; }

س: هل Auth.js (NextAuth v5) جاهز للإنتاج؟
ج: اعتبارًا من عام 2026، نعم – ظل الإصدار التجريبي مستقرًا لعدة أشهر ويستخدم على نطاق واسع في الإنتاج. واجهة برمجة التطبيقات (API) مستقرة ويوصى بها للمشاريع الجديدة.

س: كيف يمكنني الوصول إلى رمز وصول Google لاستدعاءات واجهة برمجة التطبيقات (API)؟
ج: قم بتخزينه في رد اتصال JWT (token.accessToken = account.access_token) وعرضه في رد اتصال الجلسة. الوصول عبرsession.accessToken.

الخلاصة

يمنحك NextAuth v5 + Google OAuth مصادقة جاهزة للإنتاج في Next.js 15 مع حوالي 50 سطرًا من التعليمات البرمجية. يغطي نمط معالج المسار وتسجيل الدخول/الخروج لإجراء الخادم وحماية البرامج الوسيطة ومحول قاعدة البيانات الاختياري كل متطلبات المصادقة في العالم الحقيقي. أضف GitHub، أو Discord، أو البريد الإلكتروني/كلمة المرور إلى جانب Google باستخدام نفس النمط – يتعامل NextAuth مع التعقيد حتى لا تضطر إلى القيام بذلك.