Refactor/#18/jwt to session by LEE-HYUN-JE · Pull Request #19 · Aolda/cloud-console-backend

LEE-HYUN-JE · 2026-03-10T04:10:11Z

📌 변경 요약 (Summary)

이 PR에서 무엇을 변경했는지 간단히 설명해주세요.

JWT(Access Token + Refresh Token) 기반 인증을 Keycloak OIDC Authorization Code Flow + Redis 세션 방식으로 전환합니다.
프론트엔드는 토큰을 직접 관리하지 않고, 백엔드가 발급한 acc-session-id 세션 쿠키만으로 모든 API를 호출할 수 있게 됩니다.
또한 기존에 서비스 레이어 전체에 분산되어 있던 String token 파라미터를 SessionModule 로부터 전달 받게 됩니다.

🔗 관련 이슈 (Related Issue)

이 PR과 관련된 이슈를 작성해주세요.

Closes #18

🛠 작업 내용 / 작업 순서 (Implementation Details)

이번 작업에서 수행한 내용이나 작업 순서를 작성해주세요.

예시:

DB 재설계 — UserEntity에 keycloak_user_id 컬럼 추가 및 Keystone 비밀번호 AES-256 암호화 적용
Keycloak OIDC Authorization Code Flow 구현 (KeycloakAuthController, KeycloakAuthServicePort)
Redis 세션 저장소 구현 — 세션 ID를 키로 Keycloak 토큰·Keystone 토큰 캐싱 (SessionAuthenticationFilter, SessionModule)
Keycloak 토큰 갱신 및 만료 처리 — 매 요청마다 SessionAuthenticationFilter에서 토큰 유효성 검사 후 자동 갱신
JwtAuthenticationFilter·JwtInfo 제거 및 SecurityConfig 정리
전체 도메인(10개) Port/Adapter/Controller 세션 기반으로 전환
SuperAdmin 초기화 시 Keycloak 계정 자동 매핑, 관리자 학적검증 우회 처리 추가

✨ 주요 변경 사항 (Key Changes)

인증 방식 전환

제거: JwtAuthenticationFilter, JwtInfo, /auth/login/refresh 엔드포인트
추가: Keycloak OIDC 로그인 (GET /api/v1/auth/keycloak/login), 로그아웃 (DELETE /api/v1/auth/keycloak/logout)
세션 쿠키 acc-session-id (HttpOnly / Secure / SameSite=None) 발급

Redis 세션 저장소

세션 ID → { keystoneUnscopedToken, keystoneScopedTokens, keycloakAccessToken, keycloakRefreshToken } 구조로 Redis 저장
TTL 30분, 슬라이딩 방식 (매 요청마다 갱신)
Keycloak refresh token 만료 시 세션 강제 폐기 → 401 반환

전 도메인 서비스 시그니처 변경

기존: someMethod(String token, ...) → 변경: someMethod(String sessionId, ...)
SessionModule.getKeystoneUserId(sessionId) / getKeystoneScopedToken(sessionId, projectId) 등으로 토큰 조회 일원화
영향 범위: Instance / Network / Image / Keypair / QuickStart / Project / User / Role / Notice / Auth / Volume

보안 강화

DB에 평문 저장되던 Keystone 비밀번호 → AES-256 암호화 저장 (KEYSTONE_PASSWORD_ENCRYPTION_KEY)
UserEntity에 keycloak_user_id 추가 — Keycloak ↔ Keystone 계정 연결

환경변수 변경

구분	항목
신규 추가	`KEYCLOAK_ISSUER_URI`, `KEYCLOAK_CLIENT_ID`, `KEYCLOAK_CLIENT_SECRET`, `KEYCLOAK_REDIRECT_URI`, `KEYCLOAK_FRONTEND_REDIRECT_URL`, `OAUTH_COOKIE_DOMAIN`, `KEYSTONE_PASSWORD_ENCRYPTION_KEY`

|
| 제거 가능 | JWT_SECRET, JWT_EXPIRATION_MS, JWT_REFRESH_EXPIRATION_MS, JWT_OAUTH_VERIFICATION_EXPIRATION_MS |

🧪 테스트 결과 (Test Results)

테스트 방법 및 결과를 작성해주세요.

테스트 환경

로컬 환경에서 개발환경의 Keycloak에 local client를 활용하여 진행했습니다.
추후 merge 시, 개발환경의 keycloak client에 매핑할 필요가 있습니다. (개발환경 도메인 추가 등등)

테스트 방법

테스트 해야했던 케이스가 너무 많아 노션에 정리했습니다.
https://www.notion.so/aolda/Jwt-Session-ae8a7bacf95583a994c70103b92047e7?source=copy_link

테스트 결과

