Auth

PrimDB Auth, deploy ettiğin uygulamanın son kullanıcılarını doğrular. Proje bazında açarsın. O andan sonra kayıt, giriş, oturum, organizasyon ve kurumsal SSO işini PrimDB üstlenir, kullanıcı kayıtlarının kendisi ise projenin kendi Postgres’inde durur. Hesap açman gereken ayrı bir auth sağlayıcısı yok, veritabanının dışında duran bir kullanıcı dizini de yok.

Kullanıcı verisi nerede durur

Auth’u açtığında projenin Postgres’inde auth_* tabloları oluşur. Bunlar veritabanındaki sıradan tablolardır: okursun, kendi şemanla join edersin, yedeklerine de her şeyle birlikte girerler.

Dürüst not. Auth’u kapatmak control-plane yapılandırmasını ve enjekte edilen env değişkenlerini kaldırır, tabloları yerinde bırakır: içlerindeki satırlar senin verin. Tekrar açtığında aynı tablolar kullanılır.

Nasıl açılır

Auth’un bu tabloları koyacak bir yere ihtiyacı var, o yüzden projede hazır bir Postgres servisi bulunmalı. O varken panelden açarsın ya da bir ajanın enable_auth MCP aracını çağırmasını istersin. Açma işlemi idempotenttir: tabloları kurar, projenin imzalama anahtarını üretir, PRIMDB_PROJECT_ID ve PRIMDB_AUTH_URL değişkenlerini uygulamanın ortamına enjekte eder.

Sonrası arka uç SDK’sı. @primdb/auth-node npm’de 0.2.0 sürümüyle yayında ve framework bağımsız: Hono, Express, Fastify, Next.js route handler’ları.

import { createPrimDBAuth } from '@primdb/auth-node';

export const auth = createPrimDBAuth({
  projectId: process.env.PRIMDB_PROJECT_ID!, // injected when you enable auth
  baseUrl: process.env.PRIMDB_AUTH_URL,      // injected too
});

Giriş yöntemleri

Altı giriş yolu var. Bir projenin hangilerini sunduğu panelden ya da MCP üzerinden değiştirilen bir ayardır, yani bugün tek yöntemle çıkıp sonra entegrasyona dokunmadan bir tane daha ekleyebilirsin.

Yönlendirme tabanlı iki yöntem aynı kalıbı paylaşır. signIn.oauth ve signIn.saml, proje için kayıtlı bir origin olmak zorunda olan redirectTo alır. Bu değer allowlist’e karşı denetlendiği için akış açık yönlendirmeye çevrilemez. Kullanıcı geri döndüğünde URL’de tek kullanımlık bir primdb_oauth_code taşır, completeOAuth onu oturuma çevirir.

Etkileşimli her giriş, oturum yerine bir MFA sorusu döndürebilir. Bir kez dallandırırsın, bütün yöntemleri kapsamış olursun.

import { isMfaChallenge } from '@primdb/auth-node';

const result = await auth.signIn.emailPassword({ email, password });

if (isMfaChallenge(result)) {
  // No session yet. Prompt for a TOTP code or a single-use recovery code.
  const { session } = await auth.verifyMfa({ mfaToken: result.mfaToken, code });
  return session;
}

return result.session;

Oturumlar ve istek doğrulama

Tamamlanan bir giriş sana bir kullanıcı ve bir oturum verir: kısa ömürlü bir access token ile bir refresh token. Access token, projenin kendi anahtar çiftiyle imzalanmış bir ES256 JWT’dir, arka ucun onu eşleşen açık anahtarla doğrular. Ortamına kopyalaman gereken bir sır yok.

validateRequest bir Fetch Request nesnesini, bir Node isteğini ya da düz bir { authorization } nesnesini kabul eder, oturumu veya null döner. Projenin açık anahtarını ilk çalıştığında GET /auth/v1/jwks/:projectId adresinden çeker, sonrasında yerel doğrular. Sıcak yol ağ isteği ödemez.

// Hono
app.get('/me', async (c) => {
  const session = await auth.validateRequest(c.req.raw);
  if (!session) return c.json({ error: 'unauthorized' }, 401);
  return c.json({ userId: session.userId, orgId: session.orgId ?? null });
});

// Express
app.get('/me', async (req, res) => {
  const session = await auth.validateRequest(req);
  if (!session) return res.status(401).json({ error: 'unauthorized' });
  res.json({ userId: session.userId });
});

Oturum ömrünün kalanı üç çağrı. refreshSession refresh token’ı taze bir oturumla takas eder, signOut mevcut oturumu kapatır, all: true ile çağrılan signOut kullanıcının bütün oturumlarını kapatır. Yönetim tarafından tek bir oturumu ya da hepsini iptal edebilirsin. Projenin auth sırrını döndürmek ise canlı bütün access token’ları bir anda geçersiz kılar.

