NextAuth.js ve OAuth 2.0 ile Modern Kimlik Doğrulama Rehberi

Web uygulamalarında kullanıcı deneyimini bozmadan yüksek güvenlik sağlamak günümüz yazılım dünyasının en kritik gereksinimlerinden biridir. Bu noktada NextAuth.js ve OAuth 2.0 ile modern kimlik doğrulama çözümleri, Next.js ekosisteminde standart bir yaklaşım haline gelmiştir. Geleneksel kullanıcı adı ve parola ikilisinin yarattığı güvenlik riskleri ile operasyonel yükler, geliştiricileri Google, GitHub ve Microsoft gibi güvenilir sağlayıcıların sunduğu OAuth 2.0 tabanlı oturum açma sistemlerine yönlendirmektedir.

Bu rehberde, Next.js (App Router) mimarisi üzerinde Auth.js (NextAuth.js) kütüphanesini kullanarak tam teşekküllü, üretkenlik odaklı ve güvenli bir kimlik doğrulama altyapısının nasıl kurulacağını adım adım inceleyeceğiz. Teorik kavramlardan pratik kod örneklerine, veritabanı entegrasyonundan güvenlik ipuçlarına kadar tüm süreçleri bulabilirsiniz. Temel güvenlik konseptleri hakkında detaylı bilgi edinmek için daha önce hazırladığımız OAuth 2.0 ve JWT rehberimizden yararlanabilirsiniz.

OAuth 2.0 Mantığı ve NextAuth.js Mimari Yapısı

OAuth 2.0, bir uygulamanın (Client), kullanıcının (Resource Owner) şifresini öğrenmeden üçüncü taraf bir servis (Authorization Server) üzerindeki kaynaklarına erişmesini sağlayan yetkilendirme standardıdır. Modern web mimarilerinde OAuth 2.0 çoğunlukla OpenID Connect (OIDC) katmanı ile birleştirilerek kimlik doğrulama (Authentication) amacıyla kullanılır.

NextAuth.js, Next.js projeleri için özel olarak tasarlanmış, esnek ve açık kaynaklı bir kimlik doğrulama kütüphanesidir. Arka planda şu süreçleri otomatik yönetir:

• Authorization Code Flow: Kullanıcıyı yetkilendirme sunucusuna yönlendirir, geri dönen geçici code değerini sunucu tarafında güvenli bir şekilde access_token ile takas eder.
• Oturum Yönetimi: JWT (JSON Web Token) veya veritabanı tabanlı (Database Session) oturum stratejilerini destekler.
• Güvenli Çerez (Cookie) Politikaları: HTTPOnly, SameSite ve Secure bayrakları aktif edilmiş çerezler üreterek XSS ve CSRF saldırılarına karşı koruma sağlar.

Adım Adım NextAuth.js Kurulumu ve Yapılandırması

Next.js App Router projenize NextAuth.js eklemek için öncelikle gerekli bağımlılıkları projenize dahil etmeniz gerekir. Komut satırında şu komutu çalıştırarak başlayın:

npm install next-auth@beta

Not: NextAuth.js v5 sürümüyle birlikte paket next-auth olarak güncellenmiş ve App Router mimarisiyle tam uyumlu hale getirilmiştir.

1. Çevre Değişkenlerinin Hazırlanması

Güvenlik anahtarını ve OAuth sağlayıcılarından aldığınız istemci bilgilerini .env.local dosyasında saklamalısınız:

NEXTAUTH_SECRET="super-gizli-rastgele-32-karakterli-anahtar-string"
NEXTAUTH_URL="http://localhost:3000"

GITHUB_CLIENT_ID="github_dan_alınan_client_id"
GITHUB_CLIENT_SECRET="github_dan_alınan_client_secret"

GOOGLE_CLIENT_ID="google_cloud_client_id"
GOOGLE_CLIENT_SECRET="google_cloud_client_secret"

NEXTAUTH_SECRET üretmek için terminalinizde openssl rand -base64 32 komutunu çalıştırabilirsiniz.

2. Yapılandırma Dosyasının Oluşturulması

Projenizin kök dizininde veya src/ klasörü altında auth.ts adında bir dosya oluşturun ve sağlayıcıları tanımlayın:

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

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    GitHub({
      clientId: process.env.GITHUB_CLIENT_ID,
      clientSecret: process.env.GITHUB_CLIENT_SECRET,
    }),
    Google({
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    }),
  ],
  pages: {
    signIn: "/login",
  },
  callbacks: {
    async session({ session, token }) {
      if (token.sub && session.user) {
        session.user.id = token.sub;
      }
      return session;
    },
  },
});

3. API Rotasının Tanımlanması

App Router yapısında tüm NextAuth isteklerini karşılayacak dinamik API rotasını oluşturun. app/api/auth/[...nextauth]/route.ts dosyasını oluşturup içerisine şu satırları ekleyin:

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

