관련 웹사이트 세트: 개발자 가이드

관련 웹사이트 세트 (RWS)는 브라우저가 도메인 모음 간의 관계를 이해하는 데 도움이 되는 웹 플랫폼 메커니즘입니다. 이를 통해 브라우저는 특정 사이트 기능을 사용 설정할지 (예: 크로스 사이트 쿠키에 대한 액세스 허용 여부)와 같은 주요 결정을 내리고 이 정보를 사용자에게 표시할 수 있습니다.

많은 사이트에서 단일 사용자 환경을 제공하기 위해 여러 도메인을 사용합니다. 조직에서는 국가별 도메인이나 이미지 또는 동영상을 호스팅하는 서비스 도메인과 같은 여러 사용 사례에 대해 서로 다른 최상위 도메인을 유지관리할 수 있습니다. 관련 웹사이트 세트를 사용하면 사이트가 특정 관리 기능을 통해 도메인 간에 데이터를 공유할 수 있습니다.

관련 웹사이트 세트란 무엇인가요?

요약하자면 관련 웹사이트 세트는 단일 '세트 기본'과 잠재적으로 여러 '세트 구성원'이 있는 도메인 모음입니다.

다음 예시에서 primary에는 기본 도메인이 나열되고 associatedSites에는 연결된 하위 집합의 요구사항을 충족하는 도메인이 나열됩니다.

{
  "primary": "https://primary.com",
  "associatedSites": ["https://associate1.com", "https://associate2.com", "https://associate3.com"]
}

관련 웹사이트 세트는 GitHub에 호스팅된 공개 JSON 파일에 나열됩니다. 이는 승인된 모든 세트의 표준 소스입니다. 브라우저는 이 파일을 사용하여 사이트가 동일한 관련 웹사이트 세트에 속하는지 여부를 확인합니다.

도메인을 관리하는 사용자만 해당 도메인으로 세트를 만들 수 있습니다. 제출자는 각 '세트 구성원'과 '세트 기본' 간의 관계를 선언해야 합니다. 세트 구성원에는 다양한 도메인 유형이 포함될 수 있으며 사용 사례에 기반한 하위 집합에 속해야 합니다.

애플리케이션이 동일한 관련 웹사이트 세트 내의 사이트 간 교차 사이트 쿠키 (서드 파티 쿠키라고도 함)에 대한 액세스에 의존하는 경우 Storage Access API (SAA) 및 requestStorageAccessFor API를 사용하여 이러한 쿠키에 대한 액세스를 요청할 수 있습니다. 각 사이트가 속한 하위 집합에 따라 브라우저가 요청을 다르게 처리할 수 있습니다.

세트 제출 절차 및 요구사항에 대해 자세히 알아보려면 제출 가이드라인을 참고하세요. 제출된 세트는 제출을 검증하기 위해 다양한 기술 검사를 거칩니다.

관련 웹사이트 세트 사용 사례

관련 웹사이트 세트는 조직이 여러 최상위 사이트에서 공유 ID가 필요한 경우에 적합합니다.

관련 웹사이트 세트의 사용 사례는 다음과 같습니다.

• 국가 맞춤설정 공유 인프라를 사용하는 동안 현지화된 사이트를 활용합니다 (예: example.co.uk가 example.ca에서 호스팅하는 서비스를 사용할 수 있음).
• 서비스 도메인 통합 사용자가 직접 상호작용하지는 않지만 동일한 조직의 사이트 (example-cdn.com) 전반에서 서비스를 제공하는 서비스 도메인을 활용합니다.
• 사용자 콘텐츠 분리 보안상의 이유로 사용자 업로드 콘텐츠를 다른 사이트 콘텐츠와 분리하는 여러 도메인의 데이터에 액세스하면서 샌드박스 도메인이 인증 (및 기타) 쿠키에 액세스하도록 허용합니다. 비활성 상태의 사용자가 업로드한 콘텐츠를 제공하는 경우 권장사항에 따라 동일한 도메인에서 안전하게 호스팅할 수도 있습니다.
  • 인증된 콘텐츠가 삽입됨 계열사 속성 전반의 삽입된 콘텐츠 (동영상, 문서 또는 최상위 사이트에 로그인한 사용자에게만 제공되는 리소스) 지원
