HttpOnly 쿠키 🍪: 개념, 적용 방법, 그리고 보안적 특징 🔒

🚀 JWT 인증 및 보안 강화 방법 (HttpOnly 쿠키 사용)

1. JWT 인증의 기본 흐름 🏃‍♂️

사용자가 로그인하면 서버는 JWT(JSON Web Token)를 발급하고, 이를 클라이언트가 저장하여 인증을 유지한다. JWT는 일반적으로 localStorage나 sessionStorage에 저장하지만, 보안이 중요한 상황에서는 HttpOnly 쿠키에 저장하는 것이 훨씬 안전하다. 🎯

---

2. 보안 고려사항 🛡️

localStorage에 JWT를 저장하면 XSS(크로스 사이트 스크립팅) 공격에 취약할 수 있다. 이를 방지하려면, HttpOnly 쿠키를 사용하는 것이 좋다. 😬
하지만... HttpOnly 쿠키를 사용하면 XSS를 완전히 방지하는 것이 아니라, JavaScript로 쿠키 접근만 막는다는 점을 명확히 해야한다.

XSS 자체를 차단하려면 ⁉️ : 콘텐츠 보안 정책(CSP) 설정, 입력값 검증 강화가 필요

+ 💡CSRF 방어를 위한 추가 설정
HttpOnly 쿠키를 사용하면 CSRF 방어는 충분하지 않다.
이를 보완하기 위해 CSRF 토큰과 같은 추가 보호를 설명하는 것이 좋다.

예시:

• CSRF 방지 토큰 생성 → 쿠키와 함께 전송
• 요청 시 CSRF 토큰을 헤더나 파라미터로 함께 보내기
• 서버에서 검증

---

3. HttpOnly 쿠키란? 🍪

HttpOnly 쿠키는 JavaScript에서 접근할 수 없는 쿠키이다. 즉, 클라이언트 측 스크립트에서는 이 쿠키에 접근할 수 없으므로 XSS 공격을 예방할 수 있다. 이 방식은 보안을 강화하고, 자동으로 쿠키를 서버에 전송하기 때문에 인증 처리가 간편해진다는 장점이 존재한다. 😎

4. 구현 과정 🔧

4-1. 서버에서 JWT를 HttpOnly 쿠키에 저장 💼

로그인 요청을 처리한 후, 서버는 JWT를 생성하여 HttpOnly 쿠키로 클라이언트에 전송하며 아래와 같은 설정을 한다 :

// 쿠키 생성
Cookie jwtCookie = new Cookie("token", token);
jwtCookie.setHttpOnly(true);  // JavaScript에서 접근 불가
jwtCookie.setSecure(false);   // 개발 환경에서는 false, 배포 환경에서는 true
jwtCookie.setPath("/");       // 애플리케이션 전체에 유효
jwtCookie.setMaxAge(7 * 24 * 60 * 60);  // 7일 동안 유효
response.addCookie(jwtCookie);

+ 💡 HttpOnly 외에 SameSite 속성 추가
SameSite 속성은 쿠키의 CSRF(Cross-Site Request Forgery) 공격을 방지하기 위해 추가되어야 한다. 알아야할게 ...끝도없다 ㄹㅇ...

SameSite=Strict → 쿠키가 같은 사이트에서만 전송됨
SameSite=Lax → 대부분의 요청에서 전송되지만, 크로스 사이트 요청에서 제한
SameSite=None → 모든 요청에서 허용되지만, 반드시 Secure 속성과 함께 사용해야 함

4-2. 클라이언트에서 HttpOnly 쿠키 사용 🖥️

HttpOnly 쿠키는 클라이언트 측에서 직접 접근할 수 없다. 하지만, 클라이언트가 서버에 요청을 보낼 때, 자동으로 쿠키가 포함되어 전송된다. 이로 인해, 서버는 별도의 저장소 없이 인증을 자동으로 확인할 수 있다. 🔄

---

5. 로그인 후 상태 관리 (Pinia 사용) 📦

나는 클라이언트 측에서는 로그인 상태를 관리하기 위해 Pinia와 같은 상태 관리 라이브러리를 사용했다. 로그인 후 HttpOnly 쿠키를 기반으로 사용자 정보를 저장하고, 페이지가 새로고침 되어도 로그인 상태를 유지할 수 있었다. 👍

