FIVUCSAS | İşlerim · Vaka Çalışmaları

Problem

Biyometrik kimlik doğrulamayı benimsemek zordur çünkü onu entegre etmek genellikle ham yüz ve ses verisini işlemeyi, sahtecilik saldırılarını savuşturmayı ve katı gizlilik yasalarına uymayı gerektirir. Bu çoğu ekibin üstlenemeyeceği bir iştir. Amaç, biyometrik girişi bir siteye reCAPTCHA kadar kolay eklenebilir hâle getirmekti; üstelik entegre eden taraf biyometrik veriye hiç dokunmadan.

Kısıtlar

Biyometrik veri hiçbir zaman şifresiz olarak depolanmamalı ve gömme çıkarımı hiçbir zaman halka açık internetten erişilebilir olmamalı.

KVKK uyumluluğu sonradan eklenecek bir özellik değil, kesin bir gerekliliktir.

Her kiracı kuruluş, veritabanı düzeyinde diğer tüm kiracılardan yalıtılmış olmalıdır.

Yaklaşım

Platform üç çalışma ekseni hâlinde ayrılır: doğruluk kaynağı olan bir Spring Boot kimlik çekirdeği, tüm biyometrik işlemeye sahip özel bir FastAPI ML yan-süreci ve ince istemciler (React web, Kotlin Multiplatform mobil ve masaüstü ile gömülebilir bir widget). Widget, tüm meydan okuma akışını reCAPTCHA'nın bir meydan okumayı sunduğu gibi sunar.

Önemli kararlar

ML yan-sürecini kimlik çekirdeğinden ayrı bir dağıtılabilir olarak ayır

Biyometrik işlemci API ile yalnızca özel bir Docker ağı üzerinden konuşur ve asla halka açık değildir. ML yığını API'ye dokunmadan yükseltilebilir ve gömme çıkarımı internetten yapısal olarak erişilemezdir.

Kiracı yalıtımını RLS ve uygulama katmanı filtrelemesiyle veritabanı düzeyinde zorla

Çok kiracılılık, paylaşımlı şema üzerinde PostgreSQL Satır Düzeyi Güvenliği (RLS) ve Hibernate @Filter kombinasyonuyla sağlanır; her kiracı kapsamlı tabloda tenant_id sütunları bulunur. Bir sorgunun görmemesi gereken verilere ulaşması için her iki katmanın da aynı fikirde olması gerekir.

Gömme şifreleme anahtarı eksik olduğunda hızlı başarısız ol

Gömmeler bekleme hâlinde Fernet ile şifrelenir ve yalnızca kosinüs benzerliği çalıştığı anda süreç içinde çözülür. Uygulama anahtar olmadan açılmayı reddeder; böylece her saklı gömmeyi geçersiz kılacak bir varsayılana sessizce geri dönemez.

Mimari

Tarayıcılar ve mobil istemciler, bir Traefik ters proxy'si üzerinden Spring Boot kimlik çekirdeğine ulaşır. Kimlik çekirdeği, pgvector'lü PostgreSQL'e sahiptir ve FastAPI biyometrik işlemcisiyle halka açık internetin erişemediği özel bir Docker ağı üzerinden konuşur. Loki, Promtail ve Grafana tüm yığını gözlemler.

flowchart TB
  client["Clients<br/>React web · KMP mobile/desktop · embeddable widget"]
  traefik["Traefik reverse proxy"]
  api["Identity Core API<br/>Spring Boot 3 · Java 21"]
  db[("PostgreSQL<br/>+ pgvector")]
  ml["Biometric Processor<br/>FastAPI · Python"]
  obs["Loki · Promtail · Grafana"]

  client --> traefik --> api
  api --> db
  api -. private docker network .-> ml
  api --> obs
  ml --> obs

Bir Traefik proxy'sinin arkasında üç çalışma ekseni; ML yan-süreci yalnızca özel ağdadır.

Sonuç

FIVUCSAS, gömülebilir bir widget, WebAuthn/FIDO2 passkey'leri ve ekran tekrarını ve önceden kaydedilmiş saldırıları savuşturan rastgele bir aktif canlılık meydan okumasıyla, kendi kendine barındırılan çok kiracılı bir platform olarak canlıda çalışır. Depo, üçüncü taraf güvenlik incelemesi tamamlanana dek özeldir; kaynak erişimi talep üzerine mümkündür.

Rakamlarla

85 Flyway migrasyonları (V1'den V86'ya)

13 users satırının ardındaki FK-kademeli tablo

3 Çalışma ekseni (API · ML · istemciler)

Fernet Bekleme hâlinde gömme şifrelemesi

SHA-256 Model teslim bütünlüğü

WebAuthn, TOTP, NFC, OTP Desteklenen kimlik doğrulama yöntemleri

Aşağıdaki yapılandırılmış bölümler Türkçe mevcuttur; ayrıntılı anlatım İngilizce yazılmıştır. Tam Türkçe çeviri henüz mevcut değildir.

FIVUCSAS (Face and Identity Verification Using Cloud-based SaaS) started as a three-person Marmara University senior project (CSE4297/CSE4197) and now ships under RollingCat Software. I led it and built the Spring Boot 3 / Java 21 identity core, the React 18 web app, the ML integration, and the infrastructure. Ayşenur Arıcı built the anti-spoofing and liveness ML algorithms. Ayşe Gülsüm Eren worked across the Kotlin Multiplatform mobile and desktop apps, liveness tuning, the gesture-analysis module, NFC passport reading, and UX. For a deeper technical walkthrough, see the companion write-up.

The shape of the system

Two constraints drove most design decisions: biometric data must never sit unencrypted at rest, and embedding extraction must never be reachable from the public internet.

Those constraints are why the ML stack lives in a separate FastAPI sidecar on a private Docker network rather than inside the Spring Boot API. The identity core is the authoritative source of truth for tenants, users, sessions, audit logs, and MFA factors (TOTP, WebAuthn, NFC, biometric). The biometric processor owns the face mesh, embedding extraction, and active-liveness puzzle scoring, and it answers only to the API, never to a browser.

Active liveness

The “Biometric Puzzle” prompts a randomized sequence of facial actions (smile, blink, look left, look right) rather than accepting a single still frame that a photo or screen replay could defeat. The randomization makes a pre-recorded attack impractical because the attacker cannot know the sequence in advance. The widget exposes this flow the way reCAPTCHA exposes a challenge, so a tenant integrates against the smallest possible surface. Active liveness is flag-gated.

Tenancy and privacy

Multi-tenancy uses a shared schema with PostgreSQL Row-Level Security (RLS) and a Hibernate @Filter, backed by tenant_id columns on every tenant-scoped table. Both layers must agree before a query can reach another tenant’s data.

Face embeddings are encrypted with Fernet at rest in pgvector and decrypted in-process only at the moment cosine similarity runs. The application refuses to start without the embedding encryption key, so it can never silently fall back to an invalid state.

Operational posture

The platform runs on a Hetzner CX43 box behind Traefik, observed with Loki, Promtail, and Grafana, with nightly encrypted database backups. Security hygiene is part of the workflow: GitHub secret-scanning with push-protection is on, and every new OAuth endpoint gets a permitAll-chain review as part of PR review.

The source is private until a third-party security review completes. Source access is available on request.

Yığın