비공개 상태 토큰 개발자 가이드

이전에는 서드 파티 쿠키가 로그인 상태, 사용 중인 기기에 관한 정보, 알려진 사용자 및 신뢰할 수 있는 사용자인지 여부와 같은 사용자 상태에 관한 정보를 저장하고 전달하는 데 사용되었습니다. 예를 들어 사용자가 SSO로 로그인했는지, 사용자가 특정 유형의 호환 기기를 보유하고 있는지, 사용자가 알려져 있고 신뢰할 수 있는지 등이 있습니다. 서드 파티 쿠키 지원이 중단됨에 따라 이러한 사용 사례 중 다수는 다른 방법으로 지원해야 합니다.

Private State Tokens는 실제로 공유할 수 있는 데이터 양을 제어하여 개인 정보 보호 방식으로 웹 전반에서 정보를 공유하는 방법을 제공합니다.

비공개 상태 토큰 (이전 명칭: 신뢰 토큰)을 사용하면 패시브 추적 없이도 한 컨텍스트에서 다른 컨텍스트로 사용자 인증에 대한 신뢰를 전달할 수 있으므로 사이트에서 사기를 방지하고 실제 사람과 봇을 구분할 수 있습니다.

이 문서에서는 비공개 상태 토큰 (PST) 구현에 관한 기술 세부정보를 간략하게 설명합니다. 개략적인 개요는 PST 개요를 참고하세요.

비공개 상태 토큰은 어떻게 작동하나요?

PST에서 이해해야 하는 주요 관계는 발급자와 사용자의 관계입니다. 발급자와 사용자는 동일한 회사에 속할 수 있습니다.

• 발급자 - 이러한 법인은 사용자에 관한 신호 (예: 사용자가 봇인지 여부)를 보유하고 있으며 해당 신호를 사용자 기기에 저장된 토큰에 삽입합니다 (자세한 내용은 다음 섹션 참고).
• 리디머 - 이러한 법인은 사용자에 관한 신호가 없을 수 있지만 사용자에 관해 알아야 하는 사항 (예: 해당 사용자가 봇인지 여부)이 있으며 발급자로부터 토큰을 사용하도록 요청하여 해당 사용자의 신뢰성을 파악해야 합니다.

모든 PST 상호작용에는 발급자와 교환자가 웹 전반에서 신호를 공유하기 위해 협력해야 합니다. 이러한 신호는 개인을 식별할 만큼 자세하지 않은 대략적인 값입니다.

비공개 상태 토큰이 적합한가요?

신뢰 결정을 내리고 여러 컨텍스트에서 해당 정보를 사용할 수 있도록 하려는 회사에 PST가 유용할 수 있습니다. PST의 잠재적 사용 사례에 대한 자세한 내용은 PST 사용 사례에 관한 문서를 참고하세요.

토큰 발급 및 사용

PST 구현은 다음 세 단계로 진행됩니다.

1. 토큰 발급
2. 토큰 사용
3. 판매대금 지급 기록 전달

첫 번째 단계에서는 토큰이 브라우저에 발급됩니다 (일반적으로 일종의 유효성 검사 후). 두 번째 단계에서는 다른 법인이 토큰에 발급된 토큰을 사용하여 해당 토큰의 값을 읽도록 요청합니다. 마지막 단계에서 교환 당사자는 토큰에 포함된 값이 있는 교환 기록 (RR)을 수신합니다. 그러면 보상 당사자는 다양한 목적으로 해당 기록을 해당 사용자의 증명으로 사용할 수 있습니다.

토큰 전략 정의

토큰 전략을 정의하려면 PST 핵심 개념 (토큰 및 사용 기록), 변수, 동작, 제한사항을 이해하여 사용 사례에 대한 잠재적 사용을 고려할 수 있어야 합니다.

토큰과 사용 기록: 어떤 관계가 있나요?

각 기기는 최상위 웹사이트 및 발급자당 최대 500개의 토큰을 저장할 수 있습니다. 또한 각 토큰에는 발급자가 토큰을 발급하는 데 사용한 키를 알려주는 메타데이터가 있습니다. 이 정보는 사용 프로세스 중에 토큰을 사용할지 여부를 결정하는 데 사용할 수 있습니다. PST 데이터는 브라우저에 의해 사용자의 기기에 내부적으로 저장되며 PST API를 통해서만 액세스할 수 있습니다.

