[Feat] 로그아웃 API 구현 및 프론트 연동

.env.example

@@ -31,3 +31,10 @@ MINIO_BUCKET=docgrid
 # Ollama RAG LLM 서버 - application.yml에 이미 기본값(http://localhost:11434)이 있어 docker-compose 기본 포트를 쓰면 설정 불필요.
 # 기본값과 다른 포트/호스트를 쓸 때만 주석 해제
 # OLLAMA_SERVER_URL=http://localhost:11434
+
+# Redis (로그아웃 토큰 블랙리스트) - application.yml에 이미 기본값(localhost:6379, 인증 없음)이 있어
+# docker-compose 기본 포트를 쓰면 설정 불필요. 기본값과 다를 때만 주석 해제
+# REDIS_HOST=localhost
+# REDIS_PORT=6379
+# REDIS_PASSWORD=
+# REDIS_TIMEOUT=1s

backend/build.gradle

@@ -29,6 +29,7 @@ dependencies {
 	implementation 'org.springframework.boot:spring-boot-starter-validation'
 	implementation 'org.springframework.boot:spring-boot-starter-web'
 	implementation 'org.springframework.boot:spring-boot-starter-websocket'
+	implementation 'org.springframework.boot:spring-boot-starter-data-redis'
 	implementation 'org.springframework.ai:spring-ai-starter-mcp-server-webmvc'
 	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.9'
 	implementation 'io.minio:minio:8.5.17'

backend/src/main/java/com/opensource/docgrid/domain/auth/controller/AuthController.java

@@ -13,6 +13,7 @@
 import com.opensource.docgrid.domain.auth.dto.response.LoginResponse;
 import com.opensource.docgrid.domain.auth.dto.response.MeResponse;
 import com.opensource.docgrid.domain.auth.dto.response.SignupResponse;
+import com.opensource.docgrid.domain.auth.jwt.JwtProvider;
 import com.opensource.docgrid.domain.auth.service.command.AuthCommandService;
 import com.opensource.docgrid.domain.auth.service.query.AuthQueryService;
 import com.opensource.docgrid.global.common.response.ApiResponse;
@@ -21,6 +22,7 @@
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.servlet.http.HttpServletRequest;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 
@@ -50,4 +52,11 @@ public ResponseEntity<ApiResponse<LoginResponse>> login(@RequestBody @Valid Logi
     public ResponseEntity<ApiResponse<MeResponse>> getMe(@Parameter(hidden = true) @CurrentUser Long userId) {
         return ResponseUtils.ok(authQueryService.getMe(userId));
     }
+
+    @Operation(summary = "로그아웃", description = "현재 사용 중인 액세스 토큰을 무효화합니다. 무효화된 토큰은 만료 전이라도 이후 요청에 사용할 수 없습니다. Authorization: Bearer {token} 헤더가 필요합니다.")
+    @PostMapping("/logout")
+    public ResponseEntity<ApiResponse<Void>> logout(HttpServletRequest request) {
+        authCommandService.logout(JwtProvider.resolveToken(request));
+        return ResponseUtils.noContent();
+    }
 }

backend/src/main/java/com/opensource/docgrid/domain/auth/jwt/JwtAuthenticationFilter.java

@@ -15,22 +15,25 @@
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 
+@Slf4j
 @RequiredArgsConstructor
 public class JwtAuthenticationFilter extends OncePerRequestFilter {
 
     private final JwtProvider jwtProvider;
+    private final TokenBlacklistService tokenBlacklistService;
 
     @Override
     @SuppressWarnings("unchecked")
     protected void doFilterInternal(HttpServletRequest request,
                                     HttpServletResponse response,
                                     FilterChain filterChain) throws ServletException, IOException {
-        String token = resolveToken(request);
+        String token = JwtProvider.resolveToken(request);
 
         if (StringUtils.hasText(token)) {
             Claims claims = jwtProvider.getClaimsIfValid(token);
-            if (claims != null) {
+            if (claims != null && !isBlacklisted(claims.get("jti", String.class))) {
                 Long userId = claims.get("userId", Long.class);
                 String email = claims.getSubject();
                 List<String> roles = (List<String>) claims.get("roles");
@@ -50,11 +53,12 @@ protected void doFilterInternal(HttpServletRequest request,
         filterChain.doFilter(request, response);
     }
 
-    private String resolveToken(HttpServletRequest request) {
-        String bearer = request.getHeader("Authorization");
-        if (StringUtils.hasText(bearer) && bearer.startsWith("Bearer ")) {
-            return bearer.substring(7);
+    private boolean isBlacklisted(String jti) {
+        try {
+            return tokenBlacklistService.isBlacklisted(jti);
+        } catch (Exception e) {
+            log.error("Redis 블랙리스트 조회 실패, 인증을 계속 진행합니다: {}", e.getMessage());
+            return false;
         }
-        return null;
     }
 }

backend/src/main/java/com/opensource/docgrid/domain/auth/jwt/JwtProvider.java

@@ -3,16 +3,19 @@
 import java.nio.charset.StandardCharsets;
 import java.util.Date;
 import java.util.List;
+import java.util.UUID;
 
 import javax.crypto.SecretKey;
 
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.stereotype.Component;
+import org.springframework.util.StringUtils;
 
 import io.jsonwebtoken.Claims;
 import io.jsonwebtoken.JwtException;
 import io.jsonwebtoken.Jwts;
 import io.jsonwebtoken.security.Keys;
+import jakarta.servlet.http.HttpServletRequest;
 import lombok.extern.slf4j.Slf4j;
 
 @Slf4j
@@ -37,12 +40,21 @@ public String generateToken(Long userId, String email, List<String> roles) {
                 .subject(email)
                 .claim("userId", userId)
                 .claim("roles", roles)
+                .claim("jti", UUID.randomUUID().toString())
                 .issuedAt(now)
                 .expiration(expiry)
                 .signWith(secretKey)
                 .compact();
     }
 
+    public static String resolveToken(HttpServletRequest request) {
+        String bearer = request.getHeader("Authorization");
+        if (StringUtils.hasText(bearer) && bearer.startsWith("Bearer ")) {
+            return bearer.substring(7);
+        }
+        return null;
+    }
+
     public Claims getClaimsIfValid(String token) {
         try {
             return Jwts.parser()

backend/src/main/java/com/opensource/docgrid/domain/auth/jwt/TokenBlacklistService.java

@@ -0,0 +1,25 @@
+package com.opensource.docgrid.domain.auth.jwt;
+
+import java.time.Duration;
+
+import org.springframework.data.redis.core.StringRedisTemplate;
+import org.springframework.stereotype.Component;
+
+import lombok.RequiredArgsConstructor;
+
+@Component
+@RequiredArgsConstructor
+public class TokenBlacklistService {
+
+    private static final String KEY_PREFIX = "auth:blacklist:";
+
+    private final StringRedisTemplate redisTemplate;
+
+    public void blacklist(String jti, long ttlSeconds) {
+        redisTemplate.opsForValue().set(KEY_PREFIX + jti, "1", Duration.ofSeconds(ttlSeconds));
+    }
+
+    public boolean isBlacklisted(String jti) {
+        return Boolean.TRUE.equals(redisTemplate.hasKey(KEY_PREFIX + jti));
+    }
+}

backend/src/main/java/com/opensource/docgrid/domain/auth/service/command/AuthCommandService.java

@@ -1,5 +1,7 @@
 package com.opensource.docgrid.domain.auth.service.command;
 
+import java.time.Duration;
+import java.time.Instant;
 import java.time.LocalDateTime;
 import java.util.List;
 
@@ -12,6 +14,7 @@
 import com.opensource.docgrid.domain.auth.dto.response.LoginResponse;
 import com.opensource.docgrid.domain.auth.dto.response.SignupResponse;
 import com.opensource.docgrid.domain.auth.jwt.JwtProvider;
+import com.opensource.docgrid.domain.auth.jwt.TokenBlacklistService;
 import com.opensource.docgrid.domain.user.entity.Department;
 import com.opensource.docgrid.domain.user.entity.Role;
 import com.opensource.docgrid.domain.user.entity.User;
@@ -25,6 +28,7 @@
 import com.opensource.docgrid.global.exception.DocGridException;
 import com.opensource.docgrid.global.exception.ErrorCode;
 
+import io.jsonwebtoken.Claims;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
@@ -40,6 +44,7 @@ public class AuthCommandService {
     private final UserRoleRepository userRoleRepository;
     private final PasswordEncoder passwordEncoder;
     private final JwtProvider jwtProvider;
+    private final TokenBlacklistService tokenBlacklistService;
 
     public SignupResponse signup(SignupRequest request) {
         if (userRepository.existsByEmail(request.email())) {
@@ -97,4 +102,22 @@ public LoginResponse login(LoginRequest request) {
 
         return LoginResponse.of(token, jwtProvider.getExpirationSeconds(), user.getId(), user.getEmail(), roles);
     }
+
+    public void logout(String token) {
+        Claims claims = jwtProvider.getClaimsIfValid(token);
+        if (claims == null) {
+            return;
+        }
+
+        String jti = claims.get("jti", String.class);
+        if (jti == null) {
+            return;
+        }
+
+        long remainingMillis = Duration.between(Instant.now(), claims.getExpiration().toInstant()).toMillis();
+        if (remainingMillis > 0) {
+            long remainingSeconds = (remainingMillis + 999) / 1000;
+            tokenBlacklistService.blacklist(jti, remainingSeconds);
+        }
+    }
 }

backend/src/main/java/com/opensource/docgrid/global/config/SecurityConfig.java

@@ -14,6 +14,7 @@
 
 import com.opensource.docgrid.domain.auth.jwt.JwtAuthenticationFilter;
 import com.opensource.docgrid.domain.auth.jwt.JwtProvider;
+import com.opensource.docgrid.domain.auth.jwt.TokenBlacklistService;
 import com.opensource.docgrid.domain.mcp.security.McpApiKeyAuthFilter;
 import com.opensource.docgrid.domain.mcp.service.command.McpAccessTokenCommandService;
 
@@ -26,6 +27,7 @@ public class SecurityConfig {
 
     private final CorsConfigurationSource corsConfigurationSource;
     private final JwtProvider jwtProvider;
+    private final TokenBlacklistService tokenBlacklistService;
     private final McpAccessTokenCommandService mcpAccessTokenCommandService;
 
     @Bean
@@ -55,7 +57,7 @@ public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
              *   - JwtAuthenticationFilter  → 웹 로그인(JWT), /mcp/tokens 등 일반 API 담당
              *   - McpApiKeyAuthFilter      → Claude Desktop API 키, /mcp 경로만 담당
              */
-            .addFilterBefore(new JwtAuthenticationFilter(jwtProvider), UsernamePasswordAuthenticationFilter.class)
+            .addFilterBefore(new JwtAuthenticationFilter(jwtProvider, tokenBlacklistService), UsernamePasswordAuthenticationFilter.class)
             .addFilterBefore(new McpApiKeyAuthFilter(mcpAccessTokenCommandService), UsernamePasswordAuthenticationFilter.class);
         return http.build();
     }

backend/src/main/resources/application.yml

@@ -13,6 +13,13 @@ spring:
     # 전역 OSIV를 끄고, WebMvcConfig에서 /mcp를 제외한 나머지 경로에만 다시 등록한다.
     # /mcp는 MCP Streamable HTTP 응답 처리 방식과 OSIV가 충돌해 DB 커넥션이 누수됐다(#120).
     open-in-view: false
+  data:
+    redis:
+      host: ${REDIS_HOST:localhost}
+      port: ${REDIS_PORT:6379}
+      password: ${REDIS_PASSWORD:}
+      # 인증 요청마다 동기 조회하므로, Redis가 응답하지 않을 때 fail-open이 빠르게 동작하도록 짧게 제한한다.
+      timeout: ${REDIS_TIMEOUT:1s}
   ai:
     mcp:
       server:

backend/src/test/java/com/opensource/docgrid/domain/auth/integration/AuthLogoutIntegrationTest.java

@@ -0,0 +1,64 @@
+package com.opensource.docgrid.domain.auth.integration;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.util.UUID;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Tag;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
+
+import com.opensource.docgrid.domain.auth.dto.request.LoginRequest;
+import com.opensource.docgrid.domain.auth.dto.request.SignupRequest;
+import com.opensource.docgrid.domain.auth.dto.response.LoginResponse;
+import com.opensource.docgrid.domain.auth.jwt.JwtProvider;
+import com.opensource.docgrid.domain.auth.jwt.TokenBlacklistService;
+import com.opensource.docgrid.domain.auth.service.command.AuthCommandService;
+import com.opensource.docgrid.domain.user.repository.DepartmentRepository;
+
+import io.jsonwebtoken.Claims;
+
+/**
+ * 실제 PostgreSQL·Redis에서 로그인한 토큰이 로그아웃 이후 블랙리스트에 등록되어
+ * 더 이상 인증에 쓰일 수 없는 상태가 되는지 검증한다.
+ */
+@Tag("integration")
+@ActiveProfiles("test")
+@SpringBootTest
+@DisplayName("로그아웃 PostgreSQL·Redis 통합 테스트")
+class AuthLogoutIntegrationTest {
+
+    @Autowired
+    private AuthCommandService authCommandService;
+
+    @Autowired
+    private TokenBlacklistService tokenBlacklistService;
+
+    @Autowired
+    private JwtProvider jwtProvider;
+
+    @Autowired
+    private DepartmentRepository departmentRepository;
+
+    @Test
+    @DisplayName("로그인 후 로그아웃하면 발급된 토큰의 jti가 블랙리스트에 등록된다")
+    void logout_blacklistsIssuedToken() {
+        Long departmentId = departmentRepository.findAll().get(0).getId();
+        String email = "logout-integration-" + UUID.randomUUID() + "@test.com";
+        authCommandService.signup(new SignupRequest(email, "password1234", "로그아웃통합테스트", departmentId));
+
+        LoginResponse loginResponse = authCommandService.login(new LoginRequest(email, "password1234"));
+        String token = loginResponse.accessToken();
+        Claims claims = jwtProvider.getClaimsIfValid(token);
+        String jti = claims.get("jti", String.class);
+
+        assertThat(tokenBlacklistService.isBlacklisted(jti)).isFalse();
+
+        authCommandService.logout(token);
+
+        assertThat(tokenBlacklistService.isBlacklisted(jti)).isTrue();
+    }
+}