[Vue.js] axios.defaults.withCredentials = true는 왜 사용하는 걸까?

JWT 로그인 기능을 구현하다 보면 자주 보게 되는 코드가 있다.

axios.defaults.withCredentials = true;

 

처음에는 "쿠키를 보내기 위한 설정인가?" 정도로만 이해했지만, 실제로 로그인 기능을 구현하면서 이 옵션이 왜 필요한지 정확히 알게 되었다.

 

📗 먼저 알아야 하는 것

나의 프로젝트의 구조는 다음과 같다.

• Vue3 : http://localhost:5173
• Node.js(Express) : http://localhost:3000

프론트엔드와 백엔드의 포트가 다르기 때문에 브라우저 입장에서는 다른 Origin(출처) 으로 인식한다.

Origin은 다음 3가지가 모두 같아야 한다.

• 프로토콜(http/https)
• 도메인(localhost)
• 포트(5173, 3000)

즉

http://localhost:5173

 

에서

http://localhost:3000

으로 요청하는 것은 Cross Origin 요청이다.

 

💡 로그인은 어떻게 이루어질까?

사용자가 로그인 버튼을 누른다.

Vue
    │
    ▼
POST /api/login/auth
    │
    ▼
Node 서버

로그인이 성공하면 서버는 JWT를 생성한다.

const token = jwt.sign(payload, "my_secret_key", {
    expiresIn: "1h"
});

그리고 브라우저에게 쿠키를 저장하라고 응답한다.

res.cookie("token", token, {
    httpOnly: true
});

브라우저는 응답을 받은 뒤 쿠키를 저장한다.

Browser

token = eyJhbGciOiJIUzI1Ni...

여기까지는 정상이다.

 

🧨 그런데 문제가 발생한다.

로그인 후 문서 목록을 가져온다고 가정해보자.

axios.get("http://localhost:3000/api/documents/list")

대부분은 당연히

GET /api/documents/list

Cookie:
token=eyJ...

이렇게 요청이 갈 것이라고 생각한다.

하지만 실제로는

GET /api/documents/list

(쿠키 없음)

위와 같이 전송된다.

 

브라우저가 쿠키를 일부러 빼버리는 것이다.

 

💁‍♂️ 왜 쿠키를 안 보내는 걸까?

결국은 보안 때문이다.

브라우저는 다른 Origin으로 요청할 때 쿠키를 자동으로 보내지 않는다.

만약 아무 사이트나 다른 서버의 쿠키를 마음대로 보낼 수 있다면 보안 문제가 발생할 수 있기 때문이다.

그래서 브라우저는

 

"이 요청은 다른 Origin인데 정말 쿠키를 같이 보낼 거야?"

 

라고 한 번 더 확인한다.

이때 사용하는 옵션이 바로

withCredentials

 

이다.

 

withCredentials를 사용하면

axios.get(
    "http://localhost:3000/api/documents/list",
    {
        withCredentials: true
    }
)

브라우저는 이제

GET /api/documents/list

Cookie:
token=eyJ...

를 함께 전송한다.

 

Node에서는

req.cookies.token

으로 JWT를 읽을 수 있다.

 

axios.defaults.withCredentials = true

하지만 매번

withCredentials: true

를 적는 것은 번거롭다.

그래서 axios에서는 기본 설정을 제공한다.

axios.defaults.withCredentials = true;

이 한 줄을 작성하면

axios.get(...)
axios.post(...)
axios.put(...)
axios.patch(...)
axios.delete(...)

모든 요청에 자동으로

withCredentials: true

가 적용된다.

 

즉

axios.get("/api/list");

를 실행해도 내부적으로는

axios.get("/api/list", {
    withCredentials: true
});

위와 같이 동일하게 동작한다.

 

물론! 서버도 설정해야 한다.

클라이언트에서 쿠키를 보내겠다고 해도 서버가 허용하지 않으면 브라우저는 쿠키를 보내지 않는다.

그러기에 Express에서는 CORS 설정에

app.use(cors({
    origin: "http://localhost:5173",
    credentials: true
}));

를 반드시 추가해야 한다.

 

여기서

credentials: true

는

 

"이 Origin에서 쿠키를 포함한 요청을 허용한다."

 

라는 의미이다.

 

🎈 전체 로그인 흐름

사용자 로그인
        │
        ▼
Vue (axios.post)
        │
        ▼
Node 로그인 처리
        │
        ▼
JWT 생성
        │
        ▼
res.cookie("token", token)
        │
        ▼
브라우저에 쿠키 저장
        │
        ▼
axios 요청 발생
        │
        ▼
axios.defaults.withCredentials = true
        │
        ▼
브라우저가 Cookie를 함께 전송
        │
        ▼
Node
req.cookies.token
        │
        ▼
jwt.verify()
        │
        ▼
로그인 사용자 확인
        │
        ▼
API 실행

 

최종정리

axios.defaults.withCredentials = true는 JWT를 생성하는 코드도 아니고, 쿠키를 저장하는 코드도 아니다.

이 옵션의 역할은 그저 브라우저에 저장되어 있는 쿠키를 이후의 모든 Axios 요청에 함께 전송하도록 브라우저에 알려주는 것이다.

JWT를 HttpOnly 쿠키 방식으로 관리하는 프로젝트에서는 거의 필수적으로 사용하는 설정이며, 서버의 cors({ credentials: true }) 설정과 함께 사용해야 정상적으로 인증이 동작한다.

이번 프로젝트를 구현하면서 직접 로그인, 새로고침, 인증 확인 과정을 디버깅해 보니 단순히 "외워서 쓰는 옵션"이 아니라 브라우저의 보안 정책과 쿠키 전송 방식을 이해하는 데 중요한 설정이라는 것을 알게 되었다.