const loginState = useLoginState(); // Pinia 상태 관리 사용

// 로그인 성공 시, 사용자 이름과 권한을 상태에 저장
loginState.isLoggedIn = true;
loginState.adminName = decodedToken.name;

아래는 위에룰 참고하여 구현한 로그인 페이지의 script 부분이다.

<script setup>
import axios from 'axios';
import { jwtDecode } from 'jwt-decode';
import { ref } from 'vue';
import { useLoginState } from '@/stores/loginState';

// 폼 데이터
const formData = ref({
  adminCode: '',
  adminPassword: ''
});

// 에러 메시지 관리
const errorMessage = ref('');
const loginState = useLoginState(); // 로그인 상태 관리 Store

// 로그인 함수
const loginUser = async () => {
  // 필수 입력 확인
  if (!formData.value.adminCode || !formData.value.adminPassword) {
    alert("사번과 비밀번호를 입력해주세요.");
    return;
  }

  try {
    const response = await axios.post('http://localhost:5000/users/login', {
      admin_code: formData.value.adminCode,
      admin_password: formData.value.adminPassword
    }, {
      headers: {
        'Content-Type': 'application/json',
      }
    });

    console.log('HTTP 응답 상태 코드:', response.status);
    console.log('전체 응답 데이터:', response);

    // 응답 헤더에서 토큰 가져오기
    const token = response.headers.authorization;
    if (token) {

      // JWT 디코딩
      const decodedToken = jwtDecode(token);
      console.log('Decoded JWT Token:', decodedToken);

      // 로그인 상태 업데이트
      loginState.isLoggedIn = true;
      loginState.adminName = decodedToken.name; // JWT에서 이름 추출하여 상태 설정

      // 성공 메시지
      alert(`${decodedToken.name}님, 환영합니다.`);

      // 메인 페이지로 이동
      window.location.href = '/';
    } else {
      errorMessage.value = '인증 토큰이 없습니다. 로그인 실패';
      alert("아이디와 비밀번호를 확인해주세요.");
    }
  } catch (error) {
    console.error('로그인 중 오류 발생:', error);
    errorMessage.value = '로그인 중 오류가 발생했습니다. 다시 시도해주세요.';
    alert(errorMessage.value);
  }
};
</script>

---

6. 로그인 후 보안 강화 ⚔️

1. XSS 공격 방지: JWT를 HttpOnly 쿠키에 저장하여, 클라이언트 측 스크립트에서 접근할 수 없도록 한다.
2. 자동 인증 처리: 서버는 클라이언트로부터 오는 요청에서 자동으로 쿠키를 확인하여 인증을 처리한다.
3. CORS 설정: 클라이언트와 서버가 서로 다른 도메인일 경우, 서버에서 CORS 설정을 추가해야 한다.

@Configuration
public class CorsConfig {
    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration configuration = new CorsConfiguration();
        configuration.addAllowedOrigin("http://localhost:5173");  // 클라이언트 URL
        configuration.addAllowedMethod("*");
        configuration.addAllowedHeader("*");
        configuration.setAllowCredentials(true);  // 쿠키 전송 허용
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", configuration);
        return source;
    }
}

---

7. 로그아웃 처리 🚪

로그아웃 시에는 서버에서 HttpOnly 쿠키를 삭제해야 하며, 클라이언트에서는 쿠키를 직접 삭제할 수 없기 때문에, 서버에서 쿠키를 제거하는 방식으로 처리한다.

Cookie jwtCookie = new Cookie("token", null);
jwtCookie.setHttpOnly(true);
jwtCookie.setSecure(true);
jwtCookie.setPath("/");
jwtCookie.setMaxAge(0);  // 쿠키 만료
response.addCookie(jwtCookie);

나는 여기서 refresh token을 발행하여 레디스에 담았기 때문에 레디스에서도 캐시 삭제를 해주었다. 혹여나 refresh token을 Redis에 저장하고 있다면, 로그아웃 시 해당 token을 Redis에서 삭제해야 다른 세션에서 해당 refresh token을 사용하여 새로운 access token을 발급받는 것을 방지할 수 있다.

Refresh Token은 클라이언트에 저장하지 않고 서버의 안전한 저장소(Redis)에 저장
Refresh Token이 사용되면 즉시 삭제(일회용)

