|
**JWT çekirdeği (kütüphanesiz)**
- HS256 imza, `hash_hmac` + `hash_equals`
- `alg` sabit — `none` ve algoritma karışıklığı kapalı
- `exp`, `nbf` kontrolü `JWT_LEEWAY` toleransıyla
- `exp`i olmayan jeton **reddedilir**
- `iss` / `aud` doğrulaması
- `jti` (jeton kimliği) baştan bulunur
- base64url encode/decode elle yazılmış
**Kimlik ve yetki**
- API anahtarı → kısa ömürlü jeton akışı
- `secret` `password_hash()` ile saklanır
- Zamanlama saldırısına karşı sahte hash ile doğrulama
- Anahtar sayımına (enumeration) karşı tek tip hata
- Kapsam (scope) tabanlı yetkilendirme
- Kapsamlar **beyaz listeden** geçer
- `active = 0` ile anahtarı silmeden kapatma
|
**API tasarımı**
- Tutarlı JSON zarfı: `data` / `meta` / `error`
- Değişmeyen `error.code` + insan için `error.message`
- Doğru durum kodları: 200/201/204/400/401/403/404/405/422/429/500
- `Allow`, `Location`, `WWW-Authenticate`, `Retry-After` başlıkları
- Sayfalama, arama (`?q=`), sıralama (beyaz listeli)
- Anahtar başına **kayan pencereli** hız sınırı
- `GET /` ile uç listesi (discovery)
- CORS + preflight (`OPTIONS` → 204)
**Konsol ve tasarım**
- Jetonun üç parçası renkli, payload tarayıcıda çözülür
- **8 senaryo**: doğrulamayı bilerek kıran istekler
- İstek geçmişi + detay penceresi + **curl karşılığı**
- Paylaşılabilir derin bağlantı (`#dene-…`, `#detay-…`)
- Sayaç şeridi: kalan süre, kapsam, not, kalan istek, anahtar
- Mobil: 360px'te **yatay kaydırma yok**
- Jeton `localStorage`'a **yazılmaz** — yalnızca bellekte
|
---
### Güvenlik: Neyi, Nasıl Kapattık?
| Açık | Tipik hatalı kod | Bu projede |
|------|------------------|------------|
| **`alg: none` saldırısı** | `$alg = $header['alg'];` — algoritma jetondan okunur | `alg !== 'HS256'` ise imza hiç hesaplanmadan **reddedilir** |
| **Zamanlama saldırısı (imza)** | `if ($sig === $beklenen)` | `hash_equals()` — sabit zamanlı kıyas |
| **Zamanlama saldırısı (secret)** | Anahtar yoksa hemen `return` | Sahte bir hash'le `password_verify()` **yine de** çalıştırılır |
| **Süresiz jeton** | `exp` hiç kontrol edilmez | `exp` yoksa **reddedilir**; varsa `JWT_LEEWAY` toleransıyla kontrol edilir |
| **Servisler arası jeton geçişi** | `iss`/`aud` kontrolü yok | İkisi de beklenen değerlerle karşılaştırılır |
| **Yetki = kimlik varsayımı** | Jetonu olan her şeyi yapabilir | `require_scope()` — eksikse **403** ve `details` ile hangi kapsamın gerektiği |
| **Anahtar sayımı (enumeration)** | "Anahtar bulunamadı" / "secret hatalı" ayrı mesajlar | İkisi de tek tip `401 invalid_client` |
| **Ham secret saklama** | `secret VARCHAR(64)` | `secret_hash` — `password_hash()`, geri üretilemez |
| **SQL Injection** | Dize birleştirme ile sorgu | Tüm sorgular prepared statement, `EMULATE_PREPARES = false` |
| **`ORDER BY` enjeksiyonu** | `ORDER BY $_GET['sort']` | Beyaz liste; tanınmayan değer `id`'ye düşer |
| **`LIKE` joker istismarı** | `LIKE '%$q%'` | `%` ve `_` kaçışlanır (`ESCAPE '!'`) |
| **Başkasının kaydına erişim** | Sahiplik PHP'de kontrol edilir | `owner_key` **her sorgunun** `WHERE`'inde; yetkisiz kayıt **404** |
| **Kaba kuvvet (secret deneme)** | Sınırsız `POST /auth/token` | Anahtar/IP başına **12 istek / 60 sn** + `Retry-After` |
| **Bilgi sızdıran hatalar** | Canlıda SQL metni ekrana basılır | `APP_DEBUG` sunucu adından türetilir; canlıda `false` |
| **Jeton hırsızlığı (XSS)** | Jeton `localStorage`'a yazılır | Konsolda jeton yalnızca **bellekte** tutulur |
| **Yapılandırma sızıntısı** | `config.php` doğrudan indirilebilir | `system/` klasörü **tümüyle kapalı** + dosya içi `CY_APP` kontrolü |
| **Şema/veri sızıntısı** | `/cy_api_jwt.sql` → HTTP 200 | `.sql`, `.md`, `.json`, `.log`, `.ini`, `.bak`, `.example` kapalı (`README*.md` bilinçli istisna) |
| **Clickjacking** | Başlık yok | `X-Frame-Options: SAMEORIGIN` |
| **MIME sniffing** | Başlık yok | `X-Content-Type-Options: nosniff` |
> **CSRF neden yok?** Bu API çerez kullanmaz; kimlik `Authorization` başlığıyla taşınır. Tarayıcının kendiliğinden gönderdiği bir kimlik olmadığı için saldırganın sayfası isteği atabilir ama **jetonu ekleyemez**. CSRF, çerezle taşınan oturumların sorunudur.
---
### Kurulum
**Gereksinimler:** PHP 8.0+ · MySQL 5.7+ / MariaDB 10.3+ · Apache (mod_rewrite önerilir)
```bash
# 1) Depoyu alın
git clone https://github.com/CilginYazilim/rest-api-jwt.git
cd rest-api-jwt
# 2) Veritabanını oluşturun (dosya CREATE DATABASE'i kendisi yapar)
mysql -u root -p < cy_api_jwt.sql
# 3) Yerel ayarları oluşturun (isteğe bağlı; varsayılanlar XAMPP'a uyar)
# En kısa yol — .env:
cp .env.example .env
# → içindeki DB_* satırlarını doldurun
#
# Ya da config.local.php (JWT_SECRET'i de burada tutabilirsiniz):
cp system/config.local.php.example system/config.local.php
# 4) Tarayıcıda açın
# http://localhost/rest-api-jwt/
```
**Composer yok, npm yok.** jQuery ve Bootstrap dosyaları depoda; internet bağlantısı olmadan da çalışır.
#### 30 saniyede curl ile deneme
```bash
BASE=http://localhost/rest-api-jwt/api
# Jeton al
TOKEN=••••••••
-H 'Content-Type: application/json' \
-d '{"key_id":"demo_full","secret":"••••••••"}' \
| php -r 'echo json_decode(file_get_contents("php://stdin"),true)["data"]["token"];')
# Kullan
curl -s "$BASE/notes?limit=3" -H "Authorization: Bearer $TOKEN"
curl -s "$BASE/me" -H "Authorization: Bearer $TOKEN"
# Kapsam sınırını gör (salt okunur anahtarla yazma denemesi → 403)
RO=$(curl -s -X POST "$BASE/auth/token" -H 'Content-Type: application/json' \
-d '{"key_id":"demo_readonly","secret":"••••••••"}' \
| php -r 'echo json_decode(file_get_contents("php://stdin"),true)["data"]["token"];')
curl -i -s -X POST "$BASE/notes" -H "Authorization: Bearer $RO" \
-H 'Content-Type: application/json' -d '{"title":"olmaz"}'
```
#### mod_rewrite yoksa
Temiz URL'ler (`/api/notes`) `api/.htaccess` içindeki yönlendirmeye dayanır. Yönlendirme çalışmıyorsa API yine erişilebilirdir:
```
/api/index.php/notes (PATH_INFO)
/api/index.php?path=/notes (sorgu dizesi)
```
Üç biçim de aynı yönlendiriciye düşer; `resolve_path()` üçünü birden dener.
#### Ortam değişkenleri
Depo kökündeki **`.env`** dosyasına yazın; `system/config.php` dosyasına
hiç dokunmayın:
```bash
cp .env.example .env # Windows: copy .env.example .env
```
`.env` `.gitignore` içindedir: depoya gönderilmez ve dağıtım (deploy) onu
**silmez**. `system/config.php` ise depoda durur ve her dağıtımda depodaki
sürümle değiştirilir — parolayı oraya yazarsanız hem GitHub'a gider hem de
ilk deploy'da kaybolur.
Dosyayı hiç oluşturmasanız da uygulama çalışır; aşağıdaki varsayılanlar
yerel bir XAMPP kurulumuna göredir.
**Değer arama sırası:** `.env` → sunucunun gerçek ortam değişkeni
(Apache `SetEnv`, systemd…) → buradaki varsayılan.
| Değişken | Varsayılan | Ne işe yarar |
|---|---|---|
| `DB_HOST` | `127.0.0.1` | Veritabanı sunucusu |
| `DB_NAME` | `cy_api_jwt` | Veritabanı adı |
| `DB_USER` | `root` | Kullanıcı |
| `DB_PASS` | *(boş)* | Şifre — **koda yazmayın** |
| `APP_TIMEZONE` | `Europe/Istanbul` | PHP'nin saat dilimi |
| `APP_DEBUG` | *ortamdan* | Hataların ekrana basılıp basılmayacağı |
**`APP_TIMEZONE` neden var?** XAMPP'ın `php.ini` dosyasındaki
`date.timezone`, MySQL'in kullandığı sistem diliminden farklı olabilir.
Test makinesinde PHP `Europe/Berlin`, MySQL `Europe/Istanbul`
kullanıyordu; aynı anı anlatan iki satır bir saat farklı görünüyordu.
Zaman **hesapları** SQL tarafında yapıldığı için doğruydu, ama ekrana
basılan saat kayıyordu. Artık dilim açıkça sabitleniyor — sunucunuz başka
bir bölgedeyse bu değişkeni tanımlamanız yeterli, koda dokunmayın.
---
### Yapılandırma
Tüm ayarlar `system/config.php` içindedir. **Sırlar oraya yazılmaz** — `system/config.local.php` dosyasına yazılır; o dosya `.gitignore` içindedir, depoya gitmez ve deploy sırasında silinmez.
| Sabit | Varsayılan | Ne işe yarar |
|-------|-----------|--------------|
| `JWT_SECRET` | *(geliştirme değeri)* | HS256 imza anahtarı. **Üretimde mutlaka değiştirin.** |
| `JWT_TTL` | `900` | Jeton ömrü (saniye). Kısa tutun. |
| `JWT_ISS` / `JWT_AUD` | `cy-rest-api` / `cy-clients` | Jetonu üreten ve jetonun geçerli olduğu servis. |
| `JWT_LEEWAY` | `30` | Sunucu saatleri arası kayma toleransı (saniye). |
| `RATE_LIMIT_TOKEN` | `[12, 60]` | Jeton üretimi: 12 istek / 60 sn. |
| `RATE_LIMIT_API` | `[180, 60]` | Normal trafik: 180 istek / 60 sn. |
| `KNOWN_SCOPES` | 3 kapsam | Tanınan kapsamlar. Listede olmayan kapsam yok sayılır. |
| `DEMO_TOKENS` | `true` | Bilerek bozuk jeton üreten uç. **Üretimde `false` yapın.** |
| `APP_DEBUG` | *(otomatik)* | Sunucu adından türetilir; canlı alan adında kendiliğinden kapanır. |
| `NOTE_TITLE_MAX` / `NOTE_BODY_MAX` | `150` / `10000` | Doğrulama sınırları. |
| `NOTES_PAGE_MAX` | `100` | Sayfa başına en çok kayıt. |
#### Yeni imza anahtarı üretmek
```bash
php -r "echo bin2hex(random_bytes(32));"
```
Anahtarı değiştirmek, o an dolaşımdaki **tüm** jetonları geçersiz kılar. Bu bir yan etki değil, elinizdeki **tek toplu iptal yöntemidir**.
#### Yeni API anahtarı eklemek
```bash
php -r "echo password_hash('secretiniz', PASSWORD_DEFAULT), PHP_EOL;"
```
```sql
INSERT INTO api_keys (name, key_id, secret_hash, scopes)
VALUES ('Mobil uygulama', 'mobil_v1', '$2y$10$…', 'notes:read notes:write profile:read');
```
---
### Kendi Projenize Eklemek
Bu depodan kendi projenize taşınacak **üç dosya** vardır:
| Dosya | Ne taşır |
|-------|----------|
| `system/function.php` | JWT çekirdeği, JSON zarfı, hız sınırı, kimlik/kapsam yardımcıları |
| `system/config.php` | Yapılandırma kalıbı ve `config.local.php` mekanizması |
| `api/index.php` | Yönlendirme ve uç noktalar — kendi kaynaklarınızla değiştirin |
`index.php` ile `assets/js/console.js` **API'nin parçası değildir**; silebilirsiniz.
#### Yeni bir uç nokta eklemek
```php
// api/index.php içinde, $claims = require_auth(); satırından SONRA
if ($path === '/urunler' && $method === 'GET') {
require_scope($claims, 'urunler:read'); // yetki kontrolü
$stmt = $db->prepare('SELECT id, ad, fiyat FROM urunler WHERE owner_key = :k');
$stmt->execute([':k' => $claims['sub']]);
api_ok($stmt->fetchAll()); // { "data": [...] }
}
```
Yeni kapsamı `KNOWN_SCOPES`'a eklemeyi unutmayın — beyaz listede olmayan kapsam, veritabanındaki anahtara yazılsa bile **yok sayılır**.
#### JWT çekirdeğini tek başına kullanmak
```php
require 'system/function.php';
$jwt = jwt_encode(['sub' => 'kullanici-42', 'scopes' => ['notes:read']]);
[$claims, $hata] = jwt_decode($jwt);
if ($hata !== null) {
echo jwt_error_message($hata); // "Jetonun süresi doldu." vb.
}
```
---
### Tasarım Kalıbı
Arayüz, tüm Çılgın Yazılım örneklerinde ortak olan tasarım kalıbını kullanır:
| Dosya | Kapsam | Değiştirilir mi? |
|-------|--------|------------------|
| `assets/css/cilginyazilim.css` | **Marka kalıbı** — kartlar, butonlar, tablolar, rozetler, modal | **Hayır.** Projeler arası ortaktır. |
| `assets/css/style.css` | Yalnızca bu sayfaya özgü parçalar (anahtar kartları, JWT gösterimi, senaryo ızgarası) | Evet |
Yükleme sırası: `bootstrap` → `cilginyazilim` → `style`. Renkler doğrudan yazılmaz, CSS değişkenlerinden okunur (`--cy-brand-600`, `--cy-danger` …).
Aynı kalıpla hazırlanmış diğer örnekler: [cilginyazilim.com/kutuphane](https://cilginyazilim.com/kutuphane)
---
### Dosya Yapısı
```
.
├── api/
│ ├── .htaccess → temiz URL yönlendirmesi + Authorization başlığı taşıma
│ └── index.php → API ÖN DENETLEYİCİ: yönlendirme ve tüm uç noktalar
├── system/
│ ├── .htaccess → klasör TÜMÜYLE kapalı (Require all denied)
│ ├── config.php → yapılandırma + PDO bağlantısı
│ ├── config.local.php → (siz oluşturursunuz; .gitignore içinde)
│ ├── config.local.php.example
│ └── function.php → JWT, JSON zarfı, hız sınırı, kimlik/kapsam
├── assets/
│ ├── css/ → bootstrap.min · cilginyazilim (marka) · style
│ ├── js/ → jquery · bootstrap.bundle · console.js
│ └── images/logo.png
├── docs/screenshots/
├── .htaccess → dizin listeleme kapalı, dosya türü kuralları, güvenlik başlıkları
├── .env.example → Veritabanı bilgileri (isteğe bağlı) — .gitignore içinde
├── cy_api_jwt.sql → şema + 4 anahtar + 19 not (zamanlar NOW() - INTERVAL ile)
├── index.php → API KONSOLU (API'nin parçası değildir)
├── CHANGELOG.md
├── LICENSE
├── README.md
└── README.en.md
```
---
### Nasıl Çalışıyor?
```
İSTEMCİ API VERİTABANI
│ │ │
│ POST /auth/token │ │
│ { key_id, secret } │ │
├─────────────────────────────>│ │
│ │ hız sınırı (12/60 sn) │
│ │ SELECT … WHERE key_id = ? │
│ ├─────────────────────────────────>│
│ │ password_verify(secret, hash) │
│ │ active = 1 ? │
│ │ │
│ │ jwt_encode({sub, scopes, exp}) │
│ { data: { token, … } } │ │
│<─────────────────────────────┤ │
│ │
│ GET /notes │
│ Authorization: Bearer 
## JWT ile REST API
#### PHP 8 · HS256 · Kütüphanesiz · Kapsam Tabanlı Yetki · Bootstrap 5 · Çılgın Yazılım Tasarım Kalıbı
**Composer yok, firebase/php-jwt yok — 60 satır PHP. Ama doğru yapılmış hâli.**
[](https://php.net)
[](https://mysql.com)
[](https://jwt.io)
[](#kurulum)
[](LICENSE)
**🇹🇷 Türkçe** · [🇬🇧 English](README.en.md)
[**▶ Canlı Demo**](https://cilginyazilim.com/kutuphane/uygulama/rest-api-jwt/) · [Kaynak Kütüphanesi](https://cilginyazilim.com/kutuphane/php-rest-api-jwt) · [cilginyazilim.com](https://cilginyazilim.com)
---
### Canlı Demo
**Kurulum yok, kayıt yok, indirme yok — tarayıcınızdan 3 saniyede deneyin.**
▲ Görsele tıklayarak demoyu açabilirsiniz
#### Mobil görünüm
390px genişlikte **yatay kaydırma yok**. İkincil sütunlar gizlenir; bilgi detay penceresinde korunur.
---
### Beş Kritik Karar
#### 1. Algoritma jetondan okunmaz
```php
// TİPİK HATALI KOD — algoritmayı saldırgan seçiyor
$header = json_decode(base64_decode($h64), true);
$alg = $header['alg']; // "none" gelebilir!
if ($alg === 'none') { /* imza yok, geç */ }
// BU PROJEDE — algoritma SABİT
if (!is_array($header) || ($header['alg'] ?? '') !== 'HS256') {
return [null, 'bad_alg']; // imza HİÇ hesaplanmadan reddedilir
}
```
`alg: none` saldırısı gerçek kütüphanelerde yıllarca yaşadı ve bugün hâlâ kopyalanan örneklerde duruyor. Saldırgan `alg` değerini `none` yapar, imza bölümünü siler ve payload'a istediği `sub` ile `scopes` değerlerini yazar. Kod algoritmayı **jetonun kendisinden** okuyorsa, saldırganın kimliğini kendi kendine onaylamış olur.
Doğrusu, sunucunun hangi algoritmayı kabul ettiğini **önceden bilmesidir**. Demodaki "alg: none saldırısı" senaryosu bu jetonu tarayıcıda üretir ve reddedilişini gösterir.
#### 2. İmza `hash_equals` ile kıyaslanır
```php
// TİPİK HATALI KOD
if ($expectedSig === $gelenSig) { /* ... */ }
// BU PROJEDE
if (!hash_equals($expectedSig, b64url_decode($s64))) {
return [null, 'bad_signature'];
}
```
PHP'nin `===` operatörü dizeleri bayt bayt kıyaslar ve **ilk farklı baytta çıkar**. Kıyas süresi, kaç baytın tuttuğuna bağlı olarak değişir; bu fark ağ üzerinden bile ölçülebilir. Saldırgan imzayı bayt bayt tahmin ederek doğru olanı bulabilir.
`hash_equals()` uzunluktan bağımsız olarak **hep aynı süreyi** harcar. Bu, jeton doğrulamasının pazarlık edilemez parçasıdır.
#### 3. Kimlik doğrulama ile yetkilendirme ayrı katmanlardır
```
Authorization: ••••••••
│
├── require_auth() → jeton geçerli mi? değilse 401
│ (imza, exp, nbf, iss, aud)
│
└── require_scope() → bu işlemi yapabilir mi? değilse 403
(scopes claim'i)
```
**401 "kim olduğunu bilmiyorum" demektir; 403 "kim olduğunu biliyorum ama bunu yapamazsın" demektir.** İkisini karıştıran bir istemci 403 aldığında yeni jeton almaya çalışır, aynı 403'ü alır ve **sonsuz döngüye** girer.
Bu projede dört demo anahtarı bu ayrımı somutlaştırır: `demo_writer` yazabilir ama **okuyamaz**. "Yazabiliyorsa okuyabilir" diye bir kural yoktur.
#### 4. Secret veritabanında hash'li tutulur
```sql
-- TİPİK HATALI ŞEMA
`secret` VARCHAR(64) NOT NULL, -- ham secret; sızan döküm = ele geçen API
-- BU PROJEDE
`secret_hash` VARCHAR(255) NOT NULL, -- password_hash(); geri üretilemez
```
API anahtarının secret'ı da bir paroladır — yalnızca kullanıcısı insan değil, bir programdır. Anahtar tablosu, sızdırılan veritabanı dökümlerinde ilk bakılan yerdir. Ham secret dursaydı, dökümü ele geçiren herkes API'ye tam yetkiyle girerdi.
Doğrulama `password_verify()` ile yapılır ve **anahtar bulunamasa bile çalıştırılır**: yoksa "bu `key_id` var ama secret yanlış" ile "bu `key_id` hiç yok" arasındaki süre farkı ölçülebilir hâle gelirdi.
#### 5. Sahiplik koşulu SQL'dedir, PHP'de değil
```php
// TİPİK HATALI KOD — bir yerde unutulur
$not = $db->query("SELECT * FROM api_notes WHERE id = $id")->fetch();
if ($not['owner_key'] !== $claims['sub']) { /* 403 */ }
// BU PROJEDE — unutmak İMKÂNSIZ
$stmt = $db->prepare('SELECT … FROM api_notes WHERE id = :id AND owner_key = :k');
```
Sahiplik kontrolünü PHP'ye bırakmak, beş uç noktadan birinde unutulması demektir — ve o bir uç, bütün verinin sızması için yeter. Koşul `WHERE`'e gömülünce kontrol atlanabilir bir adım olmaktan çıkar.
Bir ayrıntı daha: yetkisiz kayıt için **403 değil 404** dönüyoruz. 403, "böyle bir kayıt var ama senin değil" bilgisini verirdi; o bilgi, başkasının kaç kaydı olduğunu saymaya yarar.
---
### Neler Var?