NextAuth.js ile Next.js Uygulamalarında Kimlik Doğrulama Rehberi
Modern web uygulamalarında kimlik doğrulama, kullanıcı deneyimini güvenli ve kesintisiz hale getirmek için kritik bir öneme sahiptir. Next.js, hızlı ve ölçeklenebilir uygulamalar geliştirmek için popüler bir framework iken, NextAuth.js (yeni adıyla Auth.js), bu platformda kimlik doğrulama süreçlerini kolaylaştıran güçlü ve esnek bir kütüphanedir.
Bu makalemde, NextAuth.js'nin temel özelliklerini, Next.js projelerine entegrasyonunu ve en iyi uygulamaları ele alacağım.
NextAuth.js Nedir?
NextAuth.js, Next.js uygulamaları için tasarlanmış açık kaynaklı bir kimlik doğrulama kütüphanesidir. OAuth, OpenID Connect, e-posta tabanlı parola gerektirmeyen oturum açma gibi çok çeşitli kimlik doğrulama yöntemlerini destekler.
Ayrıca, veritabanı kullanımı opsiyonel olup, JSON Web Token (JWT) ile stateless kimlik doğrulama veya MySQL, PostgreSQL, MongoDB gibi veritabanlarıyla kalıcı oturum yönetimi sağlar. NextAuth.js, hem sunucu tarafında hem de istemci tarafında kolayca kullanılabilen esnek bir yapı sunar.
Temel Özellikler
-
Çoklu Sağlayıcı Desteği: Google, GitHub, Apple, Facebook gibi popüler OAuth sağlayıcılarıyla entegrasyon.
-
Parolasız Oturum Açma: E-posta ile sihirli bağlantılar (magic links) veya SMS tabanlı doğrulama.
-
Veritabanı Esnekliği: SQLite, PostgreSQL, MongoDB gibi veritabanlarıyla çalışabilir veya tamamen veritabanı olmadan JWT kullanabilir.
-
TypeScript Desteği: Dahili TypeScript tür tanımlarıyla geliştirici dostu bir deneyim.
-
Next.js ile Uyumluluk: Hem Pages Router hem de App Router ile sorunsuz çalışır.
-
Edge Uyumluluğu: Vercel Edge Functions gibi modern ortamlarla uyumlu.
NextAuth.js Kurulumu
NextAuth.js'yi bir Next.js projesine entegre etmek oldukça basittir. Aşağıda, adım adım kurulum sürecini açıklayalım.
1. Proje Kurulumu
Öncelikle bir Next.js projeniz olmalı. Eğer yoksa, aşağıdaki komutla yeni bir proje oluşturabilirsiniz:
npx create-next-app@latest my-auth-app
cd my-auth-app
2. NextAuth.js Kurulumu
NextAuth.js'yi projenize eklemek için aşağıdaki komutu çalıştırın:
npm install next-auth
3. Ortam Değişkenlerini Ayarlama
Projenizin kök dizininde bir .env.local dosyası oluşturun ve gerekli ortam değişkenlerini ekleyin:
NEXTAUTH_URL=http://localhost:3000
AUTH_SECRET=your-secret-key
AUTH_SECRET, oturumları şifrelemek için kullanılan bir anahtardır. Güvenli bir rastgele dize oluşturmak için şu komutu kullanabilirsiniz:
openssl rand -base64 32
4. Kimlik Doğrulama Yapılandırması
Next.js projenizde, kimlik doğrulama ayarlarını tanımlamak için bir rota oluşturmanız gerekir. App Router kullanıyorsanız, app/auth/[...auth]/route.ts dosyasını oluşturun:
import NextAuth from "next-auth";
import GoogleProvider from "next-auth/providers/google";
export const authOptions = {
providers: [
GoogleProvider({
clientId: process.env.GOOGLE_CLIENT_ID!,
clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
}),
],
secret: process.env.AUTH_SECRET,
};
const handler = NextAuth(authOptions);
export { handler as GET, handler as POST };
Bu kod, Google ile kimlik doğrulama sağlayıcısını yapılandırır. Google Cloud Console'dan GOOGLE_CLIENT_ID ve GOOGLE_CLIENT_SECRET değerlerini almanız gerekir.
5. SessionProvider ile Oturum Yönetimi
İstemci tarafında oturum verilerine erişmek için, uygulamanızın kök bileşeninde SessionProvider'ı kullanmalısınız. App Router kullanıyorsanız, app/layout.tsx dosyasını şu şekilde güncelleyin:
import { SessionProvider } from "next-auth/react";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<SessionProvider>{children}</SessionProvider>
</body>
</html>
);
}
6. İstemci (Client) Tarafında Oturum Kontrolü
İstemci tarafında oturum durumunu kontrol etmek için useSession kancasını kullanabilirsiniz:
import { useSession, signIn, signOut } from "next-auth/react";
export default function Home() {
const { data: session } = useSession();
if (session) {
return (
<div>
Merhaba, {session.user?.name}! <br />
<button onClick={() => signOut()}>Çıkış Yap</button>
</div>
);
}
return (
<div>
Oturum açılmadı. <br />
<button onClick={() => signIn("google")}>Google ile Giriş Yap</button>
</div>
);
}
7. Sunucu (Server) Tarafında Oturum Kontrolü
Sunucu tarafında oturum verilerine erişmek için getServerSession fonksiyonunu kullanabilirsiniz:
import { getServerSession } from "next-auth";
import { authOptions } from "@/app/auth/[...auth]/route";
export default async function Profile() {
const session = await getServerSession(authOptions);
if (!session) {
return <div>Lütfen oturum açın.</div>;
}
return <div>Hoş geldiniz, {session.user?.name}!</div>;
}
NextAuth.js ile İleri Seviye Özellikler
1. Özel Sağlayıcılar
NextAuth.js, özel OAuth sağlayıcılarını destekler. Örneğin, kendi OAuth sağlayıcınızı şu şekilde tanımlayabilirsiniz:
providers: [
{
id: "custom-provider",
name: "Custom Provider",
type: "oauth",
authorization: { url: "https://custom-provider.com/oauth/authorize", params: { scope: "read" } },
token: "https://custom-provider.com/oauth/token",
userinfo: "https://custom-provider.com/api/user",
clientId: process.env.CUSTOM_CLIENT_ID,
clientSecret: process.env.CUSTOM_CLIENT_SECRET,
profile(profile) {
return {
id: profile.id,
name: profile.name,
email: profile.email,
};
},
},
],
2. Veritabanı Entegrasyonu
NextAuth.js, oturumları ve kullanıcı verilerini saklamak için çeşitli veritabanı adaptörlerini destekler. Örneğin, Prisma ile entegrasyon için @auth/prisma-adapter paketini kullanabilirsiniz:
npm install @auth/prisma-adapter
Ardından, authOptions nesnesine adaptörü ekleyin:
import { PrismaAdapter } from "@auth/prisma-adapter";
import { PrismaClient } from "@prisma/client";
const prisma = new PrismaClient();
export const authOptions = {
adapter: PrismaAdapter(prisma),
providers: [
GoogleProvider({
clientId: process.env.GOOGLE_CLIENT_ID!,
clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
}),
],
secret: process.env.AUTH_SECRET,
};
3. Middleware ile Korumalı Rotalar
Next.js Middleware ile belirli rotaları korumak için next-auth/middleware kullanabilirsiniz:
import { withAuth } from "next-auth/middleware";
export default withAuth({
callbacks: {
authorized: ({ req, token }) => {
if (req.nextUrl.pathname.startsWith("/dashboard")) {
return !!token;
}
return true;
},
},
});
export const config = {
matcher: ["/dashboard/:path*"],
};
Bu kod, /dashboard rotasına yalnızca oturum açmış kullanıcıların erişmesini sağlar.
NextAuth.js'nin Avantajları ve Dezavantajları
Avantajlar
-
Kolay Entegrasyon: Next.js ile doğal uyumluluk sayesinde hızlı kurulum.
-
Esneklik: Çoklu sağlayıcılar ve veritabanı seçenekleriyle genişletilebilir.
-
Güvenlik: JWT ve güvenli oturum yönetimi ile yüksek güvenlik standartları.
-
Açık Kaynak: Topluluk katkılarıyla sürekli gelişen bir kütüphane.
Dezavantajlar
-
Dökümantasyon Eksiklikleri: Özellikle v5 geçişinde, yeni özelliklerin dökümantasyonu henüz tamamlanmamış olabilir.
-
Öğrenme Eğrisi: Özelleştirilmiş yapılandırmalar için OAuth protokolüne aşinalık gerekebilir.
Sonuç
NextAuth.js, Next.js uygulamaları için güçlü, esnek ve güvenli bir kimlik doğrulama çözümü sunar. Hem basit hem de karmaşık kimlik doğrulama ihtiyaçlarını karşılayabilen bu kütüphane, modern web geliştirme süreçlerinde önemli bir yer edinmiştir. Google, GitHub gibi popüler sağlayıcılarla hızlı entegrasyon, parolasız oturum açma seçenekleri ve veritabanı esnekliği ile NextAuth.js, geliştiricilere zaman kazandırır ve kullanıcı deneyimini iyileştirir.
Eğer bir Next.js projeniz varsa ve güvenli bir kimlik doğrulama sistemi kurmak istiyorsanız, NextAuth.js ile başlamanızı öneririm. Daha fazla bilgi için authjs.dev adresini ziyaret edebilir veya GitHub reposunu inceleyebilirsiniz.