Yayınlanma tarihi: 8 Temmuz 2026
Kayıt, oturum açma, abone olma, ödeme, hesap kurtarma veya başka bir işlem kapsamında e-posta adresi toplarken, e-posta adresinin girildiği kişi tarafından kullanıldığını onaylamak yaygın bir uygulamadır. Tek kullanımlık şifreler (OTP'ler) veya e-posta doğrulama bağlantıları (sihirli bağlantılar) gibi mevcut doğrulama yöntemleri, kullanıcının sitenizden ayrılmasını gerektirir. Bu rahatsız edici süreç, kullanıcının (insan veya aracı) oturumunu tamamen terk etme ve kimlik doğrulama sürecini hiçbir zaman tamamlamama riskini artırabilir.
E-posta Doğrulama API'si, kullanıcının e-posta adresinin sahibi olduğunu doğrulamak için tarayıcının doğrudan e-posta sağlayıcıyla iletişim kurmasına olanak tanıyan bir öneridir. Kullanıcılar, tarayıcının otomatik doldurma veya otomatik tamamlama önerisinden bir e-posta adresi seçer, formu gönderir ve site, e-posta göndermeden veya kullanıcının akışını kesintiye uğratmadan e-posta adresini sağlayıcıyla doğrular.
E-posta toplama, kullanıcı yolculuğunda kritik bir dönüşüm noktasıdır. Chrome, e-postaları doğrulamak isteyen sitelerden, doğrulamayı yapabilen e-posta sağlayıcılarından ve bu süreci deneyimleyen kullanıcılardan öneriyle ilgili geri bildirim almak istiyor. Kaynak denemesine bugün kaydolabilir ve buradaki uygulama talimatlarını uygulayabilirsiniz. Genel kaynak denemesi yapılandırması için Kaynak denemelerini kullanmaya başlama başlıklı makaleyi inceleyin.
Akışı bir demo hesabıyla deneyebilirsiniz:
- Düzenleyen demo, sahte bir e-posta hesabı ve oturumu sağlar.
- Doğrulayıcı demosu, katılan tüm sağlayıcıları doğrular.
E-posta doğrulama akışı
Aşağıdaki bölümlerde, e-posta doğrulama akışını başlatmak için sizin ve kullanıcılarınızın yapması gerekenler ile E-posta Doğrulama Protokolü kullanılırken uygulanan iş akışının tamamı açıklanmaktadır.
Anahtar terimler
Email Verification API ile ilgili temel terimler şunlardır:
- Doğrulayıcı: E-posta adresini toplayan ve doğrulamak isteyen site. Doğrulayıcıya Relying Party (Güvenen Taraf) da denir.
- E-posta Sağlayıcı: Kullanıcının e-posta adresini sağlayan hizmettir (örneğin,
gmail.com). - Düzenleyen: Kullanıcının e-posta hesabını yöneten hizmettir (ör.
accounts.google.com). Düzenleyen, Kimlik Sağlayıcı olarak da adlandırılır.
Bazı durumlarda e-posta sağlayıcı ve veren kuruluş aynı alan adından işlem yapabilir. Ancak e-posta adresine sahip olmak ile ilişkili hesapta etkin bir oturumun olması arasında ayrım yapmak önemlidir.
Ön koşullar
- Kullanıcı, aynı tarayıcı profilinde e-posta sağlayıcısında veya veren kuruluşta oturum açmış olmalıdır. Örneğin, Gmail kullanıyorsa Google Hesabı'nda oturum açmış olması gerekir.
- Katılımcı doğrulayıcı site olarak orijin denemesine kaydolmanız ve e-posta formunuzla aynı sayfada jetonu sağlamanız gerekir.
Kullanıcı, e-posta adresini otomatik doldurma veya otomatik tamamlama açılır listesinden seçmelidir.
- Kullanıcı daha önce alana bir e-posta adresi girdiyse bu adres otomatik tamamlama kullanılarak sunulur.
Kullanıcı, e-posta adresini Chrome ayarlarındaki "Otomatik doldurma ve şifre" (
chrome://settings/autofill) seçeneğini kullanarak eklediyse bu adres, otomatik doldurma özelliğiyle sunulur.
Kullanıcılar, doğrulama için ilk kez e-posta adresi sağladığında izin istemi görür. Bu işlem yalnızca e-posta adresi başına bir kez gerçekleşir.
Kullanıcı tarayıcısında etkin oturum açtıktan sonra işlemi başlatabilir:
- E-posta alanı içeren bir formda kullanıcı, otomatik tamamlama açılır listesinden e-posta adresini seçer. Doğrulayıcı site, bu isteği doğrulamak için formda örnek başına bir nonce ile gizli bir alan sağlar.
Tarayıcı daha sonra e-posta alanının e-posta doğrulama DNS kaydını alır. Bu işlem, tarayıcıyı veren kuruluşa yönlendirir. Daha sonra veren kuruluş, bu e-posta adresi için etkin bir oturumları olduğunu onaylar.
Ardından, veren kuruluş adres için E-posta Doğrulama Jetonu'nu (EVT) sağlar. Tarayıcı, bunu EVT, site kaynağı ve giriş formundaki tek kullanımlık sayı ile birlikte anahtara bağlı bir JWT'de birleştirir.
Form gönderildiğinde EVT paketi gizli alana eklenir ve siteye gönderilir.
Doğrulayıcı site daha sonra bu ayrıntıların her birini (beklenen e-posta adresi, nonce ve tarayıcı ile yayınlayanın imzaları) doğrular.
Kullanıcı, e-posta sağlayıcısının adresini doğruladığını bildiren küçük bir bildirim görür.
Bu işlem, doğrulayıcı siteye e-posta adresinin geçerli olduğu ve mevcut kullanıcıya ait olduğuyla ilgili onay sağlar. Bu sayede site, doğrulama e-postası göndermeyi atlayabilir.
Kullanıcılar, doğrulanmış e-postalarını Ayarlar > Otomatik doldurma ve şifreler > İletişim bilgileri > Doğrulanmış e-posta bölümünden yönetebilir (veya chrome://settings/contactInfo simgesini açabilir).
Kullanım alanıyla ilgili dikkat edilmesi gereken noktalar
E-posta doğrulama, mevcut akışınızda kademeli olarak iyileştirme sağlayan bir özelliktir. Bu özellik sayesinde, kullanıcının OTP almak veya bir bağlantıyı tıklamak için sitenizden ayrılması gerekmez. Siteler, e-posta doğrulama alanlarını girişler, bülten kayıtları, hesap oluşturma ve şifre kurtarma gibi tüm ilgili formlara ekleyebilir. EVP yalnızca tarayıcı destekliyorsa tetiklenir. Gönderim sırasında kod alınmazsa veya doğrulama adımlarından herhangi biri başarısız olursa varsayılan e-posta onay akışınıza geri dönebilirsiniz. Bu durum, API için özellik algılama olmadığı anlamına da gelir. Doğrulayıcı site, EVT'yi isteğe bağlı olarak değerlendirir ve istekte varsa işler.
E-posta doğrulaması, kullanıcının e-posta adresinin sağlayıcısında etkin bir oturumunun olduğunu onaylar. E-postanızın kullanıcıya ulaştığını doğrulamaz. Mevcut karşılama veya oryantasyon e-postalarını göndermeye devam etmek isteyebilirsiniz. Ayrıca, kullanıcıdan spam ayarlarını kontrol etmesini istemeniz gerekebilir.
Doğrulayıcı siteyi uygulama
Daha fazla bilgi için uçtan uca demo kodunu inceleyebilir ve Email Verification API ile Email Verification Protocol önerilerindeki doğrulama adımlarına göz atabilirsiniz.
Form alanlarını yapılandırma
Form alanlarınızın doğru özelliklere sahip olduğundan emin olun:
<input
name="email-address"
type="email"
autocomplete="email">
<input
type="hidden"
name="token"
nonce="rAnD0m-VaLuE"
autocomplete="email-verification-token">
Tarayıcının e-posta adresi için otomatik tamamlama önermesine izin vermek üzere email girişinin type ve autocomplete özelliklerini email olarak ayarlayın.
Form gönderildiğinde yeni hidden alanı, e-posta doğrulama jetonuyla doldurulur. Gerekli özellikler şunlardır:
- Bu alan kullanıcı girişi gerektirmediğinden
type="hidden"olarak ayarlayın. nonce="rAnD0m-VaLuE"olarak ayarlayın. Site, form gönderimini doğrulamak için oturuma bağlı benzersiz bir nonce sağlamalıdır.autocomplete="email-verification-token"olarak ayarlayın. Tarayıcı, doldurulacak alanı tanımlamak için bu özelliği kullanır.
Geliştirici Araçları'ndaki Ağ panelini kontrol ederek form öğelerinizi doğrulayın. Bir e-posta adresi seçtiğinizde tarayıcının, DNS'yi ve e-posta sağlayıcı ile veren kuruluş için sonraki hesap arama sorgularını tetiklediğini görürsünüz. Bunlar dahili tarayıcı istekleridir. Form gönderilene kadar siteniz hiçbir şey almaz.
EVT'yi doğrulama
EVT paketinin her bileşenini doğrulamak için beş adım vardır.
- Jetonu ayrıştırın.
- Beklenen değerleri doğrulayın.
- Anahtar bağlamayı doğrulayın.
- DNS kaydını doğrulayın.
- Düzenleyeni keşfedin ve EVT imzasını doğrulayın.
1. Jetonu ayrıştırma
Form gönderiminden elde edilen ham veriler, tilde (~) karakteriyle ayrılmış bir Seçici Açıklama JSON Web Jetonu
(SD-JWT+KB) içinde EVT ve imzalı talepleri içerir. Bunları ayırmanız ve Javascript Object Signing and Encryption (JOSE) üstbilgilerini ve yüklerini kodunu çözmeniz gerekir (örneğin, Node.js için jose kullanarak).
example.com, demo@gmail.com öğesini doğrularsa kodu çözülen yük aşağıdaki örneğe benzer:
{
"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. Beklenen değerleri doğrulama
Yükteki temel değerlerin sağladığınız değerlerle eşleştiğini kontrol edin:
email_verifieddeğerinintrueolarak ayarlandığını doğrulayın.emaildeğerinin, formunuzda belirtilen e-posta adresiyle eşleştiğini doğrulayın.noncedeğerinin, formunuzda sağlanan nonce ile eşleştiğini doğrulayın.auddeğerinin sitenizin kaynağıyla eşleştiğini doğrulayın.iatöğesinin nispeten yeni bir zaman damgasına sahip olduğunu (ör. form oluşturulduktan sonra) doğrulayın.
3. Anahtar bağlamayı doğrulama
Tarayıcı, jetonu imzaladığını onaylamak için işlemle ilgili geçici bir anahtar oluşturur. Bu anahtarı EVT'deki cnf (onay) talebinden çıkarın ve anahtara bağlı JWT'yi doğrulamak için kullanın.
Ardından, beklenen karma değerini hesaplayın ve sd_hash hak talebiyle karşılaştırın. Aşağıdaki Node.js örneğinde bu hesaplamanın nasıl yapılacağı gösterilmektedir:
const calculatedHash = createHash("sha256")
.update(evtJwt + "~")
.digest("base64url");
4. DNS kaydını doğrulama
E-posta adresi alanının _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"
5. Vereni keşfedin ve EVT imzasını doğrulayın
Verenin, jeton verme uç noktalarını, site için JSON Web Anahtarı'nı (JWK) ve desteklenen imzalama algoritmalarını sağlayan /.well-known/email-verification kaynağını sunduğundan emin olun.
$ 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"]
}
Jetonundan çıkardığınız EVT JWT'yi doğrulamak için JWK'ları kullanın. Çoğu JOSE kitaplığı, bu doğrulamayı işlemek için işlevler sağlar.
Beş adımın tamamı başarılı olursa e-posta adresini sağlayıcıya karşı doğrulamış olursunuz. Aksi takdirde, normal akışınıza göre kullanıcıya onay e-postası gönderin.
E-posta sağlayıcı ve veren hizmetini uygulama
Daha fazla bilgi için sahte e-posta sağlayıcı demo kodunu inceleyebilir ve E-posta Doğrulama API'si ile E-posta Doğrulama Protokolü önerilerindeki veren adımlarına göz atabilirsiniz.
Tarayıcı davranışı, güvenen taraf sitesi tarafından tetiklendiği için veren kuruluş olarak, kaynak denemesine kaydolmanız veya jeton sağlamanız gerekmez. Bu istekleri yanıtlamak için beklenen uç noktaların mevcut olduğundan emin olmanız yeterlidir.
Veren 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 temsilci kaydını yapılandırma
E-posta alanınızda, doğrulama yetkisini veren kimlik sağlayı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"
.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, düzenleme özellikleriniz ve altyapınızın desteklediği kriptografik imzalama algoritmaları özetlenmektedir.
Uç nokta: https://<issuer-domain>/.well-known/email-verification
Örnek yanıt:
{
"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"]
}
.well-known/web-identity uç noktası barındırma
Federated Credentials (FedCM) API'nin bir parçası olarak daha önce uygulamış olabileceğiniz ek bir .well-known JSON kaynağı.
Bu, hesap uç noktanıza ve giriş URL'nize bağlantılar 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çmış hesapların listesini sağlar. Aşağıdaki örnekte minimum düzeyde bir 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ıdır ve Login Status API ile bunu tarayıcıya bildirmeniz gerekir.
Bir kullanıcı başarıyla 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ızın bağlamında JavaScript kullanarak durumu güncelleyin:
navigator.login.setStatus("logged-in");
navigator.login.setStatus("logged-out");
Düzenleme isteklerini işleme
issuance_endpoint, request_token içeren bir application/x-www-form-urlencoded POST isteği alır.
Aşağıdaki bölümlerde, kart verme isteklerinin işlenmesiyle ilgili tüm süreç gösterilmektedir.
1. Düzenleme isteğini doğrulama
Gelen tarayıcı yüklerini ayrıştırma ve doğrulama:
- Yöntem:
POST - Oturum Doğrulaması: Etkin ve yetkili bir kimlik bağlamının mevcut olduğundan emin olmak için istekle birlikte iletilen kullanıcının birinci taraf çerezlerini doğrulayın.
session/authentication - Parametre Doğrulaması:
request_tokenparametresini (tarayıcı tarafından oluşturulan imzalı bir JWT) ayıklayın. Beklenen geçici ortak anahtarı, hedef e-posta adresini, doğru kitleyi ve geçerli bir zaman damgasını içerdiğini doğrulayın.
Kod çözme işleminden sonra elde edilen jeton aşağıdaki gibi görünmelidir:
{
"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. Jetonla yanıt verme
Oturum ve istek jetonu başarıyla doğrulandıktan sonra, aşağıdaki yükü kullanarak imzalı bir Selective Disclosure JWT (SD-JWT) oluşturun:
{
"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
}
Yükü özel anahtarınızı ve desteklenen algoritmayı kullanarak imzalayın. Örneğin, Node.js'de jose kullanma:
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}~`;
Başarı yanıtı örneği (HTTP 200):
{
"issuance_token": "tOkEn123tOkEn123tOkEn123...~"
}
Kaynak denemeleriyle ilgili dikkat edilmesi gerekenler
Kaynak denemeleri, geri bildirim toplamak için yapılan deneysel çalışmalardır. Bu nedenle, güvenen taraf veya kimlik sağlayıcı olarak katılırsanız geri bildirimleriniz çok önemlidir. Sorunları bildirmek için aşağıdaki GitHub depolarını kullanın:
- Tarayıcı E-posta Doğrulama API'si: WICG/email-verification
- E-posta Doğrulaması Protokolü: dickhardt/email-verification
Chrome uygulamasında hatalarla karşılaşırsanız bileşene karşı hata kaydı oluşturun:
Kaynak denemesi işlevinin etkinleştirilmesi, OT jetonunu eklemenizle birlikte yanıt bazında kontrol edilir. Bu sayede, işlevselliği kullanıcılarınızın bir bölümüyle sınırlamayı tercih ederseniz ayrıntılı kontrol sahibi olursunuz. Örneğin, halihazırda bir A/B testi çerçeveniz varsa kontrollü bir deneme popülasyonu için kaynak denemesini buraya entegre edebilirsiniz. Alternatif olarak, beta testi veya erken önizleme kullanıcı grubunuz varsa bu kullanıcılar için özelliği etkinleştirmeniz gerekebilir. Bu durumda, jetonu düzenlemeden veya doğrulamadan önce belirtilen e-posta adresini kontrol edin.
Kaynak denemelerinde, lansman öncesinde özelliğe güvenen siteleri en aza indirmek için trafik sınırları da vardır. Düzenleyen API geliştirme aşamasındadır. Chrome kullanıcı deneyiminde yapılan güncellemelerin yanı sıra geriye dönük uyumlu olmayan değişiklikler de bekleyebilirsiniz.
Geliştirme süreci ilerledikçe blogda ve evp-announce@chromium.org posta listesinde daha fazla güncelleme yayınlayacağız.