Implementazione del provider email (emittente)

Per ulteriori dettagli, puoi consultare il codice demo del provider email fittizio e fare riferimento ai passaggi dell'emittente nelle proposte dell'API Verifica email e del protocollo Verifica email.

In qualità di emittente, non devi registrarti per l'origin trial né fornire un token perché il sito della relying party attiva il comportamento del browser. Assicurati che gli endpoint siano configurati per rispondere a queste richieste.

Configurare il rilevamento dell'emittente

Per consentire ai browser di rilevare automaticamente gli endpoint di verifica quando viene selezionato un indirizzo email appartenente al tuo dominio, esponi la configurazione utilizzando il DNS e un endpoint HTTP .well-known.

Configurare il record del delegato DNS

Configura un record TXT DNS sul tuo dominio email che delega l'autorità di verifica al tuo identificatore dell'emittente. Questi identificatori possono utilizzare lo stesso dominio a seconda della tua infrastruttura.

Formato del record: _email-verification.<email-domain>

Esempio di file di zona:

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

Il valore iss= deve essere un nome host canonico in minuscolo (ad es. iss=accounts.issuer.example) senza schema (https://), porta, percorso o caratteri maiuscoli. Chrome rifiuta i record che includono componenti non host.

Ospitare un endpoint .well-known/email-verification

Ospita un file di metadati JSON sul tuo dominio dell'emittente nel percorso /.well-known/. Questo file descrive le tue funzionalità di emissione e gli algoritmi di firma crittografica supportati dalla tua infrastruttura.

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

Esempio di risposta:

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

Proprietà dei metadati:

  • issuer: l'origine dell'emittente (https://<issuer-domain>, senza barra finale ). Deve corrispondere all'origine da cui viene pubblicato il file di metadati byte per byte.
  • issuance_endpoint: l'URL HTTPS che riceve le richieste POST di emissione del token.
  • jwks_uri: l'URL HTTPS che pubblica il tuo set di chiavi web JSON (JWKS) pubblico.
  • signing_alg_values_supported: array di algoritmi di firma JWS supportati.

Ospitare un endpoint .well-known/web-identity

Potresti aver già implementato una risorsa JSON aggiuntiva .well-known nell' ambito dell'API Federated Credentials (FedCM). Questa risorsa fornisce link all'endpoint degli account e all'URL di accesso.

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

Esempio di risposta:

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

Utilizzare un endpoint degli account

L'endpoint degli account dell'API FedCM fornisce un elenco degli account con accesso eseguito al momento. L'esempio seguente mostra una risposta minima. Per ulteriori dettagli, consulta la guida all'implementazione del provider di identità.

Endpoint: come specificato in .well-known/web-identity

Di seguito è riportato un esempio di risposta:

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

Eseguire l'integrazione con l'API Login Status

L'utente deve avere una sessione attiva con il provider e tu devi segnalarlo al browser utilizzando l'API Login Status.

Quando un utente esegue l'accesso o esce correttamente, pubblica l'intestazione della risposta HTTP corrispondente:

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

In alternativa, aggiorna lo stato utilizzando JavaScript nel contesto dell'applicazione web:

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

Gestire le richieste di emissione

Il tuo issuance_endpoint riceve una richiesta application/json POST che contiene la chiave email e le intestazioni HTTP Message Signatures per Signature, Signature-Input, e Signature-Key.

Utilizza una libreria che supporti le intestazioni strutturate e le firme dei messaggi HTTP per il tuo ambiente. In Node.js puoi utilizzare structured-headers e http-message-sig.

Formato completo della richiesta:

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

Analizza e convalida la richiesta:

  • Autenticazione della sessione: convalida i cookie di sessione proprietari inviati con la richiesta. L'utente deve essere autenticato.
  • Intestazione Sec-Fetch-Dest: impostata su email-verification.
  • Firme dei messaggi HTTP: verifica la firma della richiesta utilizzando la chiave pubblica effimera in Signature-Key e convalida Content-Digest. A partire da Chrome 156, l'intestazione Signature-Key include alg="Ed25519" nei relativi hwk parametri; accetta "Ed25519" e "EdDSA" e consenti l'omissione di alg da parte delle versioni precedenti di Chrome.
  • Payload: il corpo JSON contiene la stringa email richiesta per la verifica.

Risposta di emissione

Una volta convalidati correttamente la sessione e il token della richiesta, genera un JWT di divulgazione selettiva (SD-JWT) firmato restituito come JSON utilizzando le librerie appropriate per la tua piattaforma. Ad esempio, per Node puoi utilizzare @sd-jwt/core e jose.

Il formato del payload non elaborato dovrebbe essere simile al seguente:

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

Crea, firma e restituisci il 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);

Il corpo della risposta risultante è simile al seguente:

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

Dopo aver creato e firmato il token di verifica dell'email, il browser lo passa al sito del verificatore per la convalida.

Risoluzione dei problemi

Se il browser non contatta i tuoi endpoint o rifiuta i token emessi, controlla i seguenti problemi comuni:

Il browser non chiama mai accounts_endpoint o issuance_endpoint

  • Stato di accesso non impostato: Chrome esegue query sugli endpoint solo se sa che l' utente ha eseguito l'accesso. Assicurati che il flusso di accesso imposti l'intestazione Set-Login: logged-in HTTP o chiami navigator.login.setStatus("logged-in").
  • Cookie di sessione bloccati (SameSite=None): il browser recupera accounts_endpoint e issuance_endpoint da una relying party su un altro sito. Poiché si tratta di richieste cross-site, il cookie di sessione deve includere SameSite=None; Secure. Un cookie SameSite=Lax funziona quando viene eseguito il test su un verificatore dello stesso sito, ma viene omesso nelle richieste cross-site.
  • Mancata corrispondenza tra rilevamento o account: verifica che _email-verification.<email-domain> restituisca un singolo record TXT con un nome host canonico in minuscolo (iss=<issuer-domain>, senza https://, una porta, un percorso o caratteri maiuscoli), che entrambi gli endpoint .well-known restituiscano Content-Type: application/json, che .well-known/email-verification abbia un issuer che corrisponda a https://<issuer-domain> byte per byte e che la accounts_endpoint risposta includa un account la cui email corrisponda all' indirizzo inserito.
  • Algoritmo di firma non supportato in .well-known/email-verification: Chrome 154 e 155 richiedono "EdDSA" in signing_alg_values_supported, mentre Chrome 156+ e la specifica IETF supportano "Ed25519". Pubblica entrambi ["Ed25519", "EdDSA"] durante la transizione in modo che Chrome Stable non rifiuti i metadati di rilevamento.

La convalida della richiesta di emissione non riesce

  • Sec-Fetch-Dest ortografia dell'intestazione: Chrome 154+ invia Sec-Fetch-Dest: email-verification (con un trattino), mentre Chrome 153 inviava emailverification (senza trattino). Accetta entrambi i valori durante il lancio.
  • Mancata corrispondenza della firma del messaggio HTTP (@authority) dietro un proxy: quando si verifica la firma RFC 9421, il componente @authority riflette l'host pubblico. Se il server si trova dietro un reverse proxy o un bilanciatore del carico, ricostruisci l'URL di verifica utilizzando X-Forwarded-Host (o l'origine pubblica) anziché il nome host interno e calcola Content-Digest sui byte del corpo della richiesta non elaborata prima dell'analisi JSON.

Il browser rifiuta issuance_token restituito

  • Rivendicazione email modificata o canonica: a partire da Chrome 156, il browser verifica che la rivendicazione email EVT corrisponda all'indirizzo email byte per byte. Se il backend normalizza l'indirizzo in un formato di account canonico (ad esempio, restituisce First.Last@example.com quando è stato richiesto first.LAST@example.com), Chrome elimina il token. Abbina la richiesta all'account dell'utente, ma restituisci la stringa email esatta ricevuta nel corpo della richiesta.
  • Tilde finale mancante (~): anche con zero divulgazioni, il issuance_token deve essere un SD-JWT valido che termina con una tilde finale (<Issuer-signed-JWT>~) in modo che il browser possa aggiungere <KB-JWT>.
  • Non corrispondenti iss o cnf.jwk: assicurati che la rivendicazione iss EVT sia l'origine HTTPS esatta (https://<issuer-domain>, senza barra finale) che corrisponda ai metadati .well-known/email-verification e che cnf.jwk incorpori la chiave pubblica effimera del browser dall'intestazione Signature-Key.