JWT Claims Açıklaması

JWT Claim’lerinin Yaptığı Şey

JWT, noktalarla ayrılmış üç base64url kodlu segmenttir: header.payload.signature. Payload, kimlik ve yetkilendirme verileri taşıyan claim’leri (anahtar-değer çiftleri) içerir. Her claim, tokena sahip olan herkese görünürdür. Şifreleme yoktur, yalnızca tokenın güvenilir bir parti tarafından verildiğini doğrulayan bir imza vardır.

Claim’ler üç kategoride yer alır:

• Kayıtlı claim’ler: JWT spec (RFC 7519) tarafından tanımlanır. Bunlar iss, sub, aud, exp, nbf, iat ve jti’yi içerir.
• Herkese açık claim’ler: IANA JSON Web Token Claims Registry’de kayıtlı veya çarpışma dirençli bir isim kullanır.
• Özel claim’ler: Veren ve tüketici arasında üzerinde anlaşulan isimler (örn. role, org_id, permissions).

Zaman Claim’leri: iat, nbf, exp

Bu üç claim bir tokenın yaşam döngüsünü oluşturur:

iat ──────────── nbf ──────────── token aktif ──────────── exp
                  │                                        │
                  └── token geçerli olmaya başlar          └── token sona erer

iat (Verilme Zamanı)

Tokenın oluşturulduğu Unix zaman damgası. Bu bilgilendiricidir. Uygulama mantığınız maksimum token yaşı dayatmadığı sürece doğrulamayı etkilemez.

{
  "iat": 1735603200
}

1735603200 = 1 Ocak 2025 00:00:00 UTC.

nbf (Önceden Değil)

Tokenın geçerli olduğu Unix zaman damgası. Bir token gelecekte bir nbf ile gelirse, sunucu onu reddetmelidir. Bu pratikte nadiren görülür. Çoğu sistem nbf’yi iat’ye eşit ayarlar.

{
  "nbf": 1735603200
}

exp (Son Kullanma)

Tokenın geçersizleştiği Unix zaman damgası. Bu anahtar zaman claim’idir. Sunucu, exp’si geçmişte olan her tokenı reddetmelidir.

{
  "exp": 1735689600,
  "iat": 1735603200
}

Fark 86400 saniyedir (24 saat). Bu tokenın bir günlük ömrü vardır.

Standart Kayıtlı Claim’ler

Zaman claim’lerinin ötesinde, JWT spec birkaç standart claim tanımlar:

iss (Veren): Tokenı kimin oluşturduğunu belirtir. Auth sunucunuz, diğer verenlerin tokenlarının kabul edilmesini önlemek için bunu doğrulamalıdır.

sub (Konu): Tokenın temsil ettiği varlık. Genellikle bir kullanıcı ID’si veya hizmet hesabı adıdır. İsteği kimin yaptığını belirlemek için yetkilendirme mantığınızda bunu kullanın.

aud (Hedef): Tokenın kime yönelik olduğu. Sisteminiz birden fazla hizmete sahipse (örn. API gateway, kullanıcı hizmeti, ödeme hizmeti), her biri aud claim’inin kendi tanımlayıcısıyla eşleştiğini doğrulamalıdır.

jti (JWT Kimliği): Token için benzersiz bir tanımlayıcı. Token iptali için bunu kullanın. Kullanıcı çıkış yaptığında veya token iptal edildiğinde jti’yi bir inkar listesinde saklayın.

Saat Sapması: Neden Tokenlar Erken Reddedilir

Sunucuların saatleri asla tam olarak senkronize değildir. Auth sunucusunun saati API sunucusundan 30 saniye ileriyse, exp = 1735689600 olan bir token, zaten 1735689631 olduğunu düşünen bir sunucu tarafından doğrulanabilir.

Çözüm bir tolerans penceresidir:

// Node.js ile jsonwebtoken
jwt.verify(token, secret, { clockTolerance: 30 }); // 30 saniye tolerans

// Go ile golang-jwt
token, err := jwt.Parse(tokenString, keyFunc,
    jwt.WithLeeway(30 * time.Second),
)

30-60 saniyelik bir tolerans standarttır. Sıfıra ayarlamayın, aksi takdirde hata ayıklaması zor aralıklı 401 hataları görürsünüz.

Yaygın Hatalar

exp’i saniyelerle vs milisaniyelerle kullanma

Bazı kütüphaneler saniye (RFC 7519 standardı), bazıları milisaniye kullanır. exp: 1735689600 (saniye) olan bir token, milisaniye olarak yorumlandığında yıl 56935 gibi görünür. Kütüphanenizin beklentisini doğrulayın.

exp’yi çok ileri bir tarihe ayarlama

30 günlük ömürlü bir token, çalınmış bir tokenın 30 gün boyunca kullanılabileceği anlamına gelir. Access tokenlar 15-60 dakika içinde sona ermelidir.

aud doğrulamasının eksik olması

API’niz aud claim’ini kontrol etmiyorsa, farklı bir hizmet için verilen bir token sizin uç noktanıza karşı kullanılabilir. Her zaman iss ve aud’yu doğrulayın.

Claim’lerde hassas veri saklama

Claim’ler tokena sahip olan herkes tarafından okunabilir. Şifreleri, SSN’leri veya özel anahtarları JWT claim’lerinde koymayın.

Örnek Tokenı Kodlama

Tüm claim’lerin kodunu çözmek için örnek tokenı JWT Decoder’a yapıştırın. Payload şunları içerir:

{
  "iss": "https://api.example.com",
  "sub": "user_12345",
  "aud": "https://app.example.com",
  "exp": 1735689600,
  "iat": 1735603200,
  "nbf": 1735603200,
  "role": "admin",
  "permissions": ["read", "write", "delete"]
}

Token 1 Ocak 2025 UTC gece yarısında verilmiş, 24 saat sonra sona eriyor ve user_12345’e admin erişimi sağlıyor.