토큰이 사용되면 사용 기록 (RR)이 기기에 저장됩니다. 이 스토리지는 향후 사용을 위한 캐시 역할을 합니다. 기기, 페이지, 발급자당 48시간마다 토큰 2개로 제한됩니다. 새 상환 호출은 가능한 경우 발급자에게 요청을 전송하는 대신 캐시된 RR을 사용합니다.

1. 새 토큰이 발급됩니다 (발급자, 사이트, 기기당 최대 500개).
2. 모든 토큰은 기기 내 토큰 저장소 (쿠키 저장소와 유사)에 저장됩니다.
3. 활성 RR이 없으면 발급 후 새 RR을 생성할 수 있습니다(48시간마다 최대 2개).
4. RR은 만료될 때까지 활성 상태로 간주되며 로컬 캐시로 사용됩니다.
5. 새 사용 호출은 로컬 캐시를 사용합니다 (새 RR이 생성되지 않음).

사용 사례를 정의한 후에는 케이스에서 사용할 수 있는 횟수를 정의하므로 RR의 수명을 신중하게 정의해야 합니다.

전략을 정의하기 전에 다음 중요한 동작과 변수를 이해해야 합니다.

시나리오 예시

시나리오 1: RR 수명이 24시간 미만 (t=t)이고 48시간 기간 동안 여러 번 사용됩니다.

시나리오 2: RR 수명이 24시간이고 48시간 동안 여러 번 사용됩니다.

시나리오 3: RR 수명이 48시간이고 48시간 기간 동안 여러 번 사용됩니다.

데모 실행

PST를 도입하기 전에 데모를 설정하는 것이 좋습니다.

이 데모를 실행하면 브라우저가 데모 발급자 및 리디머 서버를 사용하여 토큰을 제공하고 소비합니다.

기술적 고려사항

다음 단계를 구현하면 데모가 최적의 상태로 실행됩니다.

• 플래그와 함께 Chrome을 실행하기 전에 모든 Chrome 인스턴스를 중지해야 합니다.
• Windows 컴퓨터에서 실행하는 경우 Chrome 실행 파일 바이너리에 매개변수를 전달하는 방법을 설명하는 이 가이드를 참고하세요.
• 데모 애플리케이션을 사용하는 동안 애플리케이션 > 저장소 > 비공개 상태 토큰에서 Chrome DevTools를 열어 데모 발급자가 발급하거나 사용한 토큰을 확인합니다.

도입 설정

이 섹션에서는 PST 발급자 또는 교환자가 되기 위한 요구사항을 설명합니다.

발급자 되기

발급자는 PST에서 중요한 역할을 합니다. 이러한 시스템은 토큰에 값을 할당하여 사용자가 봇인지 여부를 확인합니다. 발급자로서 PST를 시작하려면 발급자 등록 절차를 완료하여 등록해야 합니다.

발급자가 되려면 발급자 웹사이트 운영자가 '새 PST 발급자' 템플릿을 사용하여 GitHub 저장소에 새 문제를 열어야 합니다. 저장소의 안내에 따라 문제를 작성합니다. 엔드포인트가 확인되면 이 저장소에 병합되고 Chrome 서버 측 인프라에서 해당 키를 가져오기 시작합니다.

발급기관 서버

발급기관과 사용자는 PST의 주요 행위자이며 서버와 토큰은 PST의 주요 도구입니다. 토큰에 관한 세부정보는 이미 GitHub 문서에 제공되어 있지만 PST 서버에 관한 세부정보를 추가로 제공하고자 합니다. PST 발급자로 설정하려면 먼저 발급 서버를 설정해야 합니다.

환경 배포: 발급자 서버

토큰 발급자 서버를 구현하려면 HTTP 엔드포인트를 노출하는 자체 서버 측 애플리케이션을 빌드해야 합니다.

발급자 구성요소는 (1) 발급자 서버와 (2) 토큰 발급자라는 두 가지 주요 모듈로 구성됩니다.

모든 웹 기반 애플리케이션과 마찬가지로 발급자 서버에 추가 보호 레이어를 적용하는 것이 좋습니다.

1. 발급자 서버: 예시 구현에서 발급 서버는 Express 프레임워크를 사용하여 발급자 HTTP 엔드포인트를 호스팅하는 Node.js 서버입니다. GitHub의 샘플 코드를 확인하세요.

2. 토큰 발급자: 발급자 암호화 구성요소에는 특정 언어가 필요하지 않지만 이 구성요소의 성능 요구사항으로 인해 토큰을 관리하는 Boring SSL 라이브러리를 사용하는 C 구현이 예로 제공됩니다. 발급자 코드 예시와 설치에 관한 자세한 내용은 GitHub에서 확인하세요.