• 로그인 계열사 속성 간 로그인 지원 FedCM API도 일부 사용 사례에 적합할 수 있습니다.
• 분석. 서비스 품질을 개선하기 위해 제휴 속성 전반에서 사용자 여정 분석 및 측정 배포

관련 웹사이트 세트 통합 세부정보

Storage Access API

Storage Access API (SAA)는 삽입된 교차 출처 콘텐츠가 일반적으로 퍼스트 파티 컨텍스트에서만 액세스할 수 있는 스토리지에 액세스할 수 있는 방법을 제공합니다.

삽입된 리소스는 SAA 메서드를 사용하여 현재 스토리지에 액세스할 수 있는지 확인하고 사용자 에이전트로부터 액세스 권한을 요청할 수 있습니다.

서드 파티 쿠키가 차단되었지만 관련 웹사이트 세트 (RWS)가 사용 설정된 경우 Chrome은 RWS 내 컨텍스트에서 자동으로 권한을 부여하고 그 외의 경우에는 사용자에게 프롬프트를 표시합니다. ('RWS 내 컨텍스트'는 삽입된 사이트와 최상위 사이트가 동일한 RWS에 있는 iframe과 같은 컨텍스트입니다.)

저장소 액세스 확인 및 요청

현재 스토리지에 액세스할 수 있는지 확인하기 위해 삽입된 사이트는 Document.hasStorageAccess() 메서드를 사용할 수 있습니다.

이 메서드는 문서가 쿠키에 이미 액세스할 수 있는지 여부를 나타내는 불리언 값으로 확인되는 프로미스를 반환합니다. 또한 iframe이 최상위 프레임과 출처가 동일한 경우 프로미스가 true를 반환합니다.

크로스 사이트 컨텍스트에서 쿠키에 대한 액세스를 요청하기 위해 삽입된 사이트는 Document.requestStorageAccess()(rSA)를 사용할 수 있습니다.

requestStorageAccess() API는 iframe 내에서 호출해야 합니다. 해당 iframe은 사용자 상호작용 (모든 브라우저에서 요구하는 사용자 동작)을 방금 수신해야 하지만, Chrome에서는 지난 30일 동안 사용자가 해당 iframe을 소유한 사이트를 방문하고 iframe이 아닌 최상위 문서로 해당 사이트와 구체적으로 상호작용해야 합니다.

requestStorageAccess()는 저장소 액세스가 허용된 경우 확인되는 프라미스를 반환합니다. 어떤 이유로든 액세스가 거부되면 이유를 인용하여 프로미스가 거부됩니다.

Chrome의 requestStorageAccessFor

Storage Access API를 사용하면 삽입된 사이트가 사용자 상호작용을 수신한 <iframe> 요소 내에서만 스토리지 액세스를 요청할 수 있습니다.

이로 인해 쿠키가 필요한 크로스 사이트 이미지 또는 스크립트 태그를 사용하는 최상위 사이트에서 Storage Access API를 채택하는 데 어려움이 있습니다.

이 문제를 해결하기 위해 Chrome에서는 최상위 사이트가 Document.requestStorageAccessFor()(rSAFor)를 사용하여 특정 출처를 대신하여 저장소 액세스를 요청할 수 있는 방법을 구현했습니다.

 document.requestStorageAccessFor('https://target.site')

requestStorageAccessFor() API는 최상위 문서에서 호출해야 합니다. 또한 해당 문서에 최근 사용자 상호작용이 있어야 합니다. 하지만 requestStorageAccess()와 달리 Chrome은 사용자가 이미 페이지에 있으므로 지난 30일 이내에 최상위 문서에서 상호작용이 있었는지 확인하지 않습니다.

스토리지 액세스 권한 확인

