E-posta sağlayıcı (düzenleyen) uygulaması

Daha fazla bilgi için sahte e-posta sağlayıcı demo kodunu inceleyebilir ve E-posta Doğrulaması API ile E-posta Doğrulaması Protokolü tekliflerindeki veren adımlarına bakabilirsiniz.

Tarayıcı davranışını tetikleyen taraf güvenen taraf sitesi olduğundan, veren olarak, deneme sürecine kaydolmanız veya jeton sağlamanız gerekmez. Uç noktalarınızın bu isteklere yanıt verecek şekilde yapılandırıldığından emin olun.

Kart sağlayıcı keşfini yapılandırma

Tarayıcıların, alanınıza ait bir e-posta adresi seçildiğinde doğrulama uç noktalarınızı otomatik olarak keşfetmesine izin vermek için DNS ve .well-known HTTP uç noktası kullanarak yapılandırmanızı kullanıma sunun.

DNS yetki kaydını yapılandırma

E-posta alanınızda, doğrulama yetkisini veren tanımlayıcınıza devreden bir DNS TXT kaydı yapılandırın. Bu tanımlayıcılar, altyapınıza bağlı olarak aynı alanı kullanabilir.

Kayıt biçimi: _email-verification.<email-domain>

Örnek Alan Dosyası:

_email-verification.example.com IN TXT "iss=accounts.issuer.example"

