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 vermePOSTisteklerini 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-verificationolarak ayarlanır.- HTTP Mesaj İmzaları:
Signature-Keyiçindeki kısa ömürlü ortak anahtarı kullanarak istek imzasını doğrulayın veContent-Digestöğesini onaylayın. Chrome 156'dan itibarenSignature-Keyüstbilgisi,hwkparametrelerindealg="Ed25519"içerir."Ed25519"ve"EdDSA"'ı kabul edin vealg'ın önceki Chrome sürümleri tarafından atlanmasına izin verin. - Yük: JSON gövdesi, doğrulama için istenen
emaildizesini 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-inHTTP üstbilgisini ayarladığından veyanavigator.login.setStatus("logged-in")yöntemini çağırdığından emin olun. - Oturum çerezleri engellendi (
SameSite=None): Tarayıcı, farklı bir sitedeki güvenen taraftanaccounts_endpointveissuance_endpointbilgilerinizi getirir. Bunlar siteler arası istekler olduğundan oturum çerezinizSameSite=None; Secureiç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çermeyeniss=<issuer-domain>) içeren tek bir TXT kaydı döndürdüğünü, her iki.well-knownuç noktasının daContent-Type: application/jsondöndürdüğünü,.well-known/email-verificationadresininhttps://<issuer-domain>ile bayt bayt eşleşen birissueriçerdiğini veaccounts_endpointyanıtının,emaildeğeri girilen adresle eşleşen bir hesap içerdiğini doğrulayın. .well-known/email-verificationiçinde desteklenmeyen imzalama algoritması: Chrome 154 ve 155,signing_alg_values_supportediç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-Destbaşlığının yazımı: Chrome 154 ve sonraki sürümlerSec-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@authoritybileş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ı yerineX-Forwarded-Host(veya herkese açık kaynağınız) kullanarak yeniden oluşturun ve JSON ayrıştırmadan önce ham istek gövdesi baytları üzerindeContent-Digesthesaplayın.
Tarayıcı, döndürülen issuance_token değerini reddeder
- Değiştirilmiş veya kanonikleştirilmiş
emailtalebi: Chrome 156'dan itibaren tarayıcı, EVTemailtalebinin istenenemailile bire bir eşleştiğini kontrol eder. Arka ucunuz, adresi standart bir hesap biçimine normalleştirirse (ör.first.LAST@example.comistendiğindeFirst.Last@example.comdöndürülürse) Chrome, jetonu siler. İsteği kullanıcının hesabıyla eşleştirin ancak istek gövdesinde alınanemaildizesini aynen döndürün. - Sondaki tilde (
~) eksik: Sıfır açıklama olsa bileissuance_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
issveyacnf.jwk: EVTisshak talebinin,.well-known/email-verificationmeta verilerinizle eşleşen tam HTTPS kaynağı (https://<issuer-domain>, sonunda eğik çizgi olmadan) olduğundan vecnf.jwk'nin, tarayıcının geçici ortak anahtarınıSignature-Keyüstbilgisinden yerleştirdiğinden emin olun.