PHP example for SameSite=None; Secure 교차 사이트 SameSite 속성 설정

크롬(Chrome)을 비롯한 최신 웹 브라우저의 보안 정책이 강화되면서, 교차 사이트(Cross-Site) 간의 쿠키 전송을 제어하는 SameSite 속성 설정이 필수적인 요소가 되었습니다.

특히 결제 게이트웨이(PG), 외부 API 연동, 소셜 로그인 등 타 사이트에서 우리 사이트로 쿠키를 공유해야 하는 경우 SameSite=None; Secure 설정이 제대로 되어 있지 않으면 쿠키가 누락되어 세션이 끊기는 문제가 발생합니다.

이번 포스팅에서는 PHP 버전별로 일반 쿠키 및 세션 쿠키에 SameSite 속성을 올바르게 적용하는 방법을 예제 코드와 함께 알아보겠습니다.

    ⚠️ 핵심 요약 (SameSite 기본 규칙):

    - SameSite=Lax: 같은 도메인 내 혹은 안전한 퍼스트 파티 컨텍스트에서만 쿠키를 전송합니다. (기본값 추천)

    - SameSite=None: 교차 사이트 간 쿠키 전송을 허용합니다. 단, 반드시 'Secure(HTTPS)' 속성이 함께 지정되어야 브라우저에서 차단되지 않습니다.

1. 일반 쿠키(setcookie) 설정 방법

PHP 버전이 7.3.0 이상인 경우, setcookie() 함수 내부에 배열 구조의 옵션을 통해 SameSite를 아주 간결하게 지정할 수 있습니다.

// PHP 7.3.0 이상: 배열 형태의 옵션 지원
setcookie('same-site-cookie', 'foo', ['samesite' => 'Lax']);
setcookie('cross-site-cookie', 'bar', ['samesite' => 'None', 'secure' => true]);

하위 버전(PHP 7.3.0 미만)에서의 우회 방법

만약 서버가 옛날 PHP 버전을 사용 중이라면 함수 내부 인자로 지원되지 않기 때문에, 아래와 같이 header() 함수를 사용해 직접 HTTP 헤더를 내려주어야 합니다.

// PHP 7.3 미만: header() 함수로 Set-Cookie 직접 명시
header('Set-Cookie: same-site-cookie=foo; SameSite=Lax', false);
header('Set-Cookie: cross-site-cookie=bar; SameSite=None; Secure', false);

2. 세션 쿠키(Session Cookie) 설정 방법

로그인 상태 유지 등을 담당하는 세션 쿠키 역시 SameSite 대응이 필요합니다. session_set_cookie_params() 메서드를 활용하여 적용할 수 있으며, 이 또한 버전에 따라 분기 처리가 필요합니다.

아래 코드는 현재 서버의 PHP 버전을 체크(PHP_VERSION_ID)하여 하위 버전과 상위 버전 모두에서 에러 없이 SameSite=Lax를 안전하게 주입해 주는 실무형 스크립트입니다.

if (PHP_VERSION_ID >= 70300) { 
    // PHP 7.3.0 이상: 'samesite' 키를 옵션 배열에 포함
    session_set_cookie_params([
        'lifetime' => $cookie_timeout,
        'path' => '/',
        'domain' => $cookie_domain,
        'secure' => $session_secure,
        'httponly' => $cookie_httponly,
        'samesite' => 'Lax'
    ]);
} else { 
    // PHP 7.3 미만: path 인자에 우회 문자열 '; samesite=Lax' 추가
    session_set_cookie_params(
        $cookie_timeout, 
        '/; samesite=Lax', 
        $cookie_domain, 
        $session_secure, 
        $cookie_httponly
    ); 
}

// 파라미터 설정 후 세션 시작
session_start();

3. 마무리하며

SameSite 미지정으로 인한 쿠키 유실은 크롬 개발자 도구(F12)의 Console 탭이나 Network 탭에서 경고/에러 메시지로 손쉽게 확인할 수 있습니다. 사용 중인 PHP 개발 환경에 맞춰 위 예제 코드를 적용하고 외부 연동 오류를 사전에 예방해 보세요!

DEV.자료창고