Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Menguji Protokol Verifikasi Email dengan uji coba origin

Rowan Merewood

Dipublikasikan: 8 Juli 2026

Saat mengumpulkan alamat email sebagai bagian dari proses pendaftaran, login, langganan, checkout, pemulihan akun, atau proses lainnya, biasanya alamat email tersebut akan dikonfirmasi sebagai milik orang yang memasukkannya. Metode verifikasi yang ada, seperti sandi sekali pakai (OTP) atau link verifikasi email (link ajaib), mengharuskan pengguna keluar dari situs Anda. Proses yang mengganggu ini dapat meningkatkan risiko pengguna, baik manusia maupun agen, meninggalkan sesi mereka sepenuhnya dan tidak pernah menyelesaikan proses autentikasi mereka.

Email Verification API adalah proposal yang memungkinkan browser berkomunikasi langsung dengan penyedia email untuk memverifikasi bahwa pengguna memiliki alamat email tersebut. Pengguna memilih email dari saran isi otomatis atau pelengkapan otomatis browser, mengirimkan formulir, dan situs memverifikasi alamat email dengan penyedia tanpa mengirim email atau mengganggu alur pengguna.

Demo perintah pengguna Email Verification API

Pengumpulan email adalah titik konversi penting dalam perjalanan pengguna, dan Chrome ingin mendapatkan masukan tentang proposal dari situs yang ingin memverifikasi email, penyedia email yang dapat melakukan verifikasi, dan pengguna yang mengalami proses tersebut. Anda dapat mendaftar ke uji coba origin hari ini dan mengikuti petunjuk penerapan di sini. Untuk konfigurasi uji coba origin umum, lihat Memulai uji coba origin.

Anda dapat mencoba alur dengan akun demo:

Demo penerbit memberi Anda akun dan sesi email tiruan
Demo verifikator akan memverifikasi penyedia yang berpartisipasi

Alur verifikasi email

Bagian berikut menjelaskan hal-hal yang Anda dan pengguna Anda perlukan untuk memulai alur verifikasi email, dan seluruh alur kerja saat menggunakan Email Verification Protocol.

Istilah utama

Istilah utama untuk Email Verification API adalah sebagai berikut:

Verifikator: Situs yang mengumpulkan alamat email dan ingin memverifikasi nya. Verifikator juga disebut Pihak yang Mengandalkan.
Penyedia Email: Layanan yang menyediakan alamat email pengguna, misalnya gmail.com.
Penerbit: Layanan yang mengelola akun untuk email pengguna, misalnya accounts.google.com. Penerbit juga disebut Penyedia Identitas.

Dalam beberapa kasus, penyedia email dan penerbit dapat beroperasi dari domain yang sama. Namun, penting untuk membedakan antara memiliki alamat email dan memiliki sesi aktif untuk akun terkait.

Prasyarat