refresh token을 한 번 사용하고 만료시키는 방식으로 처리하는 것이 좋으며 refresh token을 매번 새로 발급하고, 이전 token을 삭제하는 방식으로 구현하여 보안을 강화할 수 있다.

예를 들어, 로그아웃 시 Redis에서 refresh token을 삭제한 후, 
새로 발급된 token은 이전에 사용된 refresh token과 관계없이 다시 발급되도록 설정할 수 있다.

⚠️ refresh token 일회용 처리하는것을 잊지말자 !!!

Access Token이 만료됨 → 401 에러 반환
클라이언트는 Refresh Token을 서버로 전송 → 새 Access Token 발급
Refresh Token은 즉시 삭제하고 새로운 Refresh Token 발급

---

⚠️ JWT 인증 구현 시 주의사항

JWT 인증을 구현할 때 HttpOnly 쿠키를 사용하는 방법이 안전하고 편리하지만, 몇 가지 중요한 주의사항이 있다. 이를 고려하지 않으면 보안이나 기능에 문제가 발생할 수 있다. 아래의 주의사항을 반드시 체크! ✅

🔖 1. HTTPS 필수! 🔒

cookie.setSecure(true)는 HTTPS 환경에서만 작동한다.
즉, 배포 환경에서 secure 속성을 true로 설정하려면 반드시 HTTPS를 사용해야 한다.

개발 환경에서는 HTTP로도 동작할 수 있지만, 실제 서비스에서는 HTTPS를 반드시 사용해야 한다. HTTPS는 데이터 전송 중 암호화를 보장하며, 중간자 공격(MITM)을 방지한다.
따라서, 배포 환경에서 JWT 토큰을 HttpOnly 쿠키에 저장하려면, HTTPS 설정이 필수이다. 🌐

예시:

Cookie jwtCookie = new Cookie("token", token);
jwtCookie.setHttpOnly(true); // JavaScript에서 접근 불가
jwtCookie.setSecure(true);   // HTTPS 환경에서만 적용
jwtCookie.setPath("/");
response.addCookie(jwtCookie);

🔖 2. JWT 토큰 만료 처리 ⏳

JWT는 만료 시간(exp)을 포함할 수 있으며, 만료된 토큰을 그대로 사용할 경우 인증 실패가 발생한다. 따라서, 토큰이 만료된 경우 새로운 토큰을 발급받는 로직을 구현해야 한다.

만료된 토큰 처리 흐름:
클라이언트가 서버에 요청할 때, JWT 토큰이 만료되었는지 확인 ➡️
만약 만료되었다면 ➡️ 클라이언트는 새로운 토큰을 발급받기 위해 재로그인을 하거나 ➡️ 리프레시 토큰(refresh token)을 사용하여 새 토큰을 발급

💡 리프레시 토큰을 사용하면 사용자가 로그인 상태를 유지하면서 새로운 JWT 토큰을 발급받을 수 있으며 리프레시 토큰은 액세스 토큰을 갱신하는 역할만 하며, 그 자체로 인증을 대신하는 역할은 하지 않다라는것을 꼭 알아두자 ❗❗❗❗

🔖 3. CORS 설정 (Cross-Origin Resource Sharing) ⚙️

클라이언트와 서버가 서로 다른 도메인에서 동작할 경우, CORS 설정이 필요하다. 특히 쿠키 기반 인증을 사용할 때는 credentials: true를 서버에서 설정해야 한다.

💥 CORS 설정을 위한 주요 포인트 💥

Access-Control-Allow-Credentials: true: 
쿠키를 포함한 인증 정보를 서버와 클라이언트 간에 전달하려면, 이 헤더를 반드시 설정 !!!

Access-Control-Allow-Origin: 
클라이언트의 출처(origin)를 정확히 명시해야 하며, * (모든 출처) 대신 정확한 도메인을 설정

@Configuration
public class CorsConfig {
    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration configuration = new CorsConfiguration();
        configuration.addAllowedOrigin("http://localhost:5173"); // 클라이언트 URL
        configuration.addAllowedMethod("*");
        configuration.addAllowedHeader("*");
        configuration.setAllowCredentials(true); // 쿠키 전송 허용
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", configuration);
        return source;
    }
}

🔖 4. 프론트엔드 설정 주의사항 🚨