3. 키: 토큰 발급자 구성요소는 맞춤 EC 키를 사용하여 토큰을 암호화합니다. 이러한 키는 보호되어 안전한 저장소에 저장되어야 합니다.

발급자 서버의 기술 요구사항

프로토콜에 따라 발급자 서버에서 HTTP 엔드포인트를 두 개 이상 구현해야 합니다.

• 키 커밋 (예: /.well-known/private-state-token/key-commitment): 이 엔드포인트는 브라우저가 서버가 합법적인지 확인할 수 있도록 암호화 공개 키 세부정보가 제공되는 곳입니다.
  • GitHub의 코드 샘플
  • 데모 보기
• 토큰 발급 (예: /.well-known/private-state-token/issuance): 모든 토큰 요청이 처리되는 토큰 발급 엔드포인트입니다. 이 엔드포인트는 토큰 발급기관 구성요소의 통합 지점이 됩니다.
  • GitHub의 코드 샘플
  • 데모 보기

앞서 언급한 바와 같이 이 서버는 트래픽이 많을 수 있으므로 가변적인 수요에 따라 백엔드를 조정할 수 있도록 확장 가능한 인프라 (예: 클라우드 환경)를 사용하여 배포하는 것이 좋습니다.

발급기관 서버에 호출 전송

새 토큰을 발급하기 위해 발급자 스택에 웹사이트 가져오기 호출을 구현합니다.

 // issuer request
    await fetch("/.well-known/private-state-token/issuance", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-request"
      }
    });

코드 예시 보기

리디머 서버

자체 서버 측 애플리케이션을 빌드하여 토큰 사용 서비스를 구현해야 합니다. 이렇게 하면 발급자가 전송하는 토큰을 읽을 수 있습니다. 다음 단계에서는 토큰을 사용하는 방법과 이러한 토큰과 연결된 사용 기록을 읽는 방법을 간략히 설명합니다.

발급자와 교환자를 동일한 서버 (또는 서버 그룹)에서 실행할 수 있습니다.

리디머 서버의 기술 요구사항

프로토콜에 따라 리디머 서버에 대해 두 개 이상의 HTTP 엔드포인트를 구현해야 합니다.

• /.well-known/private-state-token/redemption: 모든 토큰 사용이 처리되는 엔드포인트입니다. 이 엔드포인트는 토큰 리디머 구성요소가 통합될 위치입니다.
  • GitHub의 예시 코드
  • 데모

리디머 서버에 호출 전송

토큰을 사용하려면 이전에 발급된 토큰을 사용하기 위해 리디머 스택에 대한 웹사이트 가져오기 호출을 구현해야 합니다.

    // redemption request
    await fetch("/.well-known/private-state-token/redemption", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-redemption",
        refreshPolicy: "none"
      }
    });

코드 샘플을 참고하세요.

토큰을 사용한 후 다른 가져오기 호출을 실행하여 사용 기록 (RR)을 전송할 수 있습니다.

    // attach redemption records from the issuers to the request
    await fetch("<DESTINATION_RESOURCE>", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "send-redemption-record",
        issuers: [<ISSUER_DOMAIN>]
      }
    });

코드 샘플을 참고하세요.

구현 배포

구현을 테스트하려면 먼저 호출이 이루어지는 웹페이지로 이동하여 토큰이 로직에 따라 생성되는지 확인합니다. 백엔드에서 호출이 사양에 따라 이루어졌는지 확인합니다. 그런 다음, 사용 호출이 이루어지는 웹페이지로 이동하여 논리에 따라 RR이 생성되었는지 확인합니다.

실제 배포

특정 사용 사례에 속하는 타겟 웹사이트를 선택하는 것이 좋습니다.

• 월별 방문수가 적음 (~ 100만 회 미만/월): 먼저 소수의 잠재고객에게 API를 배포하는 것부터 시작해야 합니다.
• 소유 및 제어: 필요한 경우 복잡한 승인 없이 구현을 빠르게 사용 중지할 수 있습니다.
• 발급자 1명 이하: 테스트를 간소화하기 위해 토큰 수를 제한합니다.
• 2명 이하의 사용권 구매자: 문제가 발생할 경우 문제 해결을 간소화해야 합니다.

권한 정책

PST API가 제대로 작동하려면 최상위 페이지와 API를 사용하는 모든 하위 리소스에서 PST API를 사용할 수 있어야 합니다.

