인증/인가 모듈 역할 및 특징

---

기술 스택

• Spring Boot: 백엔드 프레임워크
• Spring Security: 인증 및 보안
• JWT: Access / Refresh Token 기반 인증
• Redis: Refresh Token 저장 및 블랙리스트 처리
• OAuth2: 소셜 로그인 지원
• WebClient: 동기/비동기 HTTP 통신
• Spring Mail: 이메일 전송 기능
• Lombok: 반복 코드 제거
• JUnit / Spring Security Test: 테스트

---

인증 흐름

---

API 엔드포인트

메서드	경로	설명
POST	/auth/signup	회원가입 요청
POST	/auth/login	로그인 및 Access / Refresh Token 발급
POST	/auth/logout	로그아웃 및 Redis에 저장된 Refresh Token 삭제
POST	/auth/reissue	만료된 Access Token 재발급 요청
GET	/auth/validate	JWT 기반 사용자 정보 확인 (유효성 검증)
POST	/auth/validateUser	이메일/비밀번호 유효성만 검증
GET	/auth/verify-email	이메일 인증 링크 클릭 시 호출
GET	/auth/kakao	카카오 OAuth 로그인 콜백
GET	/auth/github	GitHub OAuth 로그인 콜백
POST	/auth/exchange-token	소셜 로그인 후 authCode를 통해 토큰 발급
POST	/gateway/**	정해진 각 모듈로 요청 전달

---

인가 정책 (Authorization Policy)

• 모든 보호된 API 요청은 Authorization: Bearer <Access Token> 형식의 헤더로 인증 처리됨
• 토큰에서 사용자 정보 (userId, email, role) 를 추출하여 SecurityContext에 등록
• 토큰 유효성 검증은 다음 조건을 따름:
  • 서명(Signature) 유효성
  • 만료 시간 체크
  • 블랙리스트 등록 여부 확인 (Redis에서 조회)
• 아래 URI는 화이트리스트로 지정되어 필터를 통과 (인증/인가 없이 접근 가능):
  • FilterConstant.whiteList 또는 FilterConstant.specialList에 등록된 경로
• 사용자 권한(ROLE_USER, ROLE_ADMIN 등)에 따라 접근 제어가 가능하며, SimpleGrantedAuthority로 주입됨
• Refresh Token 관련 요청(/auth/reissue)의 경우는 쿠키에서 토큰을 추출하여 따로 처리됨

---

설정 주요 정보

Spring Security 설정

• SecurityFilterChain을 통해 경로별 인증/인가 정책 설정
• JWT 기반 인증 방식 사용 (세션 사용 X, 완전한 Stateless 구조)
• JwtAuthenticationFilter를 통해 Access Token 검증
• 화이트리스트(/auth/login, /auth/signup 등)는 인증 없이 접근 허용
• 블랙리스트 경로는 인증 필요 (SecurityContext 기반 인가 처리)
• OAuth2 로그인 성공 시, 커스텀 SuccessHandler를 통해 프론트엔드로 리다이렉트

JWT & Redis 연동

• Access Token: 모든 API 요청 시 Authorization: Bearer <token> 형태로 전송
• Refresh Token: Redis에 저장하여 토큰 재발급 시 사용
• 로그아웃 시 Refresh Token을 Redis에서 제거 (블랙리스트 차단 처리 포함)

CORS 정책

• 허용 Origin:
  • http://localhost:5500
  • http://127.0.0.1:5500
  • https://visiblego.com
  • https://www.visiblego.com
• 허용 메서드: GET, POST, PUT, DELETE, PATCH, OPTIONS
• 모든 헤더 허용, 인증 정보 포함 (allowCredentials: true)

---

예외 코드 목록 (내부 statusCode 기준)

내부 코드	오류명	설명
10000	UNKNOWN_ERROR	알 수 없는 에러
10001	TOKEN_EXPIRED	Access Token 만료
10002	INVALID_SIGNATURE	JWT 서명 오류
10003	MALFORMED_TOKEN	잘못된 구조의 JWT
10004	MISSING_TOKEN	Authorization 헤더 또는 토큰 누락
10005	REFRESH_TOKEN_MISMATCH	Redis에 저장된 Refresh Token과 요청값 불일치
10006	EMAIL_TOKEN_MISMATCH	이메일 인증 토큰 불일치
10007	BLACK_LIST_FOUND	블랙리스트에 등록된 사용자
10008	BLOCK_OAUTH_USER	차단된 OAuth 계정 사용자

---

프로젝트 디렉토리 구조

auth/
└── src/
    └── main/
        └── java/com/comprehensive/eureka/auth/
            ├── client/        # 외부 서비스(타 모듈)과 통신하는 Web Client 모음
            ├── config/        # Spring Security 및 인증 관련 설정 클래스
            ├── constant/      # 상수 정의 (역할, 토큰 헤더 이름 등)
            ├── controller/    # 인증/인가 관련 API 엔드포인트
            ├── dto/           # 요청/응답 객체 정의
            │   ├── base/        # ├─ 공통 응답 구조 (BaseResponse 등)
            │   ├── common/      # ├─ 공용 DTO (세션 사용자 정보 등)
            │   ├── request/     # ├─ 클라이언트 요청 DTO
            │   └── response/    # └─ 서버 응답 DTO
            ├── exception/     # 커스텀 예외 및 예외 코드 관리
            │   ├── code/        # ├─ 에러 코드 Enum
            │   └── custom/      # └─ 사용자 정의 예외 클래스
            ├── filter/        # JWT 인증 필터 등 보안 관련 필터
            ├── service/       # 인증 로직 처리 서비스
            │   └── impl/        # └─ 서비스 구현체
            └── util/          # JwtUtil 등 공용 유틸리티 클래스