이메일 제공업체 (발급자) 구현

자세한 내용은 모의 이메일 제공업체 데모 코드 를 살펴보고 이메일 인증 API 및 이메일 인증 프로토콜 제안의 발급자 단계를 참고하세요.

발급기관은 오리진 트라이얼에 가입하거나 토큰을 제공할 필요가 없습니다. 의존 당사자 사이트에서 브라우저 동작을 트리거하기 때문입니다. 엔드포인트가 이러한 요청에 응답하도록 구성되어 있는지 확인하세요.

발급자 검색 구성

도메인에 속한 이메일 주소가 선택될 때 브라우저가 인증 엔드포인트를 자동으로 검색하도록 하려면 DNS 및 .well-known HTTP 엔드포인트를 사용하여 구성을 노출하세요.

DNS 위임 레코드 구성

인증 기관을 발급자 식별자로 위임하는 이메일 도메인에 DNS TXT 레코드를 구성합니다. 이러한 식별자는 인프라에 따라 동일한 도메인을 사용할 수 있습니다.

레코드 형식: _email-verification.<email-domain>

존 파일 예:

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

iss= 값은 스키마 (https://), 포트, 경로 또는 대문자가 없는 일반적인 소문자 호스트 이름 (예: iss=accounts.issuer.example)이어야 합니다. Chrome에서는 호스트 이름이 아닌 구성요소가 포함된 레코드를 거부합니다.

.well-known/email-verification 엔드포인트 호스팅

/.well-known/ 경로 아래의 발급자 도메인에서 JSON 메타데이터 파일을 호스팅합니다. 이 파일은 발급 기능과 인프라에서 지원하는 암호화 서명 알고리즘을 간략하게 설명합니다.

엔드포인트: https://<issuer-domain>/.well-known/email-verification

응답 예:

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

메타데이터 속성:

  • issuer: 발급자 출처 (https://<issuer-domain>, 후행 슬래시 없음) 메타데이터 파일이 바이트 단위로 제공되는 출처와 일치해야 합니다.
  • issuance_endpoint: 토큰 발급 POST 요청을 수신하는 HTTPS URL입니다.
  • jwks_uri: 공개 JSON 웹 키 세트 (JWKS)를 제공하는 HTTPS URL입니다.
  • signing_alg_values_supported: 지원되는 JWS 서명 알고리즘의 배열입니다.

.well-known/web-identity 엔드포인트 호스팅

Federated Credentials (FedCM) API의 일부로 추가 .well-known JSON 리소스를 이미 구현했을 수 있습니다. 이 리소스는 계정 엔드포인트 및 로그인 URL로 연결되는 링크를 제공합니다.

엔드포인트: https://<domain>/.well-known/web-identity

응답 예:

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

계정 엔드포인트 사용

FedCM API의 계정 엔드포인트는 현재 로그인된 계정 목록을 제공합니다. 다음 예는 최소 응답을 보여줍니다. 자세한 내용은 ID 제공업체 구현 가이드를 참고하세요.

엔드포인트: .well-known/web-identity에 지정된 대로

다음은 응답 예시입니다.

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

로그인 상태 API와 통합

사용자는 제공업체와 활성 세션을 보유해야 하며 로그인 상태 API를 사용하여 브라우저에 이를 알려야 합니다.

사용자가 로그인 또는 로그아웃하면 일치하는 HTTP 응답 헤더를 제공합니다.

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

또는 웹 애플리케이션 컨텍스트에서 JavaScript를 사용하여 상태를 업데이트합니다.

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

발급 요청 처리

issuance_endpoint는 application/json POST 요청을 수신합니다. 이 요청에는 email 키와 HTTP 메시지 서명 헤더(Signature, Signature-Input, Signature-Key)가 포함됩니다.

환경에 구조화된 헤더와 HTTP 메시지 서명을 지원하는 라이브러리를 사용합니다. Node.js에서는 structured-headers 및 http-message-sig를 사용할 수 있습니다.

전체 요청 형식:

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

요청 파싱 및 검증:

  • 세션 인증: 요청과 함께 전송된 퍼스트 파티 세션 쿠키를 검증합니다. 사용자를 인증해야 합니다.
  • Sec-Fetch-Dest 헤더: email-verification으로 설정합니다.
  • HTTP 메시지 서명: Signature-Key의 임시 공개 키를 사용하여 요청 서명을 확인하고 Content-Digest을 검증합니다. Chrome 156부터 Signature-Key 헤더는 alg="Ed25519"를 hwk 매개변수에 포함합니다. "Ed25519" 및 "EdDSA"를 허용하고 이전 Chrome 버전에서 alg를 생략하도록 허용합니다.
  • 페이로드: JSON 본문에는 인증을 위해 요청된 email 문자열이 포함되어 있습니다.

발급 응답

세션 및 요청 토큰이 검증되면 플랫폼에 적합한 라이브러리를 사용하여 JSON으로 반환되는 서명된 선택적 공개 JWT (SD-JWT)를 생성합니다. 예를 들어 Node의 경우 @sd-jwt/core 및 jose를 사용할 수 있습니다.

원시 페이로드 형식은 다음과 비슷해야 합니다.

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

토큰을 만들고 서명하고 반환합니다.

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);

결과 응답 본문은 다음과 비슷합니다.

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

이메일 인증 토큰을 만들고 서명하면 브라우저에서 검증 사이트로 전달하여 검증합니다.

문제 해결

브라우저가 엔드포인트에 연결하지 않거나 발급된 토큰을 거부하는 경우 다음과 같은 일반적인 문제를 확인하세요.

브라우저가 accounts_endpoint 또는 issuance_endpoint를 호출하지 않음

  • 로그인 상태가 설정되지 않음: Chrome은 사용자가 로그인한 것으로 알고 있는 경우에만 엔드포인트를 쿼리합니다. 로그인 흐름에서 Set-Login: logged-in HTTP 헤더를 설정하거나 navigator.login.setStatus("logged-in")을 호출하는지 확인하세요.
  • 세션 쿠키 차단 (SameSite=None): 브라우저가 다른 사이트의 의존 당사자로부터 accounts_endpoint 및 issuance_endpoint를 가져옵니다. 크로스 사이트 요청이므로 세션 쿠키에 SameSite=None; Secure가 포함되어야 합니다. SameSite=Lax 쿠키는 동일한 사이트 검증 도구에서 테스트할 때 작동하지만 크로스 사이트 요청에서는 생략됩니다.
  • 검색 또는 계정 불일치: _email-verification.<email-domain>이 표준 소문자 호스트 이름 (iss=<issuer-domain>, https://, 포트, 경로 또는 대문자 없음)이 포함된 단일 TXT 레코드를 반환하고, 두 .well-known 엔드포인트가 Content-Type: application/json을 반환하며, .well-known/email-verification에 https://<issuer-domain>과 바이트 단위로 일치하는 issuer가 있고, accounts_endpoint 응답에 입력된 주소와 일치하는 email이 포함된 계정이 있는지 확인합니다.
  • .well-known/email-verification에서 지원되지 않는 서명 알고리즘: Chrome 154 및 155에서는 signing_alg_values_supported에 "EdDSA"가 필요하지만 Chrome 156 이상 및 IETF 사양에서는 "Ed25519"를 지원합니다. 전환 중에 ["Ed25519", "EdDSA"]를 모두 알리므로 Chrome 안정화 버전에서 검색 메타데이터를 거부하지 않습니다.

발급 요청 검증 실패

  • Sec-Fetch-Dest 헤더 맞춤법: Chrome 154 이상에서는 Sec-Fetch-Dest: email-verification (하이픈 포함)을 전송하는 반면 Chrome 153에서는 emailverification (하이픈 없음)을 전송했습니다. 출시 중에 두 값을 모두 허용합니다.
  • 프록시 뒤의 HTTP 메시지 서명 (@authority) 불일치: RFC 9421 서명을 검증할 때 @authority 구성요소는 공개 호스트를 반영합니다. 서버가 리버스 프록시 또는 부하 분산기 뒤에 있는 경우 내부 호스트 이름 대신 X-Forwarded-Host (또는 공개 출처)를 사용하여 인증 URL을 재구성하고 JSON 파싱 전에 원시 요청 본문 바이트에 대해 Content-Digest를 계산합니다.

브라우저가 반환된 issuance_token을 거부함

  • 수정되거나 표준화된 email 클레임: Chrome 156부터 브라우저는 EVT email 클레임이 요청된 email 과 바이트 단위로 일치하는지 확인합니다. 백엔드에서 주소를 표준 계정 형식으로 정규화하는 경우 (예: first.LAST@example.com이 요청되었을 때 First.Last@example.com 반환) Chrome에서 토큰을 삭제합니다. 사용자 계정에 대해 요청을 일치시키되 요청 본문에서 수신된 정확한 email 문자열을 반환합니다.
  • 후행 물결표 (~) 누락: 공개가 0인 경우에도 브라우저에서 <KB-JWT>를 추가할 수 있도록 issuance_token은 후행 물결표 (<Issuer-signed-JWT>~)로 끝나는 유효한 SD-JWT여야 합니다.
  • iss 또는 cnf.jwk 불일치: EVT iss 클레임이 .well-known/email-verification 메타데이터와 일치하는 정확한 HTTPS 출처 (https://<issuer-domain>, 후행 슬래시 없음)이고 cnf.jwk가 Signature-Key 헤더의 브라우저 임시 공개 키를 삽입하는지 확인합니다.