Access-Control-Allow-Credentials

사용법

교차 출처 요청은 기본적으로 쿠키, Authorization 헤더, TLS 클라이언트 인증서 같은 자격 증명을 제외합니다. 클라이언트가 자격 증명 모드를 include로 설정하면, 브라우저가 호출한 스크립트에 응답 본문과 헤더를 노출하기 위해 서버는 값이 true인 Access-Control-Allow-Credentials를 반환해야 합니다.

사전 요청(preflight) 교환 중에 이 헤더는 실제 요청이 자격 증명을 실어 보낼 수 있는지를 나타냅니다. 사전 요청 응답에 이 헤더가 없거나 true가 아닌 값이 설정되어 있으면, 브라우저는 자격 증명이 포함된 요청을 완전히 차단합니다.

단순 CORS 요청(기본적인 GET처럼 사전 요청 단계가 없는 요청)에서도 브라우저는 응답을 받은 뒤 이 헤더를 확인합니다. 헤더가 없으면 응답은 조용히 폐기되어 호출 코드에 전달되지 않습니다.

참고

자격 증명이 포함될 때 Access-Control-Allow-Origin 헤더는 명시적인 오리진을 지정해야 합니다. 자격 증명이 포함된 요청에는 와일드카드 *가 허용되지 않습니다.

true

유일하게 유효한 값입니다. 이 헤더를 true로 포함시키면 자격 증명이 있을 때 응답을 노출하라고 브라우저에 알립니다.

Access-Control-Allow-Credentials: true

헤더를 생략하거나 다른 값을 보내면 결과는 같습니다. 브라우저는 응답을 자격 증명이 없는 것으로 취급하고 본문을 JavaScript에 전달하지 않습니다.

예시

프런트엔드 애플리케이션이 자격 증명을 포함한 교차 출처 fetch를 보냅니다. 서버는 자격 증명 헤더, 명시적인 오리진, 그리고 캐시가 오리진을 구분하도록 Vary 디렉티브와 함께 응답합니다.

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Credentials: true
Vary: Origin

자격 증명이 포함된 POST 요청의 사전 요청 중에 서버는 허용 메서드와 자격 증명 지원 여부를 모두 확인해 줍니다.

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: POST
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 3600
Vary: Origin

문제 해결

CORS 연쇄 중 어느 한 부분이라도 잘못 구성되면 자격 증명이 포함된 교차 출처 요청은 조용히 실패합니다.

서버가 Access-Control-Allow-Credentials: true를 반환하는데도 쿠키가 교차 출처로 전송되지 않습니다. 클라이언트 측 코드가 자격 증명 전송을 명시적으로 선택해야 합니다. Fetch API에서는 요청 옵션에 credentials: ‘include’를 전달하십시오. XMLHttpRequest에서는 send()를 호출하기 전에 withCredentials = true를 설정하십시오. 이 플래그가 없으면 브라우저는 서버 응답과 무관하게 교차 출처 요청에서 쿠키와 Authorization 헤더를 제거합니다.

콘솔에 “Cannot use wildcard in Access-Control-Allow-Origin when credentials flag is true.”가 표시됩니다. Access-Control-Allow-Credentials가 true일 때 Access-Control-Allow-Origin 헤더는 명시적인 오리진을 담아야 합니다. 들어오는 Origin 헤더를 읽어 허용 목록과 대조해 검증하고, 일치한 오리진을 그대로 돌려주며, 응답에 Vary: Origin을 추가하십시오. 같은 규칙이 Access-Control-Allow-Headers와 Access-Control-Allow-Methods에도 적용됩니다. 자격 증명이 포함된 요청에서는 이들 헤더의 와일드카드가 문자 그대로의 문자열로 취급됩니다.

fetch() 호출에 credentials: ‘include’가 빠져 있습니다. Fetch API의 기본값은 credentials: ‘same-origin’이며, 이는 교차 출처 요청에서 자격 증명을 제외합니다. { credentials: ‘include’ }를 명시적으로 전달하십시오. DevTools의 Network 탭에서 요청 헤더를 확인하십시오. 나가는 요청에 Cookie 헤더가 없다면 클라이언트가 자격 증명 전송을 선택하지 않은 것입니다.

XMLHttpRequest에 withCredentials = true가 빠져 있습니다. Fetch API와 마찬가지로 XMLHttpRequest는 withCredentials가 true로 설정되지 않는 한 교차 출처로 쿠키를 보내지 않습니다. 이 속성은 xhr.open()이나 xhr.send()를 호출하기 전에 설정해야 합니다. Axios 같은 라이브러리는 요청 설정에서 { withCredentials: true }로 이를 노출합니다.

SameSite 쿠키 속성이 교차 출처 전달을 차단합니다. 최신 브라우저는 SameSite 속성이 설정되지 않으면 기본적으로 SameSite=Lax를 적용합니다. Lax 쿠키는 교차 출처 POST나 하위 리소스 요청에서 전송되지 않습니다. 교차 출처로 전달되어야 하는 쿠키에는 SameSite=None과 Secure를 설정하십시오. DevTools의 Application에서 해당 속성을 확인하십시오.

쿠키. Secure가 없으면 브라우저는 SameSite=None 쿠키를 완전히 거부합니다.

서드파티 쿠키 단계적 폐지가 자격 증명을 차단합니다. Chrome을 비롯한 브라우저들이 서드파티 쿠키를 제한하고 있습니다. 다른 도메인이 설정한 쿠키에 의존하는 교차 출처 요청은 점점 더 많이 깨집니다. 가능하다면 Authorization 헤더를 사용하는 토큰 기반 인증으로 전환하거나, Storage Access API를 도입해 쿠키 접근을 명시적으로 요청하십시오. 배포 전에 문제를 드러내려면 Chrome에서 “Third-party cookie phaseout” 플래그를 켜고 테스트하십시오.