331 lines
10 KiB
Markdown
331 lines
10 KiB
Markdown
# Clerk Kimlik Doğrulama Kurulum Rehberi
|
||
|
||
## 📋 Genel Bakış
|
||
|
||
LetsGoCappadocia uygulaması, kullanıcı kimlik doğrulama için Clerk.com kullanmaktadır. Bu rehber, Clerk API anahtarlarını nasıl alacağınızı ve yapılandıracağınızı adım adım açıklar.
|
||
|
||
---
|
||
|
||
## 🔑 Gerekli API Anahtarları
|
||
|
||
### 1. **VITE_CLERK_PUBLISHABLE_KEY** (Frontend)
|
||
- **Açıklama:** Frontend uygulamasında kullanıcı kimlik doğrulama için gerekli
|
||
- **Format:** `pk_test_...` veya `pk_live_...` ile başlar
|
||
- **Kullanım Yeri:** React uygulaması (.env dosyası)
|
||
- **Güvenlik:** Public key - tarayıcıda görünür olabilir
|
||
|
||
### 2. **CLERK_SECRET_KEY** (Backend)
|
||
- **Açıklama:** Backend webhook doğrulama ve admin işlemleri için gerekli
|
||
- **Format:** `sk_test_...` veya `sk_live_...` ile başlar
|
||
- **Kullanım Yeri:** Supabase Edge Functions
|
||
- **Güvenlik:** ⚠️ GİZLİ - Asla frontend'de kullanmayın!
|
||
|
||
### 3. **CLERK_WEBHOOK_SECRET** (Webhook)
|
||
- **Açıklama:** Clerk webhook'larını doğrulamak için gerekli
|
||
- **Format:** `whsec_...` ile başlar
|
||
- **Kullanım Yeri:** Supabase Edge Functions (clerk-webhook)
|
||
- **Güvenlik:** ⚠️ GİZLİ - Webhook güvenliği için kritik
|
||
|
||
---
|
||
|
||
## 📝 Adım Adım Kurulum
|
||
|
||
### Adım 1: Clerk Hesabı Oluşturma
|
||
|
||
1. **Clerk.com'a gidin:** https://clerk.com/
|
||
2. **Sign Up** butonuna tıklayın
|
||
3. E-posta adresinizle kayıt olun
|
||
4. E-posta doğrulamasını tamamlayın
|
||
|
||
### Adım 2: Yeni Uygulama Oluşturma
|
||
|
||
1. Clerk Dashboard'a giriş yapın
|
||
2. **"Create Application"** butonuna tıklayın
|
||
3. Uygulama adını girin: `LetsGoCappadocia`
|
||
4. Kimlik doğrulama yöntemlerini seçin:
|
||
- ✅ Email
|
||
- ✅ Google (opsiyonel)
|
||
- ✅ Phone (opsiyonel)
|
||
5. **Create Application** butonuna tıklayın
|
||
|
||
### Adım 3: API Anahtarlarını Alma
|
||
|
||
#### 3.1 Publishable Key ve Secret Key
|
||
|
||
1. Clerk Dashboard'da sol menüden **"API Keys"** seçeneğine tıklayın
|
||
2. **Publishable Key** bölümünü bulun:
|
||
- `pk_test_...` ile başlayan anahtarı kopyalayın
|
||
- Bu anahtarı `VITE_CLERK_PUBLISHABLE_KEY` olarak kaydedin
|
||
|
||
3. **Secret Keys** bölümünü bulun:
|
||
- `sk_test_...` ile başlayan anahtarı kopyalayın
|
||
- ⚠️ **"Show"** butonuna tıklayarak anahtarı görünür hale getirin
|
||
- Bu anahtarı `CLERK_SECRET_KEY` olarak kaydedin
|
||
|
||
#### 3.2 Webhook Secret
|
||
|
||
1. Clerk Dashboard'da sol menüden **"Webhooks"** seçeneğine tıklayın
|
||
2. **"Add Endpoint"** butonuna tıklayın
|
||
3. Webhook URL'ini girin:
|
||
```
|
||
https://vtztatcglebrnvikvntf.supabase.co/functions/v1/clerk-webhook
|
||
```
|
||
4. **Events** bölümünde şu olayları seçin:
|
||
- ✅ `user.created`
|
||
- ✅ `user.updated`
|
||
- ✅ `user.deleted`
|
||
5. **Create** butonuna tıklayın
|
||
6. Oluşturulan webhook'un detay sayfasında **"Signing Secret"** bölümünü bulun
|
||
7. `whsec_...` ile başlayan anahtarı kopyalayın
|
||
8. Bu anahtarı `CLERK_WEBHOOK_SECRET` olarak kaydedin
|
||
|
||
---
|
||
|
||
## 🔧 Anahtarları Yapılandırma
|
||
|
||
### Yöntem 1: .env Dosyası (Önerilen - Development)
|
||
|
||
1. Proje kök dizinindeki `.env` dosyasını açın
|
||
2. Aşağıdaki satırları ekleyin:
|
||
|
||
```bash
|
||
# Clerk Authentication
|
||
VITE_CLERK_PUBLISHABLE_KEY=pk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
||
```
|
||
|
||
3. Dosyayı kaydedin
|
||
4. Development server'ı yeniden başlatın:
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
### Yöntem 2: Admin Panel (Önerilen - Production)
|
||
|
||
1. Uygulamaya admin olarak giriş yapın
|
||
2. **Admin Panel > Settings** sayfasına gidin
|
||
3. **"API Keys Management"** bölümünü bulun
|
||
4. **"Add New Key"** butonuna tıklayın
|
||
5. Her anahtar için:
|
||
- **Key Name:** `VITE_CLERK_PUBLISHABLE_KEY`
|
||
- **Key Value:** Kopyaladığınız publishable key
|
||
- **Save** butonuna tıklayın
|
||
|
||
### Yöntem 3: Supabase Secrets (Backend Anahtarları)
|
||
|
||
Backend anahtarları (CLERK_SECRET_KEY, CLERK_WEBHOOK_SECRET) Supabase Edge Functions için yapılandırılmalıdır:
|
||
|
||
1. Supabase Dashboard'a gidin: https://supabase.com/dashboard
|
||
2. Projenizi seçin: `vtztatcglebrnvikvntf`
|
||
3. Sol menüden **"Edge Functions"** seçeneğine tıklayın
|
||
4. **"Manage secrets"** butonuna tıklayın
|
||
5. Her secret için:
|
||
- **Name:** `CLERK_SECRET_KEY`
|
||
- **Value:** Kopyaladığınız secret key
|
||
- **Add** butonuna tıklayın
|
||
6. Aynı işlemi `CLERK_WEBHOOK_SECRET` için tekrarlayın
|
||
|
||
---
|
||
|
||
## ✅ Doğrulama
|
||
|
||
### Frontend Doğrulama
|
||
|
||
1. Uygulamayı açın: http://localhost:5173
|
||
2. **Sign In** veya **Sign Up** sayfasına gidin
|
||
3. Clerk login formu görünüyorsa ✅ başarılı
|
||
4. Eğer hata mesajı görüyorsanız:
|
||
- Browser console'u açın (F12)
|
||
- Hata mesajlarını kontrol edin
|
||
- `VITE_CLERK_PUBLISHABLE_KEY` doğru mu kontrol edin
|
||
|
||
### Backend Doğrulama
|
||
|
||
1. Admin Panel'e giriş yapın
|
||
2. **Admin Panel > Clerk Diagnostics** sayfasına gidin
|
||
3. **"Test Clerk Connection"** butonuna tıklayın
|
||
4. Başarılı mesajı görüyorsanız ✅ backend doğru yapılandırılmış
|
||
|
||
### Webhook Doğrulama
|
||
|
||
1. Clerk Dashboard > Webhooks sayfasına gidin
|
||
2. Oluşturduğunuz webhook'u seçin
|
||
3. **"Send test event"** butonuna tıklayın
|
||
4. `user.created` event'ini seçin
|
||
5. **Send** butonuna tıklayın
|
||
6. Response `200 OK` ise ✅ webhook çalışıyor
|
||
|
||
---
|
||
|
||
## 🔒 Güvenlik En İyi Uygulamaları
|
||
|
||
### ✅ Yapılması Gerekenler
|
||
|
||
1. **Secret Key'leri Asla Paylaşmayın**
|
||
- GitHub, Slack, email gibi platformlarda paylaşmayın
|
||
- Screenshot alırken anahtarları gizleyin
|
||
|
||
2. **Environment Variables Kullanın**
|
||
- Anahtarları kod içine hard-code etmeyin
|
||
- `.env` dosyasını `.gitignore`'a ekleyin
|
||
|
||
3. **Development ve Production Anahtarlarını Ayırın**
|
||
- Test için `pk_test_...` ve `sk_test_...` kullanın
|
||
- Production için `pk_live_...` ve `sk_live_...` kullanın
|
||
|
||
4. **Anahtarları Düzenli Olarak Rotate Edin**
|
||
- Her 3-6 ayda bir anahtarları yenileyin
|
||
- Şüpheli aktivite durumunda hemen yenileyin
|
||
|
||
5. **Webhook Secret'ı Koruyun**
|
||
- Webhook endpoint'inizi public yapmayın
|
||
- Sadece Clerk IP'lerinden gelen istekleri kabul edin
|
||
|
||
### ❌ Yapılmaması Gerekenler
|
||
|
||
1. **Frontend'de Secret Key Kullanmayın**
|
||
- `CLERK_SECRET_KEY` sadece backend'de kullanılmalı
|
||
- Browser'da görünür olmamalı
|
||
|
||
2. **Anahtarları Git'e Commit Etmeyin**
|
||
- `.env` dosyasını commit etmeyin
|
||
- `.env.example` kullanın (değerler olmadan)
|
||
|
||
3. **Public Repository'lerde Anahtarları Paylaşmayın**
|
||
- GitHub, GitLab gibi platformlarda anahtarları expose etmeyin
|
||
|
||
---
|
||
|
||
## 🐛 Sorun Giderme
|
||
|
||
### Hata: "Clerk Publishable Key bulunamadı"
|
||
|
||
**Çözüm:**
|
||
1. `.env` dosyasında `VITE_CLERK_PUBLISHABLE_KEY` tanımlı mı kontrol edin
|
||
2. Anahtar `pk_` ile başlıyor mu kontrol edin
|
||
3. Development server'ı yeniden başlatın: `npm run dev`
|
||
4. Browser cache'ini temizleyin (Ctrl+Shift+R)
|
||
|
||
### Hata: "Invalid Clerk API Key"
|
||
|
||
**Çözüm:**
|
||
1. Clerk Dashboard'da API Keys sayfasına gidin
|
||
2. Anahtarın aktif olduğunu kontrol edin
|
||
3. Doğru environment'ı (test/live) kullandığınızdan emin olun
|
||
4. Anahtarı yeniden kopyalayıp yapıştırın (boşluk karakteri olmamalı)
|
||
|
||
### Hata: "Webhook signature verification failed"
|
||
|
||
**Çözüm:**
|
||
1. `CLERK_WEBHOOK_SECRET` doğru mu kontrol edin
|
||
2. Webhook URL'inin doğru olduğunu kontrol edin
|
||
3. Clerk Dashboard'da webhook'un aktif olduğunu kontrol edin
|
||
4. Supabase Edge Function'ın deploy edildiğini kontrol edin
|
||
|
||
### Hata: "User profile not created after sign up"
|
||
|
||
**Çözüm:**
|
||
1. Webhook'un çalıştığını kontrol edin (yukarıdaki webhook doğrulama)
|
||
2. Supabase logs'u kontrol edin:
|
||
- Supabase Dashboard > Edge Functions > clerk-webhook > Logs
|
||
3. Database'de `profiles` tablosunu kontrol edin
|
||
4. RLS policies'in doğru yapılandırıldığını kontrol edin
|
||
|
||
---
|
||
|
||
## 📊 Clerk Dashboard Özellikleri
|
||
|
||
### User Management
|
||
- **Users:** Tüm kullanıcıları görüntüleyin ve yönetin
|
||
- **Organizations:** Organizasyon yönetimi (opsiyonel)
|
||
- **Sessions:** Aktif oturumları görüntüleyin
|
||
|
||
### Authentication
|
||
- **Email/Password:** E-posta ve şifre ile giriş
|
||
- **Social Logins:** Google, Facebook, GitHub entegrasyonu
|
||
- **Phone:** SMS ile telefon doğrulama
|
||
- **Multi-factor:** 2FA desteği
|
||
|
||
### Customization
|
||
- **Appearance:** Login/signup formlarının görünümünü özelleştirin
|
||
- **Localization:** Türkçe dil desteği (uygulama içinde yapılandırılmış)
|
||
- **Branding:** Logo ve renk teması özelleştirme
|
||
|
||
### Analytics
|
||
- **Sign-ups:** Günlük/haftalık kayıt istatistikleri
|
||
- **Active Users:** Aktif kullanıcı sayısı
|
||
- **Sessions:** Oturum süreleri ve aktivite
|
||
|
||
---
|
||
|
||
## 💰 Fiyatlandırma
|
||
|
||
### Free Tier (Development)
|
||
- ✅ 10,000 Monthly Active Users (MAU)
|
||
- ✅ Tüm authentication yöntemleri
|
||
- ✅ Webhooks
|
||
- ✅ Email support
|
||
- ✅ Test environment
|
||
|
||
### Pro Plan ($25/month)
|
||
- ✅ 10,000 MAU dahil
|
||
- ✅ $0.02/MAU sonrası
|
||
- ✅ Custom domains
|
||
- ✅ Advanced analytics
|
||
- ✅ Priority support
|
||
|
||
### Enterprise (Custom)
|
||
- ✅ Unlimited MAU
|
||
- ✅ SLA guarantees
|
||
- ✅ Dedicated support
|
||
- ✅ Custom integrations
|
||
|
||
**Not:** Development için Free tier yeterlidir. Production'da kullanıcı sayınıza göre plan seçin.
|
||
|
||
---
|
||
|
||
## 🔗 Faydalı Linkler
|
||
|
||
- **Clerk Dashboard:** https://dashboard.clerk.com/
|
||
- **Clerk Documentation:** https://clerk.com/docs
|
||
- **Clerk React SDK:** https://clerk.com/docs/references/react/overview
|
||
- **Clerk Webhooks:** https://clerk.com/docs/integrations/webhooks
|
||
- **Supabase Dashboard:** https://supabase.com/dashboard/project/vtztatcglebrnvikvntf
|
||
|
||
---
|
||
|
||
## 📞 Destek
|
||
|
||
### Clerk Desteği
|
||
- **Email:** support@clerk.com
|
||
- **Discord:** https://clerk.com/discord
|
||
- **Documentation:** https://clerk.com/docs
|
||
|
||
### Uygulama Desteği
|
||
- **Admin Panel:** Admin Panel > Settings > Support
|
||
- **Logs:** Admin Panel > Logs
|
||
|
||
---
|
||
|
||
## ✨ Özet Checklist
|
||
|
||
Kurulumu tamamlamak için:
|
||
|
||
- [ ] Clerk hesabı oluşturuldu
|
||
- [ ] Yeni uygulama oluşturuldu
|
||
- [ ] `VITE_CLERK_PUBLISHABLE_KEY` alındı ve yapılandırıldı
|
||
- [ ] `CLERK_SECRET_KEY` alındı ve Supabase'e eklendi
|
||
- [ ] Webhook endpoint oluşturuldu
|
||
- [ ] `CLERK_WEBHOOK_SECRET` alındı ve Supabase'e eklendi
|
||
- [ ] Frontend doğrulaması yapıldı (login formu görünüyor)
|
||
- [ ] Backend doğrulaması yapıldı (Clerk Diagnostics)
|
||
- [ ] Webhook doğrulaması yapıldı (test event gönderildi)
|
||
- [ ] Test kullanıcı kaydı oluşturuldu
|
||
- [ ] Profile database'de oluşturuldu
|
||
|
||
Tüm adımlar tamamlandığında ✅ Clerk entegrasyonu hazır!
|
||
|
||
---
|
||
|
||
**Son Güncelleme:** 2026-02-26
|
||
**Versiyon:** 1.0
|