Güvenen taraf uygulaması

Sitenizde e-posta doğrulamayı uygulamak için form işaretlemenizi güncelleyerek jeton isteyin ve gelen jetonlar için sunucu tarafı doğrulama ekleyin.

Kaynak denemesine kaydolma

Doğrulama sitelerinde kaynak denemesinin yapılandırılmış olması gerekir.

kaydınızı yenileyin ve güncellenen jetonu dağıtın.

Chrome 154'ten itibaren üçüncü taraf kaynak denemeleri önemli bir uyarıyla desteklenmektedir: Deneme için kayıtlı kaynak, verenle aynı site olmalıdır. Örneğin:

  • Veren alan adı: issuer.example
  • OT kaydedeni: https://issuer.example
  • JavaScript kaynağı: https://issuer.example (veya alt alan adı eşleşmesiyle https://app.issuer.example)

Form alanlarını yapılandırma

E-posta gönderim formunuza gizli bir jeton alanı ekleyin:

<input
  type="email"
  name="email-address"
  autocomplete="email">
<input
  type="hidden"
  name="token"
  autocomplete="email-verification-token"
  nonce="rAnD0m-VaLuE">

Alan koşulları:

  • E-posta alanı: Chrome'un adresi otomatik doldurabilmesi ve tanıyabilmesi için type="email" ve autocomplete="email" değerlerini ayarlayın.
  • Jeton alanı özellikleri:
    • Set autocomplete="email-verification-token": Chrome, gönderim sırasında jetonu doldurmak için bu alanı tanımlar.
    • nonce="<VALUE>" ayarlanmalıdır: Site, form gönderimini doğrulamak için oturuma bağlı benzersiz bir nonce sağlamalıdır.

E-posta doğrulama jetonunu (EVT) doğrulama

Kullanıcı formu gönderdiğinde sunucunuz, e-posta adresini ve gizli alandaki jetonu alır. Boş bir jeton alanı, tarayıcının veya sağlayıcının EVP'yi desteklemediğini ya da kullanıcının doğrulamayı atladığını gösterir. Bu durumda, OTP veya sihirli bağlantı gönderme gibi mevcut doğrulama sürecinize geri dönün.

Jeton varsa aşağıdaki şekilde doğrulayın:

  1. SD-JWT kitaplığı kullanarak jetonu ayrıştırın.
  2. Beklenen değerleri ve oturum taleplerini doğrulayın.
  3. DNS yetkilendirmesini doğrulayın.
  4. Düzenleyen meta verilerini keşfedin ve JWKS'yi getirin.
  5. Kriptografik imzaları ve anahtar bağlamayı doğrulayın.

1. Jetonu ayrıştırma

Jeton, RFC 9901: Selective Disclosure JWT (SD-JWT+KB) biçimini kullanır. Jetonu ayrıştırmak ve doğrulamak için platformunuza uygun kitaplıkları kullanın. Örneğin, Node için @sd-jwt/core ve jose kullanabilirsiniz. Ham hâli şu şekildedir: Veren tarafından imzalanmış bir JWT, ardından sıfır veya daha fazla açıklama ve her bileşenin tilde ile ayrıldığı bir anahtar bağlama JWT'si ile biter:

<Issuer-signed EVT>~<Disclosure 1>~...~<Disclosure N>~<Key Binding JWT>

Mevcut uygulamada jeton sıfır açıklama (<Issuer-signed EVT>~<Key Binding JWT>) içerir. Ancak bu durum gelecekte değişebilir.

Kitaplıkla jetonun kodunu çözün:

import { decodeSdJwtSync } from "@sd-jwt/core";
import { createHash } from "node:crypto";
const hasher = (data, alg) =>
  createHash(alg === "sha-256" ? "sha256" : alg)
    .update(data)
    .digest();
const decoded = decodeSdJwtSync(rawToken, hasher);
const evtPayload = decoded.jwt.payload;
const kbPayload = decoded.kbJwt?.payload;

verifier.example, demo@provider.example kimliğini doğrularsa kodu çözülen jeton aşağıdakine benzer:

{
  "evtJwtDecodedHeader": {
    "typ": "evt+jwt",
    "alg": "EdDSA",
    "kid": "issuer-key-id"
  },
  "evtJwtDecodedPayload": {
    "iss": "https://provider.example",
    "iat": 12345678901,
    "exp": 12345679901,
    "cnf": {
      "jwk": {
        "kty": "OKP",
        "crv": "Ed25519",
        "x": "pUbLiCkEy123pUbLiCkEy123pUbLiCkEy123"
      }
    },
    "email": "demo@provider.example",
    "email_verified": true
  },
  "kbJwtDecodedHeader": {
    "alg": "EdDSA",
    "typ": "kb+jwt"
  },
  "kbJwtDecodedPayload": {
    "aud": "https://verifier.example",
    "iat": 12345678901,
    "nonce": "rAnDoM123rAnDoM123rAnDoM123rAnDoM123",
    "sd_hash": "hAsH456hAsH456hAsH456hAsH456hAsH456"
  },
  "disclosures": []
}