Arka ucun Node değilse aynı JWKS ucunu, dilinde hazır duran JWT kütüphanesiyle doğrula. Entegrasyon sözleşmesinin tamamı bu.

Organizasyonlar

Takımlar yerleşik geliyor, yani B2B bir uygulamanın bunu sıfırdan modellemesi gerekmiyor. auth.orgs.create çağıranı sahip yaparak bir organizasyon açar, invite tek kullanımlık kabul bağlantısını e-postayla yollar, acceptInvite onu bozdurur. Günlük işi members, setRole, removeMember, invitations ve revokeInvitation görür, remove ise organizasyonu siler.

Asıl anlaşılması gereken parça auth.orgs.switch. Access token’ı aktif organizasyonu taşıyan yepyeni bir oturum döner, böylece validateRequest route handler’ına kullanıcı id’sinin yanında organizasyonu ve rolü de verir, ek sorgu olmadan. orgId: null geçersen kişisel oturuma dönersin. Üyelik ve rol her organizasyon çağrısında sunucuda yeniden denetlenir, bu yüzden eski bir token’daki bayat iddia kullanıcının gerçek yetkisinden fazlasını açmaz.

Müşterilerin için SAML

Uygulama seviyesi SAML, bir müşterinin kendi kimlik sağlayıcısıyla giriş yapmasını sağlar. SSO eklentisini ister, ayda sabit $30, bir de panelden ya da set_auth_saml MCP aracıyla kurduğun bağlantıyı: IdP entity id’si, SSO URL’i ve imzalama sertifikası. Servis sağlayıcı koordinatların GET /auth/v1/saml/:projectId/metadata adresinden gelir, assertion’lar POST /auth/v1/saml/:projectId/acs adresine düşer. Giriş signIn.saml ile başlar ve sosyal girişteki completeOAuth takasıyla biter.

Dürüst not. Bu, yayına aldığın uygulamanın son kullanıcıları için SAML. Kendi ekibini PrimDB’ye sokmak ayrı bir ayardır, SSO / SAML sayfasında anlatılıyor.

Webhook’lar

Bir uç kaydedersin, PrimDB auth olaylarını oraya gönderir. Böylece uygulaman bir kaydı ya da hesap silmeyi yoklamaya gerek kalmadan yakalar. Webhook oluşturmak imzalama sırrını tam bir kez döner, o an saklaman gerekir, çünkü sunucuda yalnız özeti tutulur. İsteğe bağlı olay filtresi neyin iletileceğini daraltır, URL her kurulduğunda veya değiştiğinde SSRF koruması denetler, sırrı sonradan döndürebilir ya da ucu silebilirsin.

Günlük yönetim

Operatörün yaptığı her iş panelde var, aynı işler MCP aracı olarak da duruyor, yani bir ajan senin yerine yapabilir:

• Bir projede auth’u aç ya da kapat, ayarlarını güncelle.
• Son kullanıcıları arama, filtre ve sayfalama ile listele.
• Bir kullanıcıyı askıya al ya da sil.
• Tek bir oturumu ya da kullanıcının bütün oturumlarını iptal et.
• Projenin auth sırrını döndür.
• OAuth sağlayıcılarını ve SAML bağlantısını yapılandır.
• Auth webhook’ları oluştur, güncelle, sırrını döndür, sil.

Bir kullanıcıyı askıya almak canlı oturumlarını da iptal eder, yani elindeki token’ın süresi dolana kadar beklemeden anında dışarıda kalır.

Kullanıcılarını SQL ile sorgulama

Tablolar sende olduğu için, normalde destek talebi açacağın sorular düz SQL’e dönüşür ve doğrudan kendi şemanla join edilir.

-- Every org membership, most recently active people first
select o.name as org, m.role, u.email, u.last_sign_in_at
from auth_orgs o
join auth_org_members m on m.org_id = o.id
join auth_users u on u.id = m.user_id
where u.status = 'active'
order by u.last_sign_in_at desc nulls last;

-- Which social providers people actually use
select provider, count(*) as accounts
from auth_oauth_accounts
group by provider
order by accounts desc;

REST API

SDK, düz bir HTTP API’nin ince sarmalayıcısı. Mobil bir istemci ya da başka bir dilde yazılmış bir servis onu doğrudan çağırabilir. Taban yol, uygulamana enjekte edilen auth URL’i üzerinde /auth/v1, toplam 42 rota, ve her istek projeyi X-PrimDB-Project-Id başlığıyla bildirir.

Dürüst not. Henüz burada olmayanlar. Yayınlanmış tek SDK @primdb/auth-node: repoda bir React paketi, bir Python istemcisi ve bir Go istemcisi duruyor ama kayıt defterlerinde olmadıkları için bugün kuramazsın. Node SDK’sında passkey yardımcısı da yok, çünkü passkey kaydı ve girişi tarayıcıda oluyor, onları yukarıdaki REST rotalarından sürersin. Bütün bunlar uygulamanın son kullanıcıları için auth, kendi PrimDB girişin için değil.