iss= değeri; şema (https://), bağlantı noktası, yol veya büyük harf içermeyen, yalın, standart ve küçük harfli bir ana makine adı (ör. iss=accounts.issuer.example) olmalıdır. Chrome, ana makine adı olmayan bileşenler içeren kayıtları reddeder.

.well-known/email-verification uç noktası barındırma

Düzenleyen alanınızda /.well-known/ yolu altında bir JSON meta veri dosyası barındırın. Bu dosyada, sertifika verme özellikleriniz ve altyapınızın desteklediği kriptografik imzalama algoritmaları açıklanır.

Uç nokta: https://<issuer-domain>/.well-known/email-verification

Örnek yanıt:

{
  "issuer": "https://accounts.issuer.example",
  "issuance_endpoint": "https://accounts.issuer.example/email-verification/issuance",
  "jwks_uri": "https://accounts.issuer.example/.well-known/vc-public-jwks",
  "signing_alg_values_supported": ["Ed25519", "EdDSA", "ES256"]
}

Meta veri özellikleri:

  • issuer: Veren kuruluş kaynağınız (https://<issuer-domain>, sonunda eğik çizgi olmadan). Meta veri dosyasının sunulduğu kaynakla bire bir eşleşmelidir.
  • issuance_endpoint: Jeton verme POST isteklerini alan HTTPS URL'si.
  • jwks_uri: Herkese açık JSON Web Anahtarı Kümenizi (JWKS) sunan HTTPS URL'si.
  • signing_alg_values_supported: Desteklenen JWS imzalama algoritmaları dizisi.

.well-known/web-identity uç noktası barındırma

Federated Credentials (FedCM) API kapsamında ek bir .well-known JSON kaynağı uygulamış olabilirsiniz. Bu kaynak, hesap uç noktanızın ve giriş URL'nizin bağlantılarını sağlar.

Uç nokta: https://<domain>/.well-known/web-identity

Örnek yanıt:

{
  "accounts_endpoint": "https://accounts.issuer.example/accounts",
  "login_url": "https://accounts.issuer.example/login"
}

Hesap uç noktası kullanma

FedCM API'deki hesaplar uç noktası, şu anda oturum açılmış hesapların listesini sağlar. Aşağıdaki örnekte minimum yanıt gösterilmektedir. Daha fazla bilgi için kimlik sağlayıcı uygulama kılavuzuna bakın.

Uç nokta: .well-known/web-identity içinde belirtildiği gibi

Aşağıda örnek bir yanıt verilmiştir:

{
  "accounts": [
    {
      "id": "demo-example",
      "name": "Demo User",
      "email": "demo@example.com",
      "given_name": "Demo"
    }
  ]
}

Login Status API ile entegrasyon

Kullanıcının sağlayıcıyla etkin bir oturumu olmalı ve Login Status API'yi kullanarak bunu tarayıcıya bildirmeniz gerekir.

Bir kullanıcı başarılı bir şekilde oturum açtığında veya oturumu kapattığında eşleşen HTTP yanıt başlığını yayınlayın:

Set-Login: logged-in
Set-Login: logged-out

Alternatif olarak, web uygulamanızda JavaScript kullanarak durumu güncelleyebilirsiniz. context:

navigator.login.setStatus("logged-in");
navigator.login.setStatus("logged-out");

Sertifika verme isteklerini işleme

issuance_endpoint, application/json POST isteği alıyor. Bu istekte email anahtarı ve Signature, Signature-Input ve Signature-Key için HTTP mesajı imzaları üst bilgileri yer alıyor.

Ortamınız için yapılandırılmış üstbilgileri ve HTTP mesaj imzalarını destekleyen bir kitaplık kullanın. Node.js'de structured-headers ve http-message-sig kullanabilirsiniz.

Tam istek biçimi:

POST /email-verification/issuance HTTP/1.1
Host: provider.example
Accept: application/json
Content-Digest: sha-256=:aBc123aBc123aBc123aBc123aBc123=:
Content-Type: application/json
Sec-Fetch-Dest: email-verification
Signature: sig=:+dEf567dEf567/dEf567dEf567dEf567/dEf567==:
Signature-Input: sig=("@method" "@authority" "@path" "content-digest" "signature-key");created=1786455840
Signature-Key: sig=hwk;alg="Ed25519";crv="Ed25519";kty="OKP";x="gHi890_gHi890_gHi890"

{email: "demo@example.com"}

İsteği ayrıştırın ve doğrulayın:

  • Oturum kimlik doğrulaması: İstekle birlikte gönderilen birinci taraf oturum çerezlerinizi doğrulayın. Kullanıcının kimliği doğrulanmalıdır.
  • Sec-Fetch-Dest üstbilgisi: email-verification olarak ayarlanır.
  • HTTP Mesaj İmzaları: Signature-Key içindeki kısa ömürlü ortak anahtarı kullanarak istek imzasını doğrulayın ve Content-Digest öğesini onaylayın. Chrome 156'dan itibaren Signature-Key üstbilgisi, hwk parametrelerinde alg="Ed25519" içerir. "Ed25519" ve "EdDSA"'ı kabul edin ve alg'ın önceki Chrome sürümleri tarafından atlanmasına izin verin.
  • Yük: JSON gövdesi, doğrulama için istenen email dizesini içerir.

Verilme yanıtı

Oturum ve istek jetonunun başarılı bir şekilde doğrulanmasının ardından, platformunuz için uygun kitaplıkları kullanarak JSON olarak döndürülen imzalı bir Seçici Açıklama JWT'si (SD-JWT) oluşturun. Örneğin, Node için @sd-jwt/core ve jose kullanabilirsiniz.

Ham yük biçimi şuna benzer şekilde görünmelidir:

{
  "iss": "https://accounts.issuer.example",
  "iat": 1780272000,
  "exp": 1780272300,
  "cnf": {
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "pUbLiCKeY123pUbLiCKeY123pUbLiCKeY123",
      "y": "pUbLiCKeY456pUbLiCKeY456pUbLiCKeY456"
    }
  },
  "email": "demo@example.com",
  "email_verified": true
}

Jetonu oluşturun, imzalayın ve döndürün:

import { importJWK, CompactSign } from "jose";
import { SDJwtInstance } from "@sd-jwt/core";
import crypto from "node:crypto";
// Issuer private key from secure storage
const privateKey = await importJWK(PRIVATE_KEY_JWK, "EdDSA");
const origin = url.origin;
const currentTime = Math.floor(Date.now() / 1000);
const evtPayload = {
  iss: origin,
  iat: currentTime,
  exp: currentTime + 300, // 5 minutes
  cnf: {
    jwk: browserJwk,
  },
  email: payload.email, // exactly as received in payload
  email_verified: true,
};
const sdJwt = new SDJwtInstance({
  signer: async (data) => {
    const [headerB64, payloadB64] = data.split(".");
    const header = JSON.parse(Buffer.from(headerB64, "base64url").toString());
    const payload = Buffer.from(payloadB64, "base64url");
    const signed = await new CompactSign(payload).setProtectedHeader(header).sign(privateKey);
    return signed.split(".").pop()!;
  },
  signAlg: "EdDSA",
  hasher: async (data, alg) => {
    const nodeAlg = alg.replace("-", "");
    return new Uint8Array(crypto.createHash(nodeAlg).update(data).digest());
  },
  hashAlg: "sha-256",
  saltGenerator: async () => crypto.randomBytes(16).toString("base64url"),
});
const issuanceToken = await sdJwt.issue(evtPayload, undefined, {
  header: {
    alg: "EdDSA",
    kid: PRIVATE_KEY_JWK.kid,
    typ: "evt+jwt",
  },
});
return sendResponse({ issuance_token: issuanceToken, }, 200);

Elde edilen yanıt gövdesi şuna benzer:

{
  "issuance_token": "tOkEn123tOkEn123tOkEn123...~"
}

E-posta doğrulama jetonunu oluşturup imzaladıktan sonra tarayıcı, bunu doğrulama için doğrulayıcı siteye iletir.

Sorun giderme

Tarayıcı, uç noktalarınızla iletişime geçmiyorsa veya verilen jetonları reddediyorsa aşağıdaki yaygın sorunları kontrol edin:

Tarayıcı hiçbir zaman accounts_endpoint veya issuance_endpoint yöntemini çağırmaz.

  • Giriş Durumu ayarlanmadı: Chrome, uç noktalarınızı yalnızca kullanıcının oturum açtığını bildiği durumlarda sorgular. Oturum açma akışınızın Set-Login: logged-in HTTP üstbilgisini ayarladığından veya navigator.login.setStatus("logged-in") yöntemini çağırdığından emin olun.
  • Oturum çerezleri engellendi (SameSite=None): Tarayıcı, farklı bir sitedeki güvenen taraftan accounts_endpoint ve issuance_endpoint bilgilerinizi getirir. Bunlar siteler arası istekler olduğundan oturum çereziniz SameSite=None; Secure içermelidir. SameSite=Lax çerezi, aynı site doğrulayıcıda test edilirken çalışır ancak siteler arası isteklerde atlanır.
  • Keşif veya hesap uyuşmazlığı: _email-verification.<email-domain> adresinin standart küçük harfli ana makine adı (https://, bağlantı noktası, yol veya büyük harf içermeyen iss=<issuer-domain>) içeren tek bir TXT kaydı döndürdüğünü, her iki .well-known uç noktasının da Content-Type: application/json döndürdüğünü, .well-known/email-verification adresinin https://<issuer-domain> ile bayt bayt eşleşen bir issuer içerdiğini ve accounts_endpoint yanıtının, email değeri girilen adresle eşleşen bir hesap içerdiğini doğrulayın.
  • .well-known/email-verification içinde desteklenmeyen imzalama algoritması: Chrome 154 ve 155, signing_alg_values_supported içinde "EdDSA" gerektirirken Chrome 156 ve sonraki sürümler ile IETF spesifikasyonu "Ed25519" destekler. Geçiş sırasında her ikisinin de ["Ed25519", "EdDSA"] reklamını yapın. Böylece Chrome kararlı sürümü, keşif meta verilerinizi reddetmez.

Düzenleme isteği doğrulanamadı

  • Sec-Fetch-Dest başlığının yazımı: Chrome 154 ve sonraki sürümler Sec-Fetch-Dest: email-verification (tire ile) gönderirken Chrome 153, emailverification (tire olmadan) gönderiyordu. Kullanıma sunma sırasında her iki değeri de kabul edin.
  • Proxy arkasında HTTP Mesaj İmzası (@authority) uyuşmazlığı: RFC 9421 imzası doğrulanırken @authority bileşeni, herkese açık ana makineyi yansıtır. Sunucunuz bir ters proxy'nin veya yük dengeleyicinin arkasında bulunuyorsa doğrulama URL'sini dahili ana makine adı yerine X-Forwarded-Host (veya herkese açık kaynağınız) kullanarak yeniden oluşturun ve JSON ayrıştırmadan önce ham istek gövdesi baytları üzerinde Content-Digest hesaplayın.

Tarayıcı, döndürülen issuance_token değerini reddeder

  • Değiştirilmiş veya kanonikleştirilmiş email talebi: Chrome 156'dan itibaren tarayıcı, EVT email talebinin istenen email ile bire bir eşleştiğini kontrol eder. Arka ucunuz, adresi standart bir hesap biçimine normalleştirirse (ör. first.LAST@example.com istendiğinde First.Last@example.com döndürülürse) Chrome, jetonu siler. İsteği kullanıcının hesabıyla eşleştirin ancak istek gövdesinde alınan email dizesini aynen döndürün.
  • Sondaki tilde (~) eksik: Sıfır açıklama olsa bile issuance_token, tarayıcının <KB-JWT> ekleyebilmesi için tilde (<Issuer-signed-JWT>~) ile biten geçerli bir SD-JWT olmalıdır.
  • Eşleşmeyen iss veya cnf.jwk: EVT iss hak talebinin, .well-known/email-verification meta verilerinizle eşleşen tam HTTPS kaynağı (https://<issuer-domain>, sonunda eğik çizgi olmadan) olduğundan ve cnf.jwk'nin, tarayıcının geçici ortak anahtarını Signature-Key üstbilgisinden yerleştirdiğinden emin olun.