2. Beklenen değerleri ve oturum iddialarını doğrulama

Yükteki temel değerlerin sağladığınız ve beklediğiniz değerlerle eşleştiğini kontrol edin:

  • email_verified: true olmalıdır.
  • email: Formda gönderilen e-posta adresiyle eşleşmelidir.
  • aud (kitle): Sitenizin kaynağıyla eşleşmelidir.
  • nonce: Formunuzda sağlanan tek seferlik rastgele sayıyla eşleşmelidir.
  • iat (verildiği zaman) ve exp (geçerlilik bitişi): Jetonun geçerli zaman aralığında olduğunu ve süresinin dolmadığını onaylayın.

3. DNS temsilini doğrulama

E-posta adresinin alan adı için _email-verification DNS kaydını doğrulayın. Örneğin, demo@gmail.com için _email-verification.gmail.com TXT kaydını sorgulayın. Bu sağlayıcı için sorgu, hesap sağlayıcının konumunu (accounts.google.com) döndürür.

$ dig +short TXT _email-verification.gmail.com
"iss=accounts.google.com"

Veren şemasının https:// olduğunu ve https://<domain> değerinin EVT'deki iss talebiyle eşleştiğini doğrulayın.

4. EVT imzasını doğrulama

Verenin keşif meta verilerini şuradan alın: https://<issuer>/.well-known/email-verification:

{
  "issuer": "https://accounts.google.com",
  "issuance_endpoint": "https://accounts.google.com/gsi/email-verification/issue",
  "jwks_uri": "https://verifiablecredentials-pa.googleapis.com/.well-known/vc-public-jwks",
  "signing_alg_values_supported": ["Ed25519", "EdDSA"]
}

Meta verilerde issuer alanı varsa EVT bayt bayt olarak iss talebiyle eşleştiğini doğrulayın. jwks_uri adresinden JSON Web Anahtarı Kümesi'ni getirin.

Jeton paketini doğrulamak için SD-JWT kitaplığınızı kullanın. Kitaplık, doğrulama işlemini koordine eder:

  1. EVT'deki veren imzasını getirilen JWKS'ye göre doğrulama.
  2. cnf.jwk içindeki kısa ömürlü ortak anahtarı kullanarak KB-JWT'deki tarayıcı imzasını doğrulama.
  3. Anahtar bağlama (aud, nonce ve özet karma sd_hash) doğrulanıyor.

Node.js'de örnek doğrulama mantığı:

import { SDJwtInstance } from "@sd-jwt/core";
import { importJWK, compactVerify } from "jose";
import { createHash } from "node:crypto";
const allowedAlgs = ["Ed25519", "EdDSA", "ES256"];
const evtAlg = decoded.jwt.header.alg;
const kbAlg = decoded.kbJwt?.header.alg;
if (!allowedAlgs.includes(evtAlg) || !allowedAlgs.includes(kbAlg)) {
  throw new Error("Unsupported signing algorithm");
}
const hasher = (data, alg) =>
  createHash(alg === "sha-256" ? "sha256" : alg)
    .update(data)
    .digest();
const sdJwt = new SDJwtInstance({ hasher });
sdJwt.config({
  hasher,
  // Verifier for the Issuer-signed EVT
  verifier: async (data, sig) => {
    const token = `${data}.${sig}`;
    const header = decoded.jwt.header;
    // Match by kid if present, or iterate across matching algorithm keys
    const keysToTry = header.kid
      ? jwksData.keys.filter(k => k.kid === header.kid)
      : jwksData.keys;
    for (const jwk of keysToTry) {
      try {
        const pubKey = await importJWK(jwk, jwk.alg || evtAlg);
        await compactVerify(token, pubKey);
        return true;
      } catch {
        // Try next candidate key
      }
    }
    return false;
  },
  // Verifier for the Key Binding JWT (KB-JWT)
  kbVerifier: async (data, sig) => {
    try {
      const browserJwkKey = evtPayload.cnf?.jwk;
      if (!browserJwkKey) return false;
      const pubKey = await importJWK(browserJwkKey, kbAlg);
      await compactVerify(`${data}.${sig}`, pubKey);
      return true;
    } catch {
      return false;
    }
  },
});
// The library automatically verifies EVT signature, KB-JWT signature, audience, nonce, and sd_hash
const result = await sdJwt.verify(rawToken, {
  kb: {
    expectedNonce: sessionNonce,
    expectedAudience: "https://example.com",
    required: true,
  },
});
const verifiedPayload = result.payload;
if (
  verifiedPayload.email_verified !== true ||
  verifiedPayload.email?.toLowerCase() !== submittedEmail.toLowerCase()
) {
  throw new Error("Token email does not match submitted email");
}

