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

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

src/main/java/com/acc/local/external/dto/keycloak/KeycloakRevokeRequest.java

LEE-HYUN-JE · 2026-03-18T02:16:59Z

src/main/java/com/acc/local/controller/InterfaceController.java

-        JwtInfo jwtInfo = (JwtInfo) authentication.getPrincipal();
-        String id = interfaceServicePort.createInterface(jwtInfo.getUserId(), projectId, request);
+        SessionPrincipal principal = (SessionPrincipal) authentication.getPrincipal();
+        String id = interfaceServicePort.createInterface(principal.getSessionId(), projectId, request);


해당 ID는 기존 도메인에서 개발된 지역변수이므로 변경하지 않음

jalju0804 · 2026-03-10T05:25:30Z

코파일럿 리뷰 반영 먼저 진행해주세용!!

callme-waffle

진행주신 리팩토링에 대한 플로우검토 및 로직검토를 완료했습니다.

코드 내 삼항연산자 사용과 단일메서드 내 다중책임 등이 확인되어 추후 리팩토링은 필요할 것 같으나, 전반적인 플로우 및 구현에서는 큰 문제는 없는 것 같습니다.

다만 몇가지 확인이 필요한 사항이 있어 확인 후 코멘트 추가 요청드립니다. 확인 후 코멘트 부탁드립니다!

callme-waffle · 2026-03-15T15:34:30Z

docs/keycloak-callback-flow.md

+`user_detail.keycloak_user_id = claims.subject()`인 레코드가 있으면 저장된 keystoneUsername과 AES-256 복호화된 keystonePassword를 그대로 반환합니다. 외부 API 호출 없이 DB 조회와 복호화만으로 처리됩니다.
+
+**Branch 2. 이메일 일치 기존 사용자 (Account Linking)**
+keycloak_user_id는 없지만 `user_auth_detail.user_email = claims.email()`인 레코드가 있을 때 진입합니다. 기존에 ADMIN 또는 GOOGLE 방식으로 가입한 사용자가 Keycloak으로 최초 로그인하는 경우입니다. 기존 Keystone 패스워드를 알 수 없으므로 시스템 어드민 토큰으로 패스워드를 재설정하고, `user_detail`에 keycloak_user_id, keystoneUsername, keystonePassword(암호화)를 업데이트합니다. 이 시점 이후 Keystone 직접 패스워드 로그인은 불가합니다.


해당 플로우는 기존 테스트하던 ACC프로젝트 내에서의 하위호환성을 위함으로 이해했는데, 혹시 맞을까요?

ADMIN계정 등록의 경우, 관리자의 개인계정과는 무관하게 별도 계정을 생성하여 사용하는 것으로 이해했어 해당 플로우의 필요성이 운영환경에서도 존재하는지 궁금하여 문의드립니다.

운영환경에서 필요성이 존재하지 않습니다.
개발환경에서 테스트 시 , 계정관련해서 필요성이 있다고 생각했는데, 개발환경의 계정이 필요없고, 다시 keycloak 기반으로 생성할 예정이라면 제거해도 되는 로직입니다.

즉 , Keycloak과 연동을 하게된다면 ACC자체에서 계정을 생성해도, keycloak 계정에 대한 유효성체크부분을 해결해야하기에 위 flow를 만들어둔 것입니다.
이제 ACC자체의 로그인 Flow를 사용하지 않고 keycloak의 sso를 통해서 로그인을 진행하기 때문입니다.

<ACC의 ADMIN 계정 생성 방법>

keycloak에서 ACC Admin 용 계정 생성 또는 Admin으로 등록할 기존 아올다 회원의 keycloak 계정 준비

해당 계정을 ACC에서 Admin으로 할당 -> (ACC DB에 직접 접근해서 Admin으로 변경하던, 아니면 Keycloak의 어떤 권한 정보를 매핑헤서 ACC DB내에 계정의 권한을 Admin으로 설정하는 로직을 추가하던 2번 과정은 필요합니다.)

그래서 만약, Keycloak에서 ACC Admin 용 계정 생성을 생성했을 시, 학적 정보를 검증하는 로직을 제거해야 정상적인 접근이 가능할 것 같아 위와같은 flow를 추가하게 된 것입니다.

src/main/java/com/acc/local/controller/KeycloakAuthController.java

callme-waffle · 2026-03-15T15:43:26Z

src/main/java/com/acc/local/domain/enums/auth/AuthType.java

    GITLAB(1, "GitLab 인증"),
-    ADMIN(2, "관리자 직접 생성");
+    ADMIN(2, "관리자 직접 생성"),
+    KEYCLOAK(3, "Keycloak OIDC 인증");


GOOGLE과 GITLAB 인증의 구현이 Keycloak 경유를 기반으로 구현되는거라 별도의 KEYCLOAK 기반 인증임을 구분할 필요는 없다고 생각했는데, 혹시 위 2개의 연동 flow는 다르게 구현되는건가요?

이것또한 개발환경 데이터를 고려해서 저렇게 구분을 했던 것입니다.
acc는 이제 keycloak에 대한 계정만을 바라보기에 AuthType이라는 속성자체를 저장할 필요가 없습니다.
keycloak의 토큰 유효성을 통해서 회원을 생성하지, 계정 생성 인증 방식에 대해서는 ACC가 이제 관여하지 않기 때문입니다.

src/main/java/com/acc/local/service/modules/auth/AjouUnivModule.java

callme-waffle · 2026-03-15T15:48:33Z