카메라나 위치 정보와 같은 일부 브라우저 기능에 대한 액세스는 사용자가 부여한 권한을 기반으로 합니다. Permissions API는 API 액세스 권한 상태를 확인하는 방법을 제공합니다. 권한이 부여되었는지, 거부되었는지, 프롬프트를 클릭하거나 페이지와 상호작용하는 등 사용자 상호작용이 필요한지 등을 확인할 수 있습니다.

navigator.permissions.query()를 사용하여 권한 상태를 쿼리할 수 있습니다.

현재 컨텍스트의 저장소 액세스 권한을 확인하려면 'storage-access' 문자열을 전달해야 합니다.

navigator.permissions.query({name: 'storage-access'})

지정된 출처의 저장소 액세스 권한을 확인하려면 'top-level-storage-access' 문자열을 전달해야 합니다.

navigator.permissions.query({name: 'top-level-storage-access', requestedOrigin: 'https://target.site'})

삽입된 출처의 무결성을 보호하기 위해 이 검사는 document.requestStorageAccessFor를 사용하여 최상위 문서에서 부여한 권한만 확인합니다.

권한이 자동으로 부여될 수 있는지 아니면 사용자 동작이 필요한지에 따라 prompt 또는 granted이 반환됩니다.

프레임별 모델

rSA 권한은 프레임별로 적용됩니다. rSA 및 rSAFor 권한은 별도의 권한으로 취급됩니다.

각 새 프레임은 개별적으로 저장소 액세스를 요청해야 하며 액세스 권한이 자동으로 부여됩니다. 첫 번째 요청에만 사용자 동작이 필요하며 탐색이나 하위 리소스와 같이 iframe에서 시작된 후속 요청은 사용자 동작을 기다릴 필요가 없습니다. 초기 요청에 의해 탐색 세션에 권한이 부여되기 때문입니다.

새로고침, 다시 로드 또는 기타 방법으로 iframe을 다시 만들려면 액세스 권한을 다시 요청해야 합니다.

쿠키 요구사항

쿠키는 SameSite=None 및 Secure 속성을 모두 지정해야 합니다. rSA는 크로스 사이트 컨텍스트에서 사용하도록 이미 표시된 쿠키에 대한 액세스 권한만 제공하기 때문입니다.

SameSite=Lax, SameSite=Strict 또는 SameSite 속성이 없는 쿠키는 퍼스트 파티 전용이며 rSA와 관계없이 크로스 사이트 컨텍스트에서 절대 공유되지 않습니다.

보안

rSAFor의 경우 하위 리소스 요청에는 교차 출처 리소스 공유(CORS) 헤더 또는 리소스의 crossorigin 속성이 필요하여 명시적 선택을 보장합니다.

구현 예

삽입된 교차 출처 iframe에서 스토리지 액세스 요청

저장소 액세스 권한이 있는지 확인

이미 스토리지 액세스 권한이 있는지 확인하려면 document.hasStorageAccess()를 사용하세요.

프로미스가 true로 확인되면 크로스 사이트 컨텍스트에서 저장소에 액세스할 수 있습니다. false로 확인되면 저장소 액세스를 요청해야 합니다.

document.hasStorageAccess().then((hasAccess) => {
    if (hasAccess) {
      // You can access storage in this context
    } else {
      // You have to request storage access
    }
});

스토리지 액세스 권한 요청

저장소 액세스 권한을 요청해야 하는 경우 먼저 저장소 액세스 권한 navigator.permissions.query({name: 'storage-access'})을 확인하여 사용자 동작이 필요한지 아니면 자동으로 부여될 수 있는지 확인합니다.

권한이 granted인 경우 document.requestStorageAccess()를 호출할 수 있으며 사용자 동작 없이 성공해야 합니다.

권한 상태가 prompt인 경우 버튼 클릭과 같은 사용자 동작 후에 document.requestStorageAccess() 호출을 시작해야 합니다.

예:

