신뢰 당사자 구현

사이트에서 이메일 인증을 구현하려면 토큰을 요청하도록 양식 마크업을 업데이트하고 수신 토큰에 서버 측 유효성 검사를 추가하세요.

오리진 트라이얼 등록

사이트를 확인하려면 사이트에 오리진 트라이얼이 구성되어 있어야 합니다.

Chrome 154부터 서드 파티 오리진 트라이얼이 지원되지만 중요한 주의사항이 있습니다. 트라이얼에 등록된 오리진은 발급기관과 동일한 사이트여야 합니다 발급기관과 동일한 사이트여야 합니다. 예를 들면 다음과 같습니다.

  • 발급기관 도메인: issuer.example
  • OT 등록자: https://issuer.example
  • JavaScript 오리진: https://issuer.example (또는 하위 도메인 일치 포함 https://app.issuer.example)

양식 필드 구성

이메일 제출 양식에 숨겨진 토큰 필드를 추가합니다.

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

필드 요구사항:

  • 이메일 필드: Chrome에서 주소를 자동 완성하고 인식할 수 있도록 type="email" 및 autocomplete="email"을 설정합니다.
  • 토큰 필드 속성:
    • autocomplete="email-verification-token" 설정: Chrome에서 이 필드를 식별하여 제출 시 토큰을 채웁니다.
    • nonce="<VALUE>" 설정: 사이트에서 양식 제출을 확인하기 위해 고유한 세션 바인딩 nonce를 제공해야 합니다.

이메일 인증 토큰 (EVT) 검증

사용자가 양식을 제출하면 서버에서 숨겨진 필드의 이메일 주소와 토큰을 수신합니다. 빈 토큰 필드는 브라우저 또는 제공업체가 EVP를 지원하지 않거나 사용자가 인증을 건너뛴다는 것을 나타냅니다. 이 경우 OTP 또는 매직 링크 전송과 같은 기존 인증 절차로 대체합니다.

토큰이 있으면 다음과 같이 검증합니다.

  1. SD-JWT 라이브러리를 사용하여 토큰을 파싱합니다.
  2. 예상 값 및 세션 클레임을 검증합니다.
  3. DNS 위임을 확인합니다.
  4. 발급기관 메타데이터를 탐색하고 JWKS를 가져옵니다.
  5. 암호화 서명 및 키 바인딩을 확인합니다.

1. 토큰 파싱

토큰은 RFC 9901: 선택적 공개 JWT (SD-JWT+KB) 형식을 사용합니다. 토큰을 파싱하고 검증하려면 플랫폼에 적합한 라이브러리를 사용하세요. 예를 들어 Node의 경우 @sd-jwt/core 및 jose를 사용할 수 있습니다. 원시 형식은 다음과 같습니다. 발급기관 서명 JWT, 그 뒤에 0개 이상의 공개가 오고 각 구성요소가 물결표로 구분된 키 바인딩 JWT로 끝납니다.

<Issuer-signed EVT>~<Disclosure 1>~...~<Disclosure N>~<Key Binding JWT>

현재 구현에서 토큰에는 공개가 포함되어 있지 않습니다 (<Issuer-signed EVT>~<Key Binding JWT>). 하지만 향후 변경될 수 있습니다.

라이브러리로 토큰을 디코딩합니다.

import { decodeSdJwtSync } from "@sd-jwt/core";
import { createHash } from "node:crypto";
const hasher = (data, alg) =>
  createHash(alg === "sha-256" ? "sha256" : alg)
    .update(data)
    .digest();
const decoded = decodeSdJwtSync(rawToken, hasher);
const evtPayload = decoded.jwt.payload;
const kbPayload = decoded.kbJwt?.payload;

verifier.example이 demo@provider.example을 검증하면 디코딩된 토큰은 다음과 비슷합니다.

{
  "evtJwtDecodedHeader": {
    "typ": "evt+jwt",
    "alg": "EdDSA",
    "kid": "issuer-key-id"
  },
  "evtJwtDecodedPayload": {
    "iss": "https://provider.example",
    "iat": 12345678901,
    "exp": 12345679901,
    "cnf": {
      "jwk": {
        "kty": "OKP",
        "crv": "Ed25519",
        "x": "pUbLiCkEy123pUbLiCkEy123pUbLiCkEy123"
      }
    },
    "email": "demo@provider.example",
    "email_verified": true
  },
  "kbJwtDecodedHeader": {
    "alg": "EdDSA",
    "typ": "kb+jwt"
  },
  "kbJwtDecodedPayload": {
    "aud": "https://verifier.example",
    "iat": 12345678901,
    "nonce": "rAnDoM123rAnDoM123rAnDoM123rAnDoM123",
    "sd_hash": "hAsH456hAsH456hAsH456hAsH456hAsH456"
  },
  "disclosures": []
}

