Ajax 요청에서 withCredentials 옵션의 의미와 주의할 점

date

Apr 6, 2025

slug

xhr-withcredentials-cors-guide

author

status

Public

1. withCredentials

withCredentials는 요청에 인증 정보를 포함할지 여부를 설정하는 옵션입니다. 이 credential은 보통 다음 두 가지 중 하나입니다:

쿠키 (특히 로그인 상태 유지용 세션 쿠키)

Authorization 헤더 (Bearer token 등)

API별 설정 방식


// axios
axios.get("https://example.com/items", {
  withCredentials: true
})

// fetch
fetch("https://example.com/users", {
  credentials: "include"
})

// XMLHttpRequest
const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

fetch에서는 옵션명이 credentials이며, "include", "same-origin", "omit" 세 가지 값을 사용할 수 있습니다. 기본값은 "same-origin"입니다.

2. 선택한 이유

CORS 요청에서 인증 정보를 함께 보내기 위해 withCredentials 옵션을 사용하게 되었습니다. 단순히 데이터를 가져오는 GET 요청이라도, 사용자의 인증 상태를 확인하기 위해 쿠키나 토큰을 포함해야 하는 경우가 많기 때문입니다.

3. 장점

사용자 인증 상태 유지: 서버 세션 기반 인증이라면 쿠키 없이 인증이 불가능하므로 필수입니다.

자동 로그인/인증 토큰 활용 가능: 한번 로그인한 상태를 유지하고 싶을 때 유용합니다.

권한 있는 API 요청 처리: Authorization 헤더 또는 쿠키가 필요한 보호 API 호출 시 활용됩니다.

4. 주의할 점

1) 서버에서도 응답 설정 필요

요청에 credential이 포함되어 있다면, 서버는 다음 응답 헤더를 반드시 설정해야 합니다:

Access-Control-Allow-Credentials: true

Access-Control-Allow-Origin: <정확한 origin> (와일드카드 사용 금지)

예:


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

2) 와일드카드 사용 금지

Allow-Origin, Allow-Methods, Allow-Headers 등의 CORS 응답 헤더에 *를 사용하면 브라우저가 응답 본문을 차단하여, 실제로는 응답을 받아도 JS 코드에서는 접근이 불가능합니다. 이는 자주 발생하는 CORS Error의 원인이기도 합니다.

3) preflight 요청은 credential을 보낼 수 없음

CORS 정책상 OPTIONS preflight 요청에는 쿠키나 Authorization 헤더를 포함할 수 없습니다. 하지만, 그에 대한 응답에서는 Access-Control-Allow-Credentials: true가 반드시 포함되어야 합니다.

5. 결론

프론트엔드 개발에서 서버와의 인증 정보를 안전하게 주고받기 위해서는 withCredentials 옵션의 정확한 의미와 동작 방식, 그리고 서버 응답 헤더의 설정까지 모두 고려해야 합니다. 특히 CORS와 보안 설정은 한쪽만 맞춰도 정상 동작하지 않기 때문에, 클라이언트와 서버가 동시에 맞춰야 하는 협업 요소임을 인식할 필요가 있습니다.

앞으로도 보안과 사용자 경험을 모두 고려한 안정적인 개발을 위해, 이런 세세한 옵션 하나도 더 깊이 이해하고 활용해 나가고자 합니다.