05 — Tokenlar, Oturum Yönetimi ve Yenileme

Kimin için: Arka uç ve API mimarları.
Ön koşul: Web Giriş Akışı ve JWT standartları.
Tahmini süre: 15 dakika.

Ne Öğreneceksiniz

• TALOST ID tarafından üretilen token türlerini ve ömürlerini,
• JWKS (/oauth/jwks.json) ile yerel kriptografik imza doğrulamayı (ağ yükü olmadan),
• refresh_token kullanarak oturumu kesintisiz yenilemeyi,
• Token saklama güvenlik prensiplerini.

Token Türleri ve Yaşam Döngüsü

Token Doğrulama (JWKS ile Çevrimdışı Doğrulama)

Her API isteğinde TALOST ID sunucusuna gitmek yerine, Access Token'ları uygulamanızın belleğinde JWKS (JSON Web Key Set) kullanarak milisaniyeler içinde yerel olarak doğrulayabilirsiniz:

TypeScript (Node / Next.js) ile `jose` Kullanımı

import { createRemoteJWKSet, jwtVerify } from "jose";

const ISSUER = process.env.TALOST_ISSUER || "https://id.talost.com";
const CLIENT_ID = process.env.TALOST_CLIENT_ID;

// JWKS anahtarlarını önbellekleyerek çeker (otomatik key rotation destekli)
const JWKS = createRemoteJWKSet(new URL(`${ISSUER}/oauth/jwks.json`));

export async function verifyTalostToken(token: string) {
  try {
    const { payload, protectedHeader } = await jwtVerify(token, JWKS, {
      issuer: ISSUER,
      audience: CLIENT_ID, // Audience istemci ID'si ile eşleşmelidir
    });

    return {
      valid: true,
      sub: payload.sub,
      email: payload.email,
      roles: payload.roles,
      scope: payload.scope,
    };
  } catch (err: any) {
    return { valid: false, error: err.message };
  }
}

Token Yenileme (Refresh Token Akışı)

Access Token süresi dolduğunda (veya dolmasına az bir süre kala), kullanıcıyı tekrar giriş ekranına göndermeden yeni bir access token alınır:

export async function refreshAccessToken(refreshToken: string) {
  const tokenRes = await fetch(`${process.env.TALOST_ISSUER}/oauth/token`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "refresh_token",
      client_id: process.env.TALOST_CLIENT_ID!,
      client_secret: process.env.TALOST_CLIENT_SECRET!,
      refresh_token: refreshToken,
    }),
  });

  if (!tokenRes.ok) {
    throw new Error("Refresh token geçersiz veya süresi dolmuş. Kullanıcı yeniden giriş yapmalıdır.");
  }

  const newTokens = await tokenRes.json();
  // newTokens: { access_token, id_token, refresh_token, expires_in }
  return newTokens;
}

Güvenli Saklama Standartları

1. Web (Sunucu / SSR): Token'ları tarayıcı tarafına asla düz olarak göndermeyin. HttpOnly, Secure ve SameSite=Lax bayraklarına sahip şifreli çerezler kullanın.
2. Web (Saf SPA): Token'ları sadece bellek içinde (JavaScript state/closure) tutun. Tarayıcı yenilendiğinde sessiz yenileme mekanizması çalıştırın.
3. Masaüstü ve Mobil: İşletim sisteminin güvenli kasalarını kullanın (Windows Credential Manager, macOS Keychain, iOS Keychain, Android Keystore).

Sık Yapılan Hatalar

• ID Token'ı Access Token gibi kullanmak: ID Token sadece istemcinin kullanıcıyı tanıması içindir. Arka uç API uçlarına yetkilendirme için gönderilecek token daima access_token olmalıdır.
• İmza doğrulamayı atlamak: Gelen JWT'nin payload kısmını sadece Base64 decode ederek doğrulanmış kabul etmek ölümcül bir güvenlik açığıdır. İmza ve exp kontrolü mutlaka yapılmalıdır.

İlgili Sayfalar

• 06. Kullanıcı Bilgisi ve Claimler
• 12. Güvenli Çıkış (Logout)
• 14. Güvenlik Kuralları

Son doğrulama: 2026-10-04 · Kaynak: _envanter.md, src/app/oauth/jwks.json/route.ts, src/lib/oauth/keys.ts