2. 예상 값 및 세션 클레임 검증

페이로드의 기본 값이 제공된 값 및 예상 값과 일치하는지 확인합니다.

  • email_verified: true여야 합니다.
  • email: 양식에 제출된 이메일 주소와 일치해야 합니다.
  • aud (대상): 사이트의 오리진과 일치해야 합니다.
  • nonce: 양식에 제공된 nonce와 일치해야 합니다.
  • iat (발급 시간) 및 exp (만료): 토큰이 유효한 기간 내에 있고 만료되지 않았는지 확인합니다.

3. DNS 위임 확인

이메일 주소 도메인의 _email-verification DNS 레코드를 확인합니다. 예를 들어 demo@gmail.com의 경우 _email-verification.gmail.com TXT 레코드를 쿼리합니다. 이 제공업체의 경우 쿼리는 계정 제공업체의 위치, 즉 accounts.google.com을 반환합니다.

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

발급기관 스키마가 https://이고 https://<domain>이 EVT의 iss 클레임과 일치하는지 확인합니다.

4. EVT 서명 확인

https://<issuer>/.well-known/email-verification에서 발급기관의 검색 메타데이터를 가져옵니다.

{
  "issuer": "https://accounts.google.com",
  "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": ["Ed25519", "EdDSA"]
}

메타데이터에 issuer 필드가 포함되어 있으면 EVT의 iss 클레임과 바이트 단위로 일치하는지 확인합니다. jwks_uri에서 JSON 웹 키 세트를 가져옵니다.

SD-JWT 라이브러리를 사용하여 토큰 패키지를 확인합니다. 라이브러리는 유효성 검사를 조정합니다.

  1. 가져온 JWKS에 대해 EVT의 발급기관 서명을 검증합니다.
  2. cnf.jwk의 임시 공개 키를 사용하여 KB-JWT의 브라우저 서명을 검증합니다.
  3. 키 바인딩 (aud, nonce, 다이제스트 해시 sd_hash)을 확인합니다.

Node.js의 검증 로직 예:

import { SDJwtInstance } from "@sd-jwt/core";
import { importJWK, compactVerify } from "jose";
import { createHash } from "node:crypto";
const allowedAlgs = ["Ed25519", "EdDSA", "ES256"];
const evtAlg = decoded.jwt.header.alg;
const kbAlg = decoded.kbJwt?.header.alg;
if (!allowedAlgs.includes(evtAlg) || !allowedAlgs.includes(kbAlg)) {
  throw new Error("Unsupported signing algorithm");
}
const hasher = (data, alg) =>
  createHash(alg === "sha-256" ? "sha256" : alg)
    .update(data)
    .digest();
const sdJwt = new SDJwtInstance({ hasher });
sdJwt.config({
  hasher,
  // Verifier for the Issuer-signed EVT
  verifier: async (data, sig) => {
    const token = `${data}.${sig}`;
    const header = decoded.jwt.header;
    // Match by kid if present, or iterate across matching algorithm keys
    const keysToTry = header.kid
      ? jwksData.keys.filter(k => k.kid === header.kid)
      : jwksData.keys;
    for (const jwk of keysToTry) {
      try {
        const pubKey = await importJWK(jwk, jwk.alg || evtAlg);
        await compactVerify(token, pubKey);
        return true;
      } catch {
        // Try next candidate key
      }
    }
    return false;
  },
  // Verifier for the Key Binding JWT (KB-JWT)
  kbVerifier: async (data, sig) => {
    try {
      const browserJwkKey = evtPayload.cnf?.jwk;
      if (!browserJwkKey) return false;
      const pubKey = await importJWK(browserJwkKey, kbAlg);
      await compactVerify(`${data}.${sig}`, pubKey);
      return true;
    } catch {
      return false;
    }
  },
});
// The library automatically verifies EVT signature, KB-JWT signature, audience, nonce, and sd_hash
const result = await sdJwt.verify(rawToken, {
  kb: {
    expectedNonce: sessionNonce,
    expectedAudience: "https://example.com",
    required: true,
  },
});
const verifiedPayload = result.payload;
if (
  verifiedPayload.email_verified !== true ||
  verifiedPayload.email?.toLowerCase() !== submittedEmail.toLowerCase()
) {
  throw new Error("Token email does not match submitted email");
}

