Implementasi penyedia email (penerbit)

Untuk detail tambahan, Anda dapat mempelajari kode demo penyedia email tiruan dan melihat langkah-langkah penerbit dalam proposal Email Verification API dan Email Verification Protocol.

Sebagai penerbit, Anda tidak perlu mendaftar ke uji coba origin atau memberikan token karena situs pihak tepercaya memicu perilaku browser. Pastikan endpoint Anda dikonfigurasi untuk merespons permintaan tersebut.

Mengonfigurasi penemuan penerbit

Untuk mengizinkan browser otomatis menemukan endpoint verifikasi Anda saat alamat email yang termasuk dalam domain Anda dipilih, ekspos konfigurasi Anda menggunakan DNS dan endpoint HTTP .well-known.

Mengonfigurasi data delegasi DNS

Konfigurasikan data TXT DNS di domain email Anda yang mendelegasikan otoritas verifikasi ke ID penerbit Anda. ID ini dapat menggunakan domain yang sama, bergantung pada infrastruktur Anda.

Format Data: _email-verification.<email-domain>

Contoh File Zona:

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

Nilai iss= harus berupa nama host huruf kecil kanonis tanpa skema (https://), port, jalur, atau karakter huruf besar (misalnya, iss=accounts.issuer.example). Chrome menolak data yang menyertakan komponen non-nama host.

Menghosting endpoint .well-known/email-verification

Hosting file metadata JSON di domain penerbit Anda di jalur /.well-known/. File ini menguraikan kemampuan penerbitan Anda dan algoritma penandatanganan kriptografi yang didukung infrastruktur Anda.

Endpoint: https://<issuer-domain>/.well-known/email-verification

Contoh respons:

{
  "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"]
}

Properti metadata:

  • issuer: Origin penerbit Anda (https://<issuer-domain>, tanpa garis miring di akhir). Harus cocok dengan origin tempat file metadata ditayangkan byte per byte.
  • issuance_endpoint: URL HTTPS yang menerima permintaan POST penerbitan token.
  • jwks_uri: URL HTTPS yang menayangkan JSON Web Key Set (JWKS) publik Anda.
  • signing_alg_values_supported: Array algoritma penandatanganan JWS yang didukung.

Menghosting endpoint .well-known/web-identity

Anda mungkin telah menerapkan resource JSON .well-known tambahan sebagai bagian dari Federated Credentials (FedCM) API. Resource ini menyediakan link ke endpoint akun dan URL login Anda.

Endpoint: https://<domain>/.well-known/web-identity

Contoh respons:

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

Menggunakan endpoint akun

Endpoint akun dari FedCM API menyediakan daftar akun yang login saat ini. Contoh berikut menunjukkan respons minimal. Untuk mengetahui detail selengkapnya, lihat panduan penerapan penyedia identitas.

Endpoint: seperti yang ditentukan di .well-known/web-identity

Berikut adalah contoh respons:

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

Berintegrasi dengan Login Status API

Pengguna harus memiliki sesi aktif dengan penyedia dan Anda harus memberi sinyal itu kepada browser menggunakan Login Status API.

Saat pengguna berhasil login atau logout, tayangkan header respons HTTP yang cocok:

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

Atau, perbarui status menggunakan JavaScript dalam konteks aplikasi web Anda:

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

Menangani permintaan penerbitan

issuance_endpoint Anda menerima permintaan POST application/json yang berisi kunci email dan header HTTP Message Signatures untuk Signature, Signature-Input, dan Signature-Key.

Gunakan library yang mendukung header terstruktur dan HTTP Message Signatures untuk lingkungan Anda. Di Node.js, Anda dapat menggunakan structured-headers dan http-message-sig.

Format permintaan lengkap:

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"}

Mengurai dan memvalidasi permintaan:

  • Autentikasi sesi: Validasi cookie sesi pihak pertama yang dikirim dengan permintaan. Pengguna harus diautentikasi.
  • Header Sec-Fetch-Dest: Setel ke email-verification.
  • Tanda Tangan Pesan HTTP: Verifikasi tanda tangan permintaan menggunakan kunci publik sementara di Signature-Key dan validasi Content-Digest. Mulai Chrome 156, header Signature-Key menyertakan alg="Ed25519" dalam parameter hwknya; terima "Ed25519" dan "EdDSA", serta izinkan alg dihilangkan oleh versi Chrome sebelumnya.
  • Payload: Isi JSON berisi string email yang diminta untuk verifikasi.

Respons penerbitan

Setelah berhasil memvalidasi sesi dan token permintaan, buat JWT Pengungkapan Selektif (SD-JWT) yang ditandatangani dan ditampilkan sebagai JSON menggunakan library yang sesuai untuk platform Anda. Misalnya, untuk Node, Anda dapat menggunakan @sd-jwt/core dan jose.

Format payload mentah akan terlihat seperti:

{
  "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
}

Buat, tandatangani, dan tampilkan token:

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);