✨✨✨✨✨✨ withCredentials: true

Axios나 Fetch API를 사용하여 서버로 요청할 때, 쿠키를 포함하려면 withCredentials: true를 설정해야 한다. 꼭!!!!!!!!!!!!!!!!!!!!!!!!!!!! 클라이언트 측에서는 withCredentials: true를 설정해야 HttpOnly 쿠키가 요청 시 자동으로 전송된다.

예시 (Axios 사용 시) :

const response = await axios.post('http://localhost:5000/users/login', 
  { 
    admin_code: formData.value.adminCode, 
    admin_password: formData.value.adminPassword 
  }, 
  {
    headers: { 'Content-Type': 'application/json' },
    withCredentials: true // 쿠키 자동 전송
  }
);

이렇게 위의 이미지처럼 다른 페이지를 넘어가도 상태가 그대로유지되는 것을 볼 수 있다.

1. 사용자는 `/users/login` 엔드포인트로 인증 요청을 보내 로그인
2. 백엔드는 JWT 토큰을 발급하고, 이를 `HttpOnly` 쿠키에 저장
3. 페이지 전환 시, Pinia 상태 관리로 토큰을 유지하고, 
                `/admin/status` 요청을 통해 인증 상태를 확인
4. 인증 성공 시, 사용자 이름과 권한을 Pinia 상태에 저장
5. `HttpOnly` 쿠키에 저장된 토큰은 클라이언트에서 접근 불가하므로 
              개발자 도구에서 확인할 수 없음
6. 이를 통해 JWT를 안전하게 사용하여 로그인 상태를 유지

console.log(localStorage.getItem('token'));  

원래 이렇게 로컬스토리지에 담고 이 명령어를 콘솔에 찍는다면 토큰값이 나타났지만,
이제는 위와 같은 콘솔값을 입력해도 토큰값 확인 불가다.

📜 기록용

console.log(localStorage.getItem('token')); --> 토큰값 확인 명령어
localStorage.removeItem('token'); --> 토큰값 삭제 명령어

💡 마무리

HttpOnly 쿠키를 사용하는 방식은 보안성을 높이고, 상태 관리가 간편하며 이를 통해, XSS 공격을 예방하고 로그인 상태를 안전하게 유지할 수 있다. 또한, 서버 측에서 토큰을 관리하고, 클라이언트 측에서는 상태 관리 라이브러리(Pinia 등)를 활용하여 로그인 상태를 지속적으로 유지할 수 있다. 🛡️✨

나도 사실... 이걸 작성하면서 더 많이 수정과!!! 공부가 필요한것 같다 ㅠㅠ.. 그냥 정보차 적는것이니, 확실한 정보가 아니여도 이사람은 이렇구나 .. 라고 봐줬으면 한다 😭

흠.. 근데 httponly쿠키로 aws 배포를 하는 도중에 오류가 계속 났는데 내가 CI/CD분야를 공부를 제대로 안해봐서 .. 주어진 배포 기간이 있었기 때문에 어렴풋이 어떤 오류인지는 팀원들과 함께 알아냈지만 해결 방법을 찾지 못하고 just jwt토큰 암호화 방법으로 배포 하였다 .. 😭😭😭
이 부분에서 오류가 났어서 1일정도 시간이 딜레이 되었는데 괜히 보안 어쩌구하면서 활용해보자고 설득 했나 .. 싶다.. 미안한 마음이 크기도 하면서 끝까지 같이 해결방안을 찾아준 팀원들 덕분에 주눅이 (조금만)? 들었던것 같기도.. 😥
사실 내가 배포까지 생각을 하고 더 공부하고.. 구현했더라면... ㅜㅜ 수고가 덜 했을텐데.. 아직도 미안하면서 나중에 혼자 해결방법을 찾아보도록 하겠다. 앞으로는 공부 더 열심히 하고.. 개발하기 . 약속. 🤼‍♂️🤼‍♂️🤼‍♂️🤼‍♂️🤼‍♂️🤼‍♂️ 😭😭😭😭
( 다들 너무 고마워.. 어엉엉 )

이번 프로젝트에서는 SHA-512 해시 알고리즘을 사용하는 암호화 방식을 사용했는데 다음에는 암호화 방식을 좀더 공부해보고싶다.

참고 문헌 : https://gamhongshi.tistory.com/28