DurumEN
BaşlarkenPayment OrchestratorCüzdanBanka HesaplarıSigortaFraud & Fraud AIIdentitySanctionAutomationSDKDemo
Identity
Assertion & JWKS

Identity Assertion & JWKS

Bir analyze / analyze-sync çağrısı, snapshot'ın yanında imzalı bir identity assertion döndürebilir: identity verdict'ini taşıyan ve Identity tarafından kriptografik olarak imzalanmış kompakt bir JWT (typ: "identity_assertion"). Amacı inkâr-edilemezliktir (non-repudiation) — sizinle hiçbir secret paylaşmayan bir üçüncü taraf, bu verdict'i Identity'nin ürettiğini ve değiştirilmediğini bağımsız olarak doğrulayabilir. Doğrulama, public bir JWKS endpoint'ine karşı yapılır.

Assertion, Identity'nin her zaman döndürdüğü aynı kanıt-derece verdict'ini taşır (identityRiskLevel ve destekleyici alanlar) — yeni bir karar eklemez. Eklediği şey kanıtlanabilirliktir: herkesin kontrol edebileceği bir imza.

Ne zaman kullanılır

İmzalı bir assertion'a, çağıranın dışındaki bir tarafın verdict'e size güvenmeden güvenmesi gerektiğinde başvurun:

  • Bir identity kararının gerçekten Identity tarafından üretildiğini doğrulayan bir regülatör ya da denetçi.
  • Identity verdict'ini tüketen ve üzerine aksiyon almadan önce bunu bağımsız olarak teyit etmesi gereken bir alt-akış payment-fraud ya da risk servisi.
  • "Merchant, Identity'nin X dediğini söylüyor" ifadesinin yeterli olmadığı ve alıcının imzayı bizzat kontrol etmek istediği her servisler-arası sınır.

Doğrulama public bir anahtar kullandığı için, doğrulayıcının paylaşılan bir secret'a ve size dönük canlı bir çağrıya ihtiyacı yoktur — yalnız assertion ve public JWKS yeter.

Doğrulanabilir assertion'lar için asimetrik imzalama gerekir

⚠️

Varsayılan olarak IDENTITY_ASSERTION_ALG HS256'dır — public doğrulanabilir anahtar üretmeyen simetrik (paylaşılan-secret) bir algoritma. Bu varsayılan durumda public JWKS endpoint'i boş bir anahtar seti ({ "keys": [] }) döndürür ve üçüncü tarafın karşısında doğrulayacağı bir şey yoktur.

Doğrulanabilir bir assertion, asimetrik imzalamanın (ES256 / RS256) yapılandırılmasını gerektirir. Bir asimetrik anahtar yapılandırıldığında, analyze imzalı bir assertion üretebilir ve JWKS endpoint'i eşleşen public anahtarı yayımlar.

Yani dürüst tablo iki durumludur:

Yapılandırmaanalyze'daki assertionjwks.jsonÜçüncü-taraf doğrulaması
Varsayılan (HS256, simetrik)Public doğrulanabilir değil{ "keys": [] }Paylaşılan secret olmadan mümkün değil
Asimetrik yapılandırılmış (ES256 / RS256)İmzalı assertion dönerPublic anahtar yayımlanırHerkes JWKS'e karşı doğrulayabilir

JWKS endpoint'i

GET /identity/.well-known/jwks.json — public, unauthenticated, 300 sn cache'lenebilir, * CORS. Identity assertion'larını imzalayan public anahtarları standart JWK Set biçiminde yayımlar:

{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "kid": "id-assert-2026-07",
      "use": "sig",
      "alg": "ES256",
      "x": "…",
      "y": "…"
    }
  ]
}

Boş bir { "keys": [] }, asimetrik imzalama yapılandırılmadığında geçerli ve beklenen bir yanıttır — doğrulanabilir assertion'ların şu an etkin olmadığının işaretidir, bir hata değil.

Bir assertion'ı doğrulama

Assertion standart bir JWT'dir: header'ındaki kid'i JWKS'teki bir anahtarla eşleştirin, ardından imzayı o public anahtarla doğrulayın. Uyumlu herhangi bir JWT kütüphanesi işe yarar — örnek jose kullanıyor.

import { createRemoteJWKSet, jwtVerify } from 'jose';
 
// Public anahtarları çeker + cache'ler; anahtarı assertion'ın `kid`'ine göre seçer
const JWKS = createRemoteJWKSet(
  new URL('https://api-gateway.lunixi.com/api/v1/identity/.well-known/jwks.json'),
);
 
async function verifyAssertion(assertion) {
  const { payload, protectedHeader } = await jwtVerify(assertion, JWKS, {
    // kabul ettiğiniz algoritmalar — asimetrik olmalı
    algorithms: ['ES256', 'RS256'],
  });
 
  // typ, bunu bir identity assertion'a sabitler
  if (protectedHeader.typ !== 'identity_assertion') {
    throw new Error('identity assertion değil');
  }
 
  // payload artık doğrulanmış identity verdict'ini taşır
  // ör. payload.identityRiskLevel, payload.subjectId, payload.traceId
  return payload;
}

Assertion'ı alın

analyze / analyze-sync çağırın (bkz. Sunucu API & Sorgular). Asimetrik imzalama yapılandırıldığında yanıt imzalı assertion'ı içerir; onu doğrulaması gereken tarafa verin.

Public anahtarları çekin

Doğrulayıcı GET /identity/.well-known/jwks.json'u çeker (en fazla 300 sn cache'ler) ve kid'i assertion header'ıyla eşleşen anahtarı seçer.

Doğrulayın

JWT imzasını o public anahtara karşı doğrulayın, kabul edilen algorithms'i asimetrik sete kısıtlayın ve typ: "identity_assertion"'ı kontrol edin. Başarılıysa, payload'ın verdict'inin Identity'den, değiştirilmeden geldiği kanıtlanmış olur.

Notlar

  • Public, secret yok. JWKS unauthenticated ve cache'lenebilirdir (300 sn); doğrulama asla paylaşılan bir secret ya da size dönük bir çağrı gerektirmez.
  • Etkinleştirmek için yapılandırın. Varsayılan HS256 altında assertion'lar üçüncü-taraf doğrulanabilir değildir ve JWKS boştur — bir anahtar yayımlamak ve doğrulanabilir assertion üretmek için asimetrik imzalamayı (ES256 / RS256) yapılandırın.
  • Tipi sabitleyin. Doğrularken her zaman typ: "identity_assertion"'ı kontrol edin ve kabul edilen algoritmaları asimetrik sete kısıtlayın.

Sonraki adımlar

Sunucu APIGenel Bakış