navigator.permissions.query({name: 'storage-access'}).then(res => {
  if (res.state === 'granted') {
    // Permission has already been granted
    // You can request storage access without any user gesture
    rSA();
  } else if (res.state === 'prompt') {
    // Requesting storage access requires user gesture
    // For example, clicking a button
    const btn = document.createElement("button");
    btn.textContent = "Grant access";
    btn.addEventListener('click', () => {
      // Request storage access
      rSA();
    });
    document.body.appendChild(btn);
  }
});

function rSA() {
  if ('requestStorageAccess' in document) {
    document.requestStorageAccess().then(
      (res) => {
        // Use storage access
      },
      (err) => {
        // Handle errors
      }
    );
  }
}

프레임, 탐색 또는 하위 리소스 내에서 이루어지는 후속 요청에는 교차 사이트 쿠키에 액세스할 수 있는 권한이 자동으로 부여됩니다. hasStorageAccess()는 true를 반환하고 동일한 관련 웹사이트 세트의 크로스 사이트 쿠키는 추가 JavaScript 호출 없이 이러한 요청에 전송됩니다.

크로스 오리진 사이트를 대신하여 쿠키 액세스를 요청하는 최상위 사이트

최상위 사이트는 requestStorageAccessFor()를 사용하여 특정 출처를 대신하여 저장소 액세스를 요청할 수 있습니다.

hasStorageAccess()는 이를 호출하는 사이트에 저장소 액세스 권한이 있는지 여부만 확인하므로 최상위 사이트에서 다른 출처의 권한을 확인할 수 있습니다.

사용자에게 메시지가 표시되는지 또는 지정된 출처에 스토리지 액세스 권한이 이미 부여되었는지 확인하려면 navigator.permissions.query({name: 'top-level-storage-access', requestedOrigin: 'https://target.site'})를 호출하세요.

권한이 granted이면 document.requestStorageAccessFor('https://target.site')를 호출할 수 있습니다. 사용자 동작 없이 성공해야 합니다.

권한이 prompt인 경우 버튼 클릭과 같은 사용자 동작 뒤에 document.requestStorageAccessFor('https://target.site') 호출을 연결해야 합니다.

예:

navigator.permissions.query({name:'top-level-storage-access',requestedOrigin: 'https://target.site'}).then(res => {
  if (res.state === 'granted') {
    // Permission has already been granted
    // You can request storage access without any user gesture
    rSAFor();
  } else if (res.state === 'prompt') {
    // Requesting storage access requires user gesture
    // For example, clicking a button
    const btn = document.createElement("button");
    btn.textContent = "Grant access";
    btn.addEventListener('click', () => {
      // Request storage access
      rSAFor();
    });
    document.body.appendChild(btn);
  }
});

function rSAFor() {
  if ('requestStorageAccessFor' in document) {
    document.requestStorageAccessFor().then(
      (res) => {
        // Use storage access
      },
      (err) => {
        // Handle errors
      }
    );
  }
}

requestStorageAccessFor() 호출이 성공하면 교차 사이트 요청에 CORS 또는 crossorigin 속성이 포함된 경우 쿠키가 포함되므로 사이트에서 요청을 트리거하기 전에 기다릴 수 있습니다.

요청은 credentials: 'include' 옵션을 사용해야 하며 리소스에는 crossorigin="use-credentials" 속성이 포함되어야 합니다.

function checkCookie() {
    fetch('https://related-website-sets.glitch.me/getcookies.json', {
        method: 'GET',
        credentials: 'include'
      })
      .then((response) => response.json())
      .then((json) => {
      // Do something
      });
  }

로컬에서 테스트하는 방법

기본 요건

관련 웹사이트 세트를 로컬에서 테스트하려면 명령줄에서 실행되는 Chrome 119 이상을 사용하고 test-third-party-cookie-phaseout Chrome 플래그를 사용 설정하세요.

Chrome 플래그 사용 설정

필요한 Chrome 플래그를 사용 설정하려면 주소 표시줄에서 chrome://flags#test-third-party-cookie-phaseout로 이동하여 플래그를 Enabled로 변경합니다. 플래그를 변경한 후 브라우저를 다시 시작해야 합니다.

로컬 관련 웹사이트 세트로 Chrome 실행