NextAuth.js ve OAuth 2.0 ile Modern Kimlik Doğrulama Uygulaması

Kurulum tamamlandıktan sonra uygulama içerisinde hem Server hem de Client bileşenlerinde oturum durumunu nasıl yöneteceğimizi inceleyelim.

Server Components Üzerinde Oturum Kontrolü

Next.js App Router mimarisinde sunucu taraflı bileşenlerde kullanıcı durumunu sorgulamak oldukça hızlı ve güvenlidir. Veritabanı sorgusu yapmadan önce auth() fonksiyonunu çağırmak yeterlidir:

import { auth } from "@/auth";
import { redirect } from "next-navigation";

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

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

  return (
    <main className="p-8">
      <h1 className="text-2xl font-bold">Hoş Geldin, {session.user.name}</h1>
      <p>E-posta: {session.user.email}</p>
    </main>
  );
}

Client Components ve SessionProvider Kullanımı

İstemci tarafında oturum bilgisini anlık olarak dinlemek ve buton etkileşimlerini yönetmek için kütüphanenin sunduğu hook'lardan faydalanabilirsiniz. Öncelikli olarak SessionProvider bileşenini layout yapınıza ekleyin:

// components/providers.tsx
"use client";

import { SessionProvider } from "next-auth/react";

export function Providers({ children }: { children: React.ReactNode }) {
  return <SessionProvider>{children}</SessionProvider>;
}

İstemci bileşeninde giriş ve çıkış butonlarının kullanımı:

// components/AuthButton.tsx
"use client";

import { useSession, signIn, signOut } from "next-auth/react";

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

  if (status === "loading") return <p>Yükleniyor...</p>;

  if (session) {
    return (
      <div className="flex gap-4 items-center">
        <span>{session.user?.name}</span>
        <button 
          onClick={() => signOut()}
          className="bg-red-500 text-white px-4 py-2 rounded"
        >
          Çıkış Yap
        </button>
      </div>
    );
  }

  return (
    <button 
      onClick={() => signIn("github")}
      className="bg-black text-white px-4 py-2 rounded"
    >
      GitHub ile Giriş Yap
    </button>
  );
}

Veritabanı Entegrasyonu (Prisma Adapter)

OAuth ile giriş yapan kullanıcıların bilgilerini, rol tanımlarını veya sipariş geçmişlerini saklamak istiyorsanız bir ORM ve Adapter kullanmanız gerekir. Prisma ORM entegrasyonu en yaygın çözümdür.

Gerekli paketleri yükleyin:

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

schema.prisma dosyanıza NextAuth modellerini ekleyin:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

model Account {
  id                String  @id @default(cuid())
  userId            String
  type              String
  provider          String
  providerAccountId String
  refresh_token     String? @db.Text
  access_token      String? @db.Text
  expires_at        Int?
  token_type        String?
  scope             String?
  id_token          String? @db.Text
  session_state     String?

  user User @relation(fields: [userId], references: [id], onDelete: Cascade)

  @@unique([provider, providerAccountId])
}

model Session {
  id           String   @id @default(cuid())
  sessionToken String   @unique
  userId       String
  expires      DateTime
  user         User     @relation(fields: [userId], references: [id], onDelete: Cascade)
}

model User {
  id            String    @id @default(cuid())
  name          String?
  email         String?   @unique
  emailVerified DateTime?
  image         String?
  accounts      Account[]
  sessions      Session[]
  role          String    @default("user")
}

auth.ts dosyanıza Prisma Adapter'ı ekleyin:

import NextAuth from "next-auth";
import { PrismaAdapter } from "@auth/prisma-adapter";
import { PrismaClient } from "@prisma/client";
import GitHub from "next-auth/providers/github";

const prisma = new PrismaClient();

export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma),
  providers: [GitHub],
  session: { strategy: "database" },
});

Güvenlik En İyi Uygulamaları ve Sık Yapılan Hatalar

Modern kimlik doğrulama sistemlerinde tek bir güvenlik açığı tüm uygulamanızı riske atabilir. Üretim ortamına geçmeden önce dikkat etmeniz gerekenler:

// middleware.ts
export { auth as middleware } from "@/auth";

export const config = = {
  matcher: ["/dashboard/:path*", "/admin/:path*"],
};

Sonuç

NextAuth.js ve OAuth 2.0 ile modern kimlik doğrulama altyapısı kurmak, uygulamanızın güvenliğini artırırken kullanıcıların kayıt ve giriş süreçlerindeki sürtünmeyi en aza indirir. Bu rehberde App Router uyumlu Auth.js kurulumunu, istemci ve sunucu tarafı oturum kontrolünü, Prisma ORM entegrasyonunu ve kritik güvenlik kriterlerini ele aldık.

Sonraki Adım: Projenize derhal Google veya GitHub sağlayıcılarından birini entegre edin, ardından role dayalı erişim kontrolü (RBAC) mekanizması ekleyerek /admin rotalarınızı koruma altına alın.