Tüm adımlar başarılı olursa e-posta adresini sağlayıcıya karşı doğrulamış olursunuz. Doğrulama başarısız olursa normal akışınızı kullanarak kullanıcıya onay e-postası gönderme yöntemine geri dönün.

Sorun giderme

Doğrulama başarısız olursa veya tarayıcı jeton sağlamazsa aşağıdaki yaygın sorunları kontrol edin:

Gönderim sırasında jeton alanı boş

  • Kaynak denemesi kaydı: Origin-Trial başlığının veya <meta> etiketinin sayfada yayınlandığını ve jetonun geçerlilik süresinin dolmadığını doğrulayın (Chrome 160 uzantısından önce oluşturulan jetonların geçerlilik süresi 17 Kasım 2026'da sona erer). Üçüncü taraf kaynak denemeleri (Chrome 154 ve sonraki sürümler) için kayıtlı deneme kaynağı, verenle aynı site olmalıdır (https://<issuer-domain>). Bir sitedeki kaynak denemesi durumunu ve jetonun geçerlilik bitimini Geliştirici Araçları'nda Uygulama > Çerçeveler > (ilgili çerçeveyi seçin) > Kaynak denemeleri bölümünde inceleyebilirsiniz.
  • Form işaretlemesi: Hem <input type="email" autocomplete="email"> hem de <input type="hidden" autocomplete="email-verification-token" nonce="..."> aynı <form> öğesinde olmalı (Shadow DOM sınırları arasında izole edilmemeli) ve nonce boş olmamalıdır.
  • Erken gönderim veya yeniden kullanılan sayfa: Tarayıcı, e-posta girildikten veya otomatik olarak doldurulduktan sonra arka planda jetonu getirir. İstek tamamlanmadan gönderilen jeton boş kalır. Kullanıcı, e-posta adresini girdikten sonra formu göndermek için Return tuşuna basarsa bu durum yaşanabilir.
  • Tarayıcı ve sağlayıcı ön koşulları: Kullanıcı, aynı tarayıcı profilinde katılımcı bir sağlayıcıda oturum açmış olmalı ve Chrome ayarlarında (chrome://settings/contactInfo) Doğrulanmış E-posta etkin olmalıdır.

Kartı veren kuruluşun imzası doğrulanamıyor

  • kid üstbilgisi eksik: EVT üstbilgisindeki ve JWKS'deki kid (Anahtar Kimliği) talebi isteğe bağlıdır (örneğin, Gmail kid'ı atlar). kid yoksa anahtar kimliği araması başarısız olmak yerine, veren kuruluşun jwks_uri'sındaki tüm aday anahtarlar arasında yineleme yapın.
  • Algoritma tanımlayıcıları (Ed25519 ve EdDSA): Chrome 156'dan itibaren Chrome, cnf.jwk ve KB-JWT başlıkları için tam olarak belirtilen Ed25519 algoritma tanımlayıcısını (RFC 9864) kullanır. Verenler ve kitaplıklar ise Ed25519 veya EdDSA (ES256 ile birlikte) belirtebilir. JWK içe aktarma ve doğrulama mantığınızın her iki tanımlayıcıyı da kabul ettiğinden emin olun.
  • Veren (iss) kaynak biçimi: DNS TXT kaydı (_email-verification.<domain>) yalın bir ana makine adı (iss=accounts.issuer.example) içerirken EVT iss hak talebi tam bir HTTPS kaynağıdır (https://accounts.issuer.example, sonunda eğik çizgi yoktur). Karşılaştırmadan önce DNS kaydı değerine https:// ön ekini ekleyin.

Anahtar bağlama (KB-JWT) doğrulaması başarısız oluyor

  • Eşleşmeyen veya süresi dolmuş nonce: <input> içinde oluşturulan nonce öğesinin, sunucunuzdaki etkin oturum nonce'uyla eşleştiğinden ve başka bir sekme tarafından üzerine yazılmadığından ya da önceki bir istek tarafından tüketilmediğinden emin olun.
  • Kitle (aud) uyuşmazlığı: aud hak talebi, doğrulayıcının HTTPS kaynağıdır (https://verifier.example, yol veya sondaki eğik çizgi olmadan).

E-posta talebi (email) karşılaştırması başarısız oluyor

  • Büyük/küçük harf kullanımı ve standartlaştırma: Chrome 156 ve sonraki sürümlerde email talebi, formda girildiği gibi bayt bayt döndürülür. Ancak daha eski tarayıcı sürümleri veya sağlayıcılar, standartlaştırılmış bir adres (örneğin, first.last@example.com için First.Last@example.com) döndürebilir. Jetonun email talebini gönderilen form değeriyle eşleştirirken büyük/küçük harfe duyarlı olmayan bir karşılaştırma kullanın.