Isi respons yang dihasilkan akan terlihat seperti:

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

Setelah Anda membuat dan menandatangani token verifikasi email, browser akan meneruskannya ke situs verifikator untuk validasi.

Pemecahan masalah

Jika browser tidak menghubungi endpoint Anda atau menolak token yang dikeluarkan, periksa masalah umum berikut:

Browser tidak pernah memanggil accounts_endpoint atau issuance_endpoint

  • Status Login tidak ditetapkan: Chrome hanya mengkueri endpoint Anda jika mengetahui bahwa pengguna login. Pastikan alur login Anda menetapkan header Set-Login: logged-in HTTP atau memanggil navigator.login.setStatus("logged-in").
  • Cookie sesi diblokir (SameSite=None): Browser mengambil accounts_endpoint dan issuance_endpoint Anda dari pihak tepercaya di situs lain. Karena ini adalah permintaan lintas situs, cookie sesi Anda harus menyertakan SameSite=None; Secure. Cookie SameSite=Lax berfungsi saat pengujian pada verifikator situs yang sama, tetapi dihilangkan pada permintaan lintas situs.
  • Ketidakcocokan penemuan atau akun: Pastikan _email-verification.<email-domain> menampilkan satu data TXT dengan nama host huruf kecil kanonis (iss=<issuer-domain>, tanpa https://, port, jalur, atau karakter huruf besar), kedua endpoint .well-known menampilkan Content-Type: application/json, .well-known/email-verification memiliki issuer yang cocok dengan https://<issuer-domain> byte per byte, dan respons accounts_endpoint menyertakan akun yang email cocok dengan alamat yang dimasukkan.
  • Algoritma penandatanganan yang tidak didukung di .well-known/email-verification: Chrome 154 dan 155 memerlukan "EdDSA" di signing_alg_values_supported, sedangkan Chrome 156+ dan spesifikasi IETF mendukung "Ed25519". Iklankan ["Ed25519", "EdDSA"] selama transisi agar Chrome Stabil tidak menolak metadata penemuan Anda.

Validasi permintaan penerbitan gagal

  • Sec-Fetch-Dest ejaan header: Chrome 154+ mengirim Sec-Fetch-Dest: email-verification (dengan tanda hubung), sedangkan Chrome 153 mengirim emailverification (tanpa tanda hubung). Terima kedua nilai selama peluncuran.
  • Ketidakcocokan HTTP Message Signature (@authority) di balik proxy: Saat memverifikasi tanda tangan RFC 9421, komponen @authority mencerminkan host yang terlihat publik. Jika server Anda berada di balik reverse proxy atau load balancer, buat ulang URL verifikasi menggunakan X-Forwarded-Host (atau origin publik Anda), bukan nama host internal, dan hitung Content-Digest melalui byte isi permintaan mentah sebelum penguraian JSON.

Browser menolak issuance_token yang ditampilkan

  • Klaim email yang diubah atau dikanonisasi: Mulai Chrome 156, browser akan memeriksa apakah klaim email EVT cocok dengan email byte per byte. Jika backend Anda menormalkan alamat ke format akun kanonis (seperti menampilkan First.Last@example.com saat first.LAST@example.com diminta), Chrome akan menghapus token. Cocokkan permintaan dengan akun pengguna, tetapi tampilkan string email persis yang diterima di isi permintaan.
  • Tilda di akhir (~) tidak ada: Meskipun tanpa pengungkapan, issuance_token harus berupa SD-JWT yang valid dan diakhiri dengan tilda (<Issuer-signed-JWT>~) agar browser dapat menambahkan <KB-JWT>.
  • `iss` atau iss`cnf.jwk`cnf.jwk tidak cocok: Pastikan klaim iss EVT adalah origin HTTPS yang sama persis (https://<issuer-domain>, tanpa garis miring di akhir) yang cocok dengan metadata .well-known/email-verification Anda, dan cnf.jwk menyematkan kunci publik sementara browser dari header Signature-Key.