토큰 요청 작업은 private-state-token-issuance 지시문에 의해 제어됩니다. token-redemption 및 send-redemption-record 작업은 private-state-token-redemption 지시문에 의해 제어됩니다. Chrome 132 이상에서는 이러한 지시어의 허용 목록이 기본적으로 * (모든 출처)로 설정됩니다. 즉, 이 기능은 명시적 위임 없이 최상위 페이지, 동일 출처 iframe, 교차 출처 iframe에서 사용할 수 있습니다.

각 페이지의 Permissions-Policy 헤더에 private-state-token-issuance=() 및 private-state-token-redemption=()를 포함하여 사이트의 특정 페이지에 대한 PST 토큰 발급 또는 사용을 선택 해제할 수 있습니다.

Permissions-Policy 헤더를 사용하여 PST에 대한 서드 파티 액세스를 제어할 수도 있습니다. 헤더 출처 목록의 파라미터로 self 및 API 액세스를 허용할 출처를 사용합니다. 예를 들어 자체 출처와 https://example.com을 제외한 모든 탐색 컨텍스트에서 PST 사용을 완전히 사용 중지하려면 다음 HTTP 응답 헤더를 설정합니다.

Permissions-Policy:private-state-token-issuance=(self "https://example.com"),private-state-token-redemption=(self "https://example.com")

모든 교차 출처 리소스에 API를 사용 설정하려면 출처 목록을 *로 설정합니다.

권한 정책으로 Privacy Sandbox 기능을 제어하는 방법을 알아보거나 권한 정책을 자세히 알아보세요.

문제 해결

Chrome DevTools 네트워크 및 애플리케이션 탭에서 PST를 검사할 수 있습니다.

네트워크 탭에서 다음을 실행합니다.

애플리케이션 탭에서 다음을 확인합니다.

이 DevTools 통합에 대해 자세히 알아보세요.

클라이언트 권장사항

웹사이트의 중요한 기능이 특정 토큰 발급자에 의존하는 경우 해당 토큰 발급자를 우선순위로 지정하세요. 다른 스크립트를 로드하기 전에 이러한 기본 발급자를 위해 hasPrivateToken(issuer)을 호출합니다. 이는 잠재적인 사용 실패를 방지하는 데 매우 중요합니다.

최상위 도메인당 발급자 수는 2개로 제한되며, 서드 파티 스크립트가 hasPrivateToken(issuer)를 호출하여 자체 선호 발급자의 우선순위를 지정할 수도 있습니다. 따라서 사이트가 예상대로 작동하도록 필수 발급자를 미리 확보하세요.

  // Prioritize your critical token issuer.
  document.hasPrivateToken('https://critical-issuer.example')
    .then(hasToken => {
      if (hasToken) {
        // Use the token or perform actions based on its availability.
      } else {
        // Handle the case where the token is not available.
      }
    });

  // Load third-party scripts or secure another token issuer (up to two in total).

서버 권장사항 및 문제 해결

발급자 및 리디머 서버가 효과적으로 작동하려면 PST에 대한 액세스, 보안, 로깅 또는 트래픽 문제가 발생하지 않도록 다음 권장사항을 구현하는 것이 좋습니다.

• 엔드포인트는 TLS 1.3 또는 1.2를 사용하여 강력한 암호화를 적용해야 합니다.
• 인프라가 급증을 포함한 다양한 트래픽 양을 처리할 수 있어야 합니다.
• 액세스 제어 정책, 키 관리 전략, 비즈니스 연속성 계획에 따라 키가 보호되고 안전한지 확인하세요.
• 스택에 관측 가능성 측정항목을 추가하여 프로덕션으로 전환한 후 사용량, 병목 현상, 성능 문제를 파악할 수 있도록 합니다.

추가 정보

1. 개발자 문서를 검토하세요.
   1. 먼저 개요를 읽고 PST와 그 기능을 숙지합니다.
   2. PST 소개 동영상을 시청하세요.
   3. PST 데모를 사용해 보세요.
   4. API 설명을 읽고 자세한 내용을 알아보세요.
   5. API의 현재 사양에 대해 자세히 알아보세요.
2. GitHub 문제 또는 W3C 통화를 사용하여 대화에 참여하세요.
3. 용어에 대해 자세히 알아보려면 개인 정보 보호 샌드박스 용어집을 참고하세요.
4. '오리진 트라이얼' 또는 'Chrome 플래그'와 같은 Chrome 개념에 관해 자세히 알아보려면 goo.gle/cc에서 제공되는 짧은 동영상과 도움말을 검토하세요.