Cookie의 domain 속성과 localhost에서 사용 시 주의사항

서론

기존 프로젝트에서 서브도메인을 도입하면서, localStorage가 서브도메인 간에 공유되지 않아 저장소를 localStorage에서 cookie로 옮기는 작업을 진행했습니다. 그런데 cookie의 도메인 설정이 호스팅 중인 개발 서버에서는 잘 적용되는데, 로컬 환경에서만 적용되지 않는 문제가 있었습니다. 확인해보니 원인은 localhost라는 주소 자체에 있었습니다.

쿠키에 도메인 설정 방법

개발할 때 로컬 환경에서 먼저 테스트해보고 이상이 없으면 개발/운영 환경에 반영하는 경우가 많습니다. 이때 주소로 localhost를 많이 사용하는데, localhost에서 cookie의 domain을 설정할 때 보통 아래처럼 동작할 것이라고 생각하기 쉽습니다.

// HTML 쿠키 설정
document.cookie = "name=Kim";

위 JavaScript 코드는 키가 name, 값이 Kim인 cookie를 설정하라는 의미입니다. 결과는 사진처럼 개발자 도구의 Application 탭에서 확인할 수 있습니다.

// localhost와 그 하위도메인의 쿠키 설정
document.cookie = "name=Kim;domain=localhost";

그렇다면 m.localhost와 localhost처럼 도메인이 같은 여러 주소들 간에 cookie를 공유해야 할 때는 어떻게 해야 할까요? MDN 문서에서는 위 코드처럼 domain 속성을 사용하라고 안내하고 있습니다.

하지만 m.localhost처럼 서브도메인 주소에서 cookie를 확인해보면, 값이 존재하지 않는 것을 볼 수 있습니다. HTTP 상태 관리 메커니즘을 다루는 RFC 6265를 보면 그 이유를 이해할 수 있는데요. Section 5.3.6에 따르면 domain 속성 값이 규칙에 부합하지 않으면, cookie 생성 요청을 완전히 무시합니다. 도메인 규칙은 Section 5.1.3에서 확인할 수 있습니다.

도메인 규칙은 아래 3가지를 모두 만족해야 합니다.

1. 도메인 문자열은 문자열의 접미사일 것
2. 문자열에 포함되지 않은 마지막 문자 도메인 문자열은 %x2E(".") 문자일 것
3. 문자열은 호스트 이름일 것(예: IP 주소가 아님)

localhost는 접두사/접미사 구분이 없고 "."도 없습니다. 따라서 위 도메인 규칙에 어긋나기 때문에 cookie가 생성되지 않았던 것입니다.

해결 방안

127.0.0.1은 자기 자신을 가리키는 주소입니다. localhost는 127.0.0.1의 도메인 네임이며, 이를 도메인 규칙에 맞는 다른 호스트명으로 변경하면 cookie의 domain 속성에 정상적으로 사용할 수 있습니다.

가장 간단한 방법은 hosts 파일을 수정하는 것입니다. hosts 파일은 Windows의 경우 C:\\Windows\\System32\\drivers\\etc\\hosts, macOS의 경우 /private/etc/hosts에 위치합니다. 파일을 텍스트 에디터로 열어 아래 항목을 추가한 뒤 저장해주시면 됩니다.

127.0.0.1       localhost.com
127.0.0.1       m.localhost.com

저는 위 두 개의 주소만 사용할 예정이라 두 줄만 추가했습니다. 그리고 cookie 설정도 아래처럼 변경합니다.

// HTML 쿠키 설정
document.cookie = "name=Kim;domain=localhost.com";

localhost.com와 m.localhost.com으로 접속했을 때 cookie가 정상적으로 공유되는 것을 확인할 수 있습니다.

다만 이 방식으로 로컬 도메인을 바꾸면, API를 호출할 때 origin이 달라져 CORS 오류가 발생할 수 있습니다. 따라서 백엔드 쪽에서도 origin 허용 목록에 localhost.com, m.localhost.com을 추가해주셔야 정상적으로 개발할 수 있습니다.

※ API 사용 시 참고 API 호출 시 CORS 오류가 발생한다면, 서버의 origin 예외 처리 항목에 localhost.com, m.localhost.com을 추가해주셔야 합니다.

Cypress로 cookie 테스트 자동화하기

로컬 환경에서 cookie domain 설정이 정상 동작하는지 매번 수동으로 확인하는 건 비효율적입니다. Cypress를 활용하면 서브도메인 간 cookie 공유 여부를 자동으로 검증할 수 있습니다.

// cypress/e2e/cookie-domain.cy.js
describe('서브도메인 간 cookie 공유 테스트', () => {
  it('localhost.com에서 설정한 cookie가 m.localhost.com에서도 조회되어야 한다', () => {
    // 1. localhost.com에서 cookie 설정
    cy.visit('http://localhost.com:3000');
    cy.setCookie('name', 'Kim', { domain: '.localhost.com' });
 
    // 2. cookie가 정상적으로 설정되었는지 확인
    cy.getCookie('name').should('have.property', 'value', 'Kim');
 
    // 3. m.localhost.com으로 이동하여 cookie 공유 확인
    cy.visit('http://m.localhost.com:3000');
    cy.getCookie('name').should('have.property', 'value', 'Kim');
  });
 
  it('domain 속성 없이 설정한 cookie는 서브도메인에서 조회되지 않아야 한다', () => {
    cy.visit('http://localhost.com:3000');
    cy.setCookie('session', 'abc123'); // domain 미지정
 
    cy.visit('http://m.localhost.com:3000');
    cy.getCookie('session').should('be.null');
  });
});

Cypress에서 서브도메인 간 이동이 필요한 테스트를 작성할 때는 cypress.config.js에 chromeWebSecurity: false 옵션을 추가해야 cross-origin 제한 없이 테스트할 수 있습니다.

// cypress.config.js
const { defineConfig } = require('cypress');
 
module.exports = defineConfig({
  e2e: {
    chromeWebSecurity: false, // cross-origin 이동 허용
    baseUrl: 'http://localhost.com:3000',
  },
});

이렇게 자동화해두면 hosts 파일이나 cookie 로직을 수정할 때마다 npx cypress run 한 번으로 전체 시나리오를 빠르게 검증할 수 있어, 매번 브라우저를 열어 수동 확인하는 수고를 덜 수 있습니다. 한 단계 더 나아가면 git push 전에 실행되는 pre-push hook이나 CI 파이프라인에 이 테스트를 포함시켜, cookie 관련 변경이 배포되기 전에 자동으로 검증되도록 구성할 수도 있습니다.