로컬로 선언된 관련 웹사이트 세트로 Chrome을 실행하려면 세트의 구성원인 URL이 포함된 JSON 객체를 만들어 --use-related-website-set에 전달하세요.

플래그를 사용하여 Chromium을 실행하는 방법을 자세히 알아보세요.

--use-related-website-set="{\"primary\": \"https://related-website-sets.glitch.me\", \"associatedSites\": [\"https://rws-member-1.glitch.me\"]}" \
https://related-website-sets.glitch.me/

예

로컬에서 관련 웹사이트 세트를 사용 설정하려면 chrome://flags에서 test-third-party-cookie-phaseout를 사용 설정하고, 세트의 구성원인 URL이 포함된 JSON 객체와 함께 --use-related-website-set 플래그를 사용하여 명령줄에서 Chrome을 실행해야 합니다.

--use-related-website-set="{\"primary\": \"https://related-website-sets.glitch.me\", \"associatedSites\": [\"https://rws-member-1.glitch.me\"]}" \
https://related-website-sets.glitch.me/

크로스 사이트 쿠키에 액세스할 수 있는지 확인

테스트 중인 사이트에서 API (rSA 또는 rSAFor)를 호출하고 크로스 사이트 쿠키에 대한 액세스를 검증합니다.

관련 웹사이트 세트 제출 절차

다음 단계에 따라 도메인 간의 관계를 선언하고 도메인이 속한 하위 집합을 지정하세요.

1. RWS 식별

관련 웹사이트 세트에 포함될 기본 설정 및 구성원 설정을 비롯한 관련 도메인을 식별합니다. 각 집합 구성원이 속한 하위 집합 유형도 식별합니다.

2. RWS 제출 만들기

GitHub 저장소의 로컬 복사본 (클론 또는 포크)을 만듭니다. 새 브랜치에서 related_website_sets.JSON 파일을 변경하여 세트를 반영합니다. 세트의 JSON 형식과 구조가 올바른지 확인하려면 JSON 생성기 도구를 사용하세요.

3. RWS가 기술 요구사항을 충족하는지 확인

세트 형성 요구사항과 세트 검증 요구사항이 적용되었는지 확인합니다.

4. RWS를 로컬로 테스트

세트를 제출하기 위한 풀 요청(PR)을 만들기 전에 제출을 로컬에서 테스트하여 필수 검사를 모두 통과하는지 확인하세요.

5. RWS 제출

Chrome에서 표준 관련 웹사이트 세트 목록을 호스팅하는 related_website_sets.JSON 파일에 PR을 만들어 관련 웹사이트 세트를 제출합니다. (PR을 만들려면 GitHub 계정이 필요하며 목록에 기여하려면 참여자 라이선스 계약 (CLA)에 서명해야 합니다.)

PR이 생성되면 3단계의 요구사항(예: CLA 서명 여부, .well-known 파일의 유효성)이 충족되는지 확인하기 위해 일련의 검사가 완료됩니다.

성공하면 PR에 검사를 통과했음이 표시됩니다. 승인된 PR은 매주 화요일 오후 12시 (동부 시간)에 표준 관련 웹사이트 세트 목록에 일괄적으로 수동 병합됩니다. 검사 중 하나라도 실패하면 GitHub의 PR 실패를 통해 제출자에게 알림이 전송됩니다. 제출자는 오류를 수정하고 PR을 업데이트할 수 있으며 다음 사항을 염두에 두어야 합니다.

• PR이 실패하면 오류 메시지에 제출이 실패한 이유에 관한 추가 정보가 표시됩니다. (예)
• 세트 제출을 관리하는 모든 기술 검사는 GitHub에서 진행되므로 기술 검사로 인해 발생하는 모든 제출 실패는 GitHub에서 확인할 수 있습니다.

엔터프라이즈 정책

Chrome에는 엔터프라이즈 사용자의 요구사항을 충족하기 위한 두 가지 정책이 있습니다.