모든 단계가 성공하면 제공업체에 대해 이메일 주소를 확인한 것입니다. 인증에 실패하면 일반적인 절차를 사용하여 사용자에게 확인 이메일을 보내는 것으로 대체합니다.

문제 해결

인증에 실패하거나 브라우저에서 토큰을 제공하지 않는 경우 다음과 같은 일반적인 문제를 확인하세요.

제출 시 토큰 필드가 비어 있음

  • 오리진 트라이얼 등록: 페이지에 Origin-Trial 헤더 또는 <meta> 태그가 제공되고 토큰이 만료일을 지나지 않았는지 확인합니다 (Chrome 160 확장 프로그램 전에 생성된 토큰은 11월 17일 2026년에 만료됨). 서드 파티 오리진 트라이얼 (Chrome 154 이상)의 경우 등록된 트라이얼 오리진은 발급기관 (https://<issuer-domain>)과 동일한 사이트여야 합니다. 개발자 도구의 애플리케이션 > 프레임 > (관련 프레임 선택) > 오리진 트라이얼 에서 사이트의 오리진 트라이얼 상태와 토큰 만료를 검사할 수 있습니다.
  • 양식 마크업: <input type="email" autocomplete="email">과 <input type="hidden" autocomplete="email-verification-token" nonce="..."> 이 모두 동일한 <form> 요소에 있어야 하며 (섀도우 DOM 경계에서 격리되지 않음) nonce가 비어 있으면 안 됩니다.
  • 조기 제출 또는 재사용된 페이지: 이메일이 입력되거나 자동 완성된 후 브라우저에서 백그라운드로 토큰을 가져옵니다. 요청이 완료되기 전에 제출하면 토큰이 비어 있게 됩니다. 사용자가 이메일을 입력한 후 Return 키를 눌러 양식을 제출하는 경우 발생할 수 있습니다.
  • 브라우저 및 제공업체 필수 조건: 사용자는 동일한 브라우저 프로필에서 참여 제공업체에 로그인되어 있어야 하며 Chrome 설정 (chrome://settings/contactInfo)에서 이메일 인증이 사용 설정되어 있어야 합니다.

발급기관 서명 검증 실패

  • kid 헤더 누락: EVT 헤더 및 JWKS의 kid (키 ID) 클레임은 선택사항입니다 (예: Gmail은 kid을 생략함). kid이 없으면 키 ID 조회를 실패하는 대신 발급기관의 jwks_uri에서 모든 후보 키를 반복합니다.
  • 알고리즘 식별자 (Ed25519 및 EdDSA): Chrome 156부터 Chrome은 cnf.jwk 및 KB-JWT 헤더에 완전히 지정된 Ed25519 알고리즘 식별자 (RFC 9864)를 사용하지만 발급기관과 라이브러리는 Ed25519 또는 EdDSA (및 ES256)를 지정할 수 있습니다. JWK 가져오기 및 검증 로직이 두 식별자를 모두 허용하는지 확인하세요.
  • 발급기관 (iss) 오리진 형식: DNS TXT 레코드 (_email-verification.<domain>)에는 기본 호스트 이름 (iss=accounts.issuer.example)이 포함되어 있지만 EVT iss 클레임은 후행 슬래시가 없는 전체 HTTPS 오리진 (https://accounts.issuer.example)입니다. 비교하기 전에 DNS 레코드 값에 https://를 접두사로 추가합니다.

키 바인딩 (KB-JWT) 검증 실패

  • nonce 불일치 또는 만료: nonce에 렌더링된 <input> 가 서버의 활성 세션 nonce와 일치하고 다른 탭에 의해 덮어쓰이지 않았거나 이전 요청에서 사용되지 않았는지 확인합니다.
  • 대상 (aud) 불일치: aud 클레임은 검증 도구의 HTTPS 오리진 (https://verifier.example, 경로 또는 후행 슬래시 없음)입니다.

이메일 클레임 (email) 비교 실패

  • 대소문자 및 정규화: Chrome 156 이상은 양식에 입력된 대로 email 클레임을 바이트 단위로 반환하지만 이전 브라우저 버전 또는 제공업체는 정규화된 주소를 반환할 수 있습니다 (예: first.last@example.com의 경우 First.Last@example.com). 토큰의 email 클레임을 제출된 양식 값과 일치시킬 때는 대소문자를 구분하지 않는 비교를 사용하세요.