필요한 경우 로그 또는 스크린샷 첨부

스크린샷도 노션에 함께 첨부되어 있습니다.

- AuthType에 KEYCLOAK(3) 추가 - UserDbExtraEntity에 keycloak_user_id, keystone_username, keystone_password 컬럼 추가 - UserDetailJpaRepository.findByKeycloakUserId() 추가 - UserIdentityJpaRepository.findByUserEmail() 추가 - UserRepositoryPort/Adapter: findUserDetailByKeycloakUserId, findUserIdentityByEmail 추가 - KeystonePasswordEncryptor: AES-256-CBC 기반 Keystone 패스워드 암호화 모듈 추가

- KeycloakOidcExternalPort/Adapter/Module: code→token 교환, token revoke 구현 - KeycloakIdTokenParser: ID Token 클레임 추출 (email, department, studentId 등) - KeycloakUserModule: 3-way 분기 처리 Branch 1) keycloakUserId 연결된 기존 사용자 → 일반 로그인 Branch 2) 이메일 일치 기존 사용자 → Account Linking (Keystone 패스워드 재설정) Branch 3) 신규 사용자 → Keystone 생성 + user_detail/user_auth_detail INSERT - KeycloakAuthModule.processCallback(): 전체 플로우 오케스트레이션 - KeycloakAuthController: /login, /callback, /logout 엔드포인트 추가

- SessionConstants: 세션 키/필드명 상수 정의 (global/security/session으로 배치) - SessionPrincipal: SecurityContext principal 클래스 (sessionId, keycloakUserId, keystoneUserId) - SessionAuthenticationFilter: acc-session-id 쿠키 → SecurityContext 인증 처리 - Redis 세션 조회 후 SessionPrincipal 설정 - 슬라이딩 세션 (요청마다 TTL 30분 연장) - SecurityConfig: SessionAuthenticationFilter를 JwtAuthenticationFilter 뒤에 등록 - RedisSessionRepositoryAdapter: SessionConstants import global로 변경

@deprecated

- SessionModule: 세션 기반 토큰 접근 모듈 - getKeystoneUnscopedToken(): 만료 시 DB credentials로 자동 재발급 - getKeycloakAccessToken(): 만료 시 refresh_token으로 자동 갱신 - getKeystoneScopedToken(): 프로젝트 스코프 토큰 발급 - AuthModule: getUnscopedTokenByUserId, issueProjectScopeToken, getProjectPermission @deprecated 처리 - docker-compose.yml: Redis 서비스 추가

- JwtAuthenticationFilter 삭제 → SessionAuthenticationFilter로 대체 - JwtInfo 삭제 → SessionPrincipal로 대체 - SessionConstants 삭제 - SecurityConfig에서 JwtAuthenticationFilter 제거

- userId → sessionId 변경 - authModule → sessionModule 전환 - JwtInfo → SessionPrincipal 교체

- userId → sessionId 변경 - sessionModule 기반 Keystone 처리

- userId → sessionId 변경 - SessionModule + AuthModule 병행 구조

- requesterId → sessionId 변경 - SessionModule 기반 사용자 식별 전환 - JwtInfo → SessionPrincipal 교체

- userId → sessionId 변경 - authModule → sessionModule 전환 - JwtInfo → SessionPrincipal 교체

- Keycloak accessToken 만료 시 refreshToken으로 자동 갱신 (HTTP 1회, ~수명마다) - refreshToken까지 만료 시 Redis 세션 삭제 → 401 (재로그인 유도) - Keycloak 서버 설정 기반 세션 수명이 실제로 적용되도록 수정 - 대부분 요청: 로컬 timestamp 체크만 수행 (HTTP 없음)

- SuperAdminProperties에 keycloakUserId/keystoneUsername/keystonePassword 필드 추가 - SuperAdminInitializer: 기동 시 user_detail + user_auth_detail 함께 생성 - keycloakUserId 미설정 계정 재기동 시 자동 업데이트

- KeycloakUserModule: isLinkedAdmin() 추가, Branch 3 departDto null 방어 - KeycloakAuthModule: isLinkedAdmin() 확인 후 관리자 학적검증 skip

- KeycloakIdTokenClaims: studentId 제거, ajouStudentId(ajou_student_id) 단일화 - KeycloakIdTokenParser: ajou_student_id 클레임 추출 추가, email optional 처리 - AjouUnivModule: univ_depart_info 미매핑 시 ajouMajor를 department fallback으로 사용

src/main/java/com/acc/local/service/ports/AdminProjectServicePort.java

+	void deleteProject(String projectId, String sessionId);

-	List<ProjectRole> getAssignableRoleTypes(String requesterId);
+	List<ProjectRole> getAssignableRoleTypes(String sessionId);