• 관련 웹사이트 세트와 통합할 수 없는 시스템은 RelatedWebsiteSetsEnabled 정책을 사용하여 모든 엔터프라이즈 Chrome 인스턴스에서 관련 웹사이트 세트 기능을 사용 중지할 수 있습니다.
  • 일부 엔터프라이즈 시스템에는 등록 가능한 도메인이 관련 웹사이트 세트의 도메인과 다른 내부 전용 사이트 (예: 인트라넷)가 있습니다. 이러한 사이트를 공개적으로 노출하지 않고 (도메인이 기밀일 수 있음) 관련 웹사이트 세트의 일부로 취급해야 하는 경우 RelatedWebsiteSetsOverrides 정책을 사용하여 공개 관련 웹사이트 세트 목록을 보강하거나 재정의할 수 있습니다.

Chrome은 replacements 또는 additions가 지정되었는지에 따라 두 가지 방법 중 하나로 공개 및 엔터프라이즈 집합의 교차점을 해결합니다.

예를 들어 공개 세트 {primary: A, associated: [B, C]}의 경우 다음과 같습니다.

관련 웹사이트 세트 문제 해결

'사용자 프롬프트' 및 '사용자 동작'

'사용자 프롬프트'와 '사용자 동작'은 서로 다른 개념입니다. Chrome은 동일한 관련 웹사이트 세트에 있는 사이트에 대해 사용자에게 권한 메시지를 표시하지 않지만, 사용자가 페이지와 상호작용한 적이 있어야 합니다. 권한을 부여하기 전에 Chrome에서는 사용자 동작('사용자 상호작용' 또는 '사용자 활성화'라고도 함)이 필요합니다. 이는 관련 웹사이트 세트 컨텍스트 (즉, requestStorageAccess()) 외부에서 Storage Access API를 사용하는 경우에도 웹 플랫폼 설계 원칙에 따라 사용자 동작이 필요하기 때문입니다.

다른 사이트의 쿠키 또는 저장소에 액세스

관련 웹사이트 세트는 서로 다른 사이트의 스토리지를 병합하지 않습니다. 프롬프트가 없는 requestStorageAccess() 호출만 더 쉽게 허용합니다. 관련 웹사이트 세트는 스토리지 액세스 API 사용 시 사용자 마찰만 줄여주며 액세스가 복원된 후의 작업은 지시하지 않습니다. A와 B가 동일한 관련 웹사이트 세트의 서로 다른 사이트이고 A가 B를 삽입하는 경우 B는 사용자에게 메시지를 표시하지 않고 requestStorageAccess()를 호출하여 퍼스트 파티 스토리지에 액세스할 수 있습니다. 관련 웹사이트 세트는 크로스 사이트 통신을 실행하지 않습니다. 예를 들어 관련 웹사이트 세트를 설정해도 B에 속한 쿠키가 A로 전송되지는 않습니다. 이 데이터를 공유하려면 B iframe에서 A 프레임으로 window.postMessage를 전송하는 등 직접 공유해야 합니다.

기본적으로 파티셔닝되지 않은 쿠키 액세스

관련 웹사이트 세트에서는 API를 호출하지 않고는 파티션을 나누지 않은 쿠키에 대한 암시적 액세스를 허용하지 않습니다. 크로스 사이트 쿠키는 세트 내에서 기본값으로 제공되지 않습니다. 관련 웹사이트 세트는 세트 내 사이트가 Storage Access API 권한 메시지를 건너뛸 수 있도록만 허용합니다. iframe이 쿠키에 액세스하려면 document.requestStorageAccess()를 호출해야 하며, 최상위 페이지는 document.requestStorageAccessFor()를 호출할 수 있습니다.

의견 공유

GitHub에 세트를 제출하고 스토리지 액세스 API 및 requestStorageAccessFor API를 사용하면 프로세스에 대한 경험과 발생한 문제를 공유할 수 있습니다.

관련 웹사이트 세트에 관한 토론에 참여하려면 다음 단계를 따르세요.

• 관련 웹사이트 세트 공개 메일링 리스트에 가입합니다.
  • 관련 웹사이트 세트 GitHub 저장소에서 문제를 제기하고 토론을 팔로우하세요.