src/main/java/com/acc/local/service/modules/keycloak/KeycloakAuthModule.java

+    /**
+     * Keycloak OIDC 콜백 처리: code → 세션 생성 → sessionId 반환.
+     */
+    public String processCallback(String code) {


후순위라 이번 리뷰에서는 반영되지 않아도 될 것 같습니다만, 추후헤는 메서드 내 담당기능이 많아 목적 별 메서드 분할하여 정리하면 조금 더 가시성이 높아질 것 같습니다 :)

src/main/java/com/acc/local/controller/NetworkController.java

-        JwtInfo jwtInfo = (JwtInfo) authentication.getPrincipal();
-        String id = networkServicePort.createNetwork(request, jwtInfo.getUserId(), projectId);
+        SessionPrincipal principal = (SessionPrincipal) authentication.getPrincipal();
+        String id = networkServicePort.createNetwork(request, principal.getSessionId(), projectId);


LEE-HYUN-JE · 2026-03-18T02:26:51Z

src/main/java/com/acc/local/controller/SecurityRuleController.java

-        JwtInfo jwtInfo = (JwtInfo) authentication.getPrincipal();
-        String id = securityRuleServicePort.createSecurityRule(projectId, jwtInfo.getUserId(), request);
+        SessionPrincipal principal = (SessionPrincipal) authentication.getPrincipal();
+        String id = securityRuleServicePort.createSecurityRule(projectId, principal.getSessionId(), request);


이번 이슈 사항이 아님.
기존 도메인에서 개발된 내용이므로 적용하지 않는다.

LEE-HYUN-JE · 2026-03-18T02:27:06Z

src/main/java/com/acc/local/controller/RouterController.java

-        JwtInfo jwtInfo = (JwtInfo) authentication.getPrincipal();
-        String id = routerServicePort.createRouter(request, jwtInfo.getUserId(), projectId);
+        SessionPrincipal principal = (SessionPrincipal) authentication.getPrincipal();
+        String id = routerServicePort.createRouter(request, principal.getSessionId(), projectId);


마찬가지로 이번 이슈 사항이 아님.
기존 도메인에서 개발된 내용이므로 적용하지 않는다.

LEE-HYUN-JE · 2026-03-18T02:27:11Z

src/main/java/com/acc/local/controller/SecurityGroupController.java

-        JwtInfo jwtInfo = (JwtInfo) authentication.getPrincipal();
-        String id = securityGroupServicePort.createSecurityGroup(request, projectId, jwtInfo.getUserId());
+        SessionPrincipal principal = (SessionPrincipal) authentication.getPrincipal();
+        String id = securityGroupServicePort.createSecurityGroup(request, projectId, principal.getSessionId());


이번 이슈 사항이 아님.
기존 도메인에서 개발된 내용이므로 적용하지 않는다.

LEE-HYUN-JE added 18 commits March 10, 2026 12:23

Remove: JwtAuthenticationFilter·JwtInfo 제거 및 SecurityConfig 정리

125ba60

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

Refactor: Instance 도메인 세션 기반 전환 (Port/Adapter/Controller)

c99851f

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

Refactor: Network 도메인 세션 기반 전환 (Port/Adapter/Controller)

3bf5cee

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

Refactor: Image 도메인 세션 기반 전환 (Port/Adapter/Controller)

cda0015

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

Refactor: Keypair/QuickStart 도메인 세션 기반 전환 (Port/Adapter/Controller)

15b370f

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

Refactor: Project 도메인 세션 기반 전환 (Port/Adapter/Controller)

fb69a2b

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

Refactor: User/Role/Notice/Auth 도메인 세션 기반 전환 (Port/Adapter/Controller)

8e15644

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

Refactor: Volume 도메인 세션 기반 전환 (Port/Adapter/Controller)

afd0654

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

Feat: Keycloak 로그인 관리자 학적검증 우회

4c49217

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

docs : 세션 로그인/회원가입 및 인증 정리

bbe7385

Docs : 작업 시, 표시했던 주석 제거

cacea7c

github-code-quality bot found potential problems Mar 10, 2026

View reviewed changes

callme-waffle reviewed Mar 15, 2026

View reviewed changes

refactor : sessionId를 사용하지 않는 메서드에 대해서 sessionId 제거 완료

258234f

github-code-quality bot found potential problems Mar 18, 2026

View reviewed changes

LEE-HYUN-JE added 2 commits March 18, 2026 11:32

refactor : AjouUnivModule내 dto 반환 시 삼항 연산자 제거

be6053d

ㄱrefactor: 로그인 상태에서 로그인 api 호출 시, keycloak 을 거치지 않고, 즉시 리다이렉트응답 진행

f3b256a

Conversation

LEE-HYUN-JE commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📌 변경 요약 (Summary)

🔗 관련 이슈 (Related Issue)

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

✨ 주요 변경 사항 (Key Changes)

인증 방식 전환

Redis 세션 저장소

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

보안 강화

환경변수 변경

🧪 테스트 결과 (Test Results)

테스트 환경

테스트 방법

테스트 결과

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jalju0804 commented Mar 10, 2026

Uh oh!

callme-waffle left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LEE-HYUN-JE Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LEE-HYUN-JE Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

LEE-HYUN-JE commented Mar 10, 2026 •

edited

Loading

LEE-HYUN-JE Mar 18, 2026 •

edited

Loading

LEE-HYUN-JE Mar 18, 2026 •

edited

Loading