Pengguna harus login ke penyedia email atau penerbit mereka di profil browser yang sama. Misalnya, jika menggunakan Gmail, mereka harus login ke Akun Google mereka.
Sebagai situs verifikator yang berpartisipasi, Anda harus mendaftar ke uji coba origin dan memberikan token di halaman yang sama dengan formulir email Anda.
Pengguna harus memilih alamat email mereka dari drop-down isi otomatis atau pelengkapan otomatis.
- Jika pengguna sebelumnya telah memasukkan alamat email di kolom, alamat email tersebut akan ditawarkan menggunakan pelengkapan otomatis.
- Jika pengguna telah menambahkan alamat email mereka menggunakan setelan Chrome "Isi otomatis dan sandi" (chrome://settings/autofill), alamat email tersebut akan ditawarkan menggunakan isi otomatis.
  
  Catatan: Dukungan untuk alamat yang diketik secara manual direncanakan untuk rilis mendatang.
Saat pertama kali memberikan alamat email untuk verifikasi, pengguna akan melihat perintah izin. Hal ini hanya terjadi satu kali per alamat email.

Setelah memiliki sesi aktif di browser, pengguna dapat memulai proses:

Pada formulir dengan kolom email, pengguna memilih alamat email mereka dari drop-down pelengkapan otomatis. Situs verifikator menyediakan kolom tersembunyi dalam formulir dengan nonce per instance untuk memvalidasi permintaan ini.
Browser kemudian akan mengambil data DNS verifikasi email untuk domain email. Hal ini mengarahkan browser ke penerbit. Penerbit kemudian akan mengonfirmasi bahwa mereka memiliki sesi aktif untuk alamat email tersebut.

Catatan: Permintaan ini tidak mengungkapkan informasi tambahan apa pun tentang pengguna. Situs verifikator tidak menerima informasi selama langkah ini. Penerbit hanya melihat permintaan untuk memverifikasi keberadaan pengguna; penerbit tidak melihat situs mana yang memulai permintaan.
Penerbit kemudian akan memberikan Token Verifikasi Email (EVT) untuk alamat tersebut. Browser menggabungkannya ke dalam JWT terikat kunci dengan EVT, origin situs, dan nonce dari formulir input.
Saat formulir dikirimkan, paket EVT akan ditambahkan ke kolom tersembunyi dan dikirim ke situs.
Situs verifikator kemudian memverifikasi setiap detail tersebut: alamat email yang diharapkan, nonce, dan tanda tangan dari browser dan penerbit.
Pengguna akan melihat notifikasi kecil yang memberi tahu bahwa penyedia email mereka telah memverifikasi alamat mereka.

Proses ini memberikan konfirmasi kepada situs verifikator bahwa alamat email tersebut valid dan milik pengguna saat ini, yang berarti situs dapat melewati pengiriman email verifikasi.

Pengguna dapat mengelola email terverifikasi mereka di bagian Setelan > Isi otomatis dan sandi > Info kontak > Email Terverifikasi (atau membuka chrome://settings/contactInfo).

Pertimbangan kasus penggunaan

Verifikasi email adalah peningkatan progresif pada alur yang ada yang menghilangkan kebutuhan pengguna untuk keluar dari situs Anda guna mengambil OTP atau mengklik link. Situs dapat menambahkan kolom verifikasi email ke semua formulir yang relevan, seperti login, pendaftaran newsletter, pembuatan akun, dan pemulihan sandi. EVP hanya dipicu jika browser mendukungnya. Jika tidak ada kode yang diterima saat pengiriman atau salah satu langkah validasi gagal, Anda dapat kembali ke alur konfirmasi email default. Hal ini juga berarti tidak ada deteksi fitur untuk API; situs verifikator memperlakukan EVT sebagai opsional, dan memprosesnya jika ada dalam permintaan.

Verifikasi email mengonfirmasi bahwa pengguna memiliki sesi aktif dengan penyedia alamat email mereka. Verifikasi email tidak mengonfirmasi bahwa email Anda telah diterima pengguna. Anda mungkin masih ingin mengirim email selamat datang atau orientasi yang ada dan mungkin ingin atau perlu meminta pengguna untuk memeriksa setelan spam mereka.

Mengimplementasikan situs verifikator

Untuk detail tambahan, Anda dapat mempelajari kode demo end-to-end dan melihat langkah-langkah validasi dalam proposal Email Verification API dan Email Verification Protocol.

Mengonfigurasi kolom formulir

Pastikan kolom formulir Anda memiliki atribut yang benar:

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

Tetapkan atribut type dan autocomplete input email ke email agar browser dapat menawarkan pelengkapan otomatis untuk alamat email.

Kolom hidden baru akan diisi dengan token verifikasi email saat pengiriman formulir. Atribut yang diperlukan adalah:

Tetapkan type="hidden" karena kolom ini tidak memerlukan input pengguna.
Tetapkan nonce="rAnD0m-VaLuE". Situs harus menyediakan nonce terikat sesi yang unik untuk memverifikasi pengiriman formulir.
Tetapkan autocomplete="email-verification-token". Browser menggunakan atribut ini untuk mengidentifikasi kolom yang akan diisi.

Validasi elemen formulir Anda dengan memeriksa panel Jaringan di DevTools. Saat Anda memilih alamat email, Anda akan melihat browser memicu DNS dan kueri pencarian akun berikutnya untuk penyedia dan penerbit email. Ini adalah permintaan browser internal; situs Anda tidak menerima apa pun hingga pengiriman formulir.

Memvalidasi EVT

Ada lima langkah untuk memvalidasi setiap komponen paket EVT.

Mengurai token.
Memvalidasi nilai yang diharapkan.
Memvalidasi pengikatan kunci.
Memvalidasi data DNS.
Menemukan penerbit dan memverifikasi tanda tangan EVT.

1. Mengurai token

Data mentah dari pengiriman formulir berisi EVT dan klaim yang ditandatangani dalam Token Web JSON Pengungkapan Selektif (SD-JWT+KB) yang dipisahkan oleh tilde (~ karakter). Anda harus memisahkan dan mendekode header dan payload Penandatanganan dan Enkripsi Objek JavaScript (JOSE) (misalnya, dengan menggunakan jose untuk Node.js).

Jika example.com memverifikasi demo@gmail.com, payload yang didekode akan terlihat mirip dengan contoh berikut:

{
  "evtJwtDecodedPayload": {
    "cnf": {
      "jwk": {
        "crv": "Ed25519",
        "kty": "OKP",
        "x": "pUbLiCkEy123pUbLiCkEy123pUbLiCkEy123"
      }
    },
    "email": "demo@gmail.com",
    "email_verified": true,
    "iat": 1782911685,
    "iss": "https://accounts.google.com"
  },
  "kbJwtDecodedPayload": {
    "aud": "https://example.com",
    "iat": 1782911685,
    "nonce": "rAnDoM123rAnDoM123rAnDoM123rAnDoM123",
    "sd_hash": "hAsH456hAsH456hAsH456hAsH456hAsH456"
  }
}

2. Memvalidasi nilai yang diharapkan

Periksa apakah nilai dasar dalam payload cocok dengan nilai yang Anda berikan:

Pastikan email_verified ditetapkan ke true.
Pastikan email cocok dengan alamat email yang diberikan dalam formulir Anda.
Pastikan nonce cocok dengan nonce yang diberikan dalam formulir Anda.
Pastikan aud cocok dengan origin situs Anda.
Pastikan iat memiliki stempel waktu yang relatif baru, misalnya, setelah formulir dirender.

3. Memvalidasi pengikatan kunci

Browser membuat kunci sementara dan efemeral untuk transaksi guna mengonfirmasi bahwa kunci tersebut menandatangani token. Ekstrak kunci ini dari klaim cnf (konfirmasi) di EVT, lalu gunakan untuk memverifikasi JWT terikat kunci.

Kemudian, hitung hash yang diharapkan dan bandingkan dengan klaim sd_hash. Contoh Node.js berikut menunjukkan cara melakukan perhitungan ini:

const calculatedHash = createHash("sha256")
        .update(evtJwt + "~")
        .digest("base64url");

4. Memvalidasi data DNS

Verifikasi data DNS _email-verification untuk domain alamat email. Misalnya, untuk demo@gmail.com, kueri data TXT _email-verification.gmail.com. Untuk penyedia ini, kueri akan menampilkan lokasi penyedia akun, yaitu accounts.google.com.

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

5. Menemukan penerbit dan memverifikasi tanda tangan EVT

Pastikan penerbit menayangkan resource /.well-known/email-verification, yang menyediakan endpoint untuk menerbitkan token, Kunci Web JSON (JWK) untuk situs, dan algoritma penandatanganan yang didukung.

$ curl https://accounts.google.com/.well-known/email-verification
{
  "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": ["EdDSA"]
}

Gunakan JWK untuk memverifikasi JWT EVT yang Anda ekstrak dari token. Sebagian besar library JOSE menyediakan fungsi untuk menangani verifikasi ini.

Jika kelima langkah berhasil, Anda telah memverifikasi alamat email terhadap penyedia. Jika tidak, kembali ke pengiriman email konfirmasi kepada pengguna sesuai alur normal Anda.

Mengimplementasikan layanan penyedia dan penerbit email

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 perilaku browser dipicu oleh situs pihak yang mengandalkan. Anda hanya perlu memastikan endpoint yang diharapkan ada untuk merespons permintaan tersebut.

Mengonfigurasi penemuan penerbit

Untuk memungkinkan 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

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

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:

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

Menghosting endpoint `.well-known/web-identity`

Resource JSON .well-known tambahan yang mungkin telah Anda terapkan 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 dengan 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/x-www-form-urlencoded yang berisi request_token.

Bagian berikut menunjukkan proses lengkap penanganan permintaan penerbitan.

1. Memvalidasi permintaan penerbitan

Mengurai dan memvalidasi payload browser yang masuk:

Metode: POST
Verifikasi Sesi: Validasi cookie session/authentication pihak pertama pengguna yang dikirim bersama permintaan untuk memastikan konteks identitas yang aktif dan diotorisasi ada.
Verifikasi Parameter: Ekstrak parameter request_token (JWT yang ditandatangani yang dibuat oleh browser). Pastikan parameter tersebut berisi kunci publik efemeral yang diharapkan, email target, audiens yang benar, dan stempel waktu yang valid.

Token yang didekode akan terlihat seperti:

{
  "decodedHeader": {
    "alg": "ES256",
    "typ": "JWT",
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "pUbLiCKeY123pUbLiCKeY123pUbLiCKeY123",
      "y": "pUbLiCKeY456pUbLiCKeY456pUbLiCKeY456"
    }
  },
  "decodedPayload": {
    "iss": "https://accounts.issuer.example",
    "sub": "demo@example.com",
    "email": "demo@example.com",
    "iat": 1780272000,
    "exp": 1780272300
  },
  "signature": "SIGnatURE-123_SIGnatURE-123_SIGnatURE-123"
}

2. Merespons dengan token

Setelah berhasil memvalidasi sesi dan token permintaan, buat JWT Pengungkapan Selektif (SD-JWT) yang ditandatangani menggunakan payload:

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

Tandatangani payload menggunakan kunci pribadi dan algoritma yang didukung. Misalnya, menggunakan jose di Node.js:

const evtJwt = await new SignJWT(evtPayload)
   .setProtectedHeader({
     alg: "EdDSA",
     kid: PRIVATE_KEY_JWK.kid, // Key ID corresponding to our JWKS keys
     typ: "evt+jwt", // Standard Token Type for EVTs
   })
   .sign(privateKey);

 // Standard SD-JWT compatibility requires appending a trailing tilde "~"
 // to separate the signed token from the key binding section.
 const issuanceToken = `${evtJwt}~`;

Contoh Respons Berhasil (HTTP 200):

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

Pertimbangan uji coba origin

Uji coba origin adalah eksperimen untuk mengumpulkan masukan, sehingga input Anda sangat penting jika Anda berpartisipasi sebagai pihak yang mengandalkan atau penyedia identitas. Untuk melaporkan masalah, gunakan repositori GitHub berikut:

Browser Email Verification API: WICG/email-verification
Email Verification Protocol: dickhardt/email-verification

Jika Anda menemukan bug dalam penerapan Chrome, ajukan bug terhadap komponen:

Masalah baru: Chromium > Blink > Identity > EVP

Pengaktifan fungsi uji coba origin dikontrol berdasarkan per respons dengan menyertakan token OT. Artinya, Anda memiliki kontrol terperinci jika lebih suka membatasi fungsi ke sebagian pengguna. Misalnya, jika sudah memiliki framework pengujian A/B, Anda dapat mengintegrasikan uji coba origin di sana untuk populasi eksperimen terkontrol. Atau, jika Anda memiliki grup pengguna pengujian beta atau pratinjau awal, Anda mungkin ingin atau perlu mengaktifkan fitur tersebut untuk mereka. Dalam hal ini, periksa alamat email yang diberikan sebelum menerbitkan atau memvalidasi token.

Uji coba origin juga memiliki batas traffic untuk meminimalkan situs yang mengandalkan fitur sebelum peluncuran. API penerbit sedang dalam pengembangan, dan Anda harus memperkirakan perubahan yang tidak kompatibel dengan versi sebelumnya bersama dengan update pada UX Chrome.

Kami akan memposting update lebih lanjut di blog ini dan di evp-announce@chromium.org milis seiring perkembangan pengembangan.