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

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

비공개 상태 토큰은 웹에서 정보를 공유하는 방법을 제공하지만 실제로 공유할 수 있는 데이터의 양을 제어하여 개인 정보를 보호합니다.

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

이 문서에서는 비공개 상태 토큰 (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의 전체 기간을 신중하게 정의해야 합니다. 이 기간에 따라 케이스에서 RR을 사용할 수 있는 횟수가 정의되기 때문입니다.

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

시나리오 예시

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

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

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

데모 실행

PST를 도입하기 전에 먼저 데모를 설정하는 것이 좋습니다. PST 데모를 사용해 보려면 데모 발급자 키 약속을 사용 설정하는 플래그를 사용하여 Chrome을 실행해야 합니다 (데모 페이지의 안내 참고).

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

기술적 고려사항

다음 단계를 구현하면 데모가 가장 잘 실행됩니다.

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

채택 설정

발급자 되기

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

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

발급기관 서버

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

환경 배포: 발급자 서버

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

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

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

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

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

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

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

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

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

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

발급자 서버에 호출 전송

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

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

코드 예시 보기

Redeemer 서버

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

발급자와 사용 권한 구매자를 동일한 서버 (또는 서버 그룹)에서 실행하도록 선택할 수 있습니다.

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

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

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

리디머 서버에 호출 전송

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

    // 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명 이하의 사용자가 사용할 수 있음: 문제가 발생할 경우 문제 해결을 간소화해야 합니다.

권한 정책

제대로 작동하려면 최상위 페이지와 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를 사용 설정하려면 출처 목록을 *로 설정합니다.

권한 정책으로 개인 정보 보호 샌드박스 기능을 제어하는 방법을 알아보거나 권한 정책에 대해 자세히 알아보세요.

문제 해결

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에서 제공되는 짧은 동영상과 도움말을 검토하세요.