[Spring Oauth2] 인증 서버 구축기

https://github.com/VenusIM/Spring-Oauth-Server

---

목차

1. 프로젝트 구조 한눈에 보기
2. 보안 구성: SecurityConfig
3. 요청 본문 복호화 필터: TokenBodyDecryptFilter
4. 전처리 컨버터(Validation Layer)
5. 핸들러/예외 매퍼
6. 유틸리티(암호화/응답/파라미터 래핑)
7. 도메인/저장소(토큰/멤버/Redis)
8. 엔드포인트 동작 흐름
9. 실행·운영 체크리스트
10. 트러블슈팅
11. 부록(코드 발췌)

---

1) 프로젝트 구조 한눈에 보기

• 루트 패키지: com.venusim.auth
• 주요 서브 패키지
  • global.config – 보안/클라이언트 설정 조립
  • global.filter – CBC+Base64 복호화 후 파라미터 주입
  • global.converter – 요청 전처리/유효성 검증 컨버터
  • global.handler – 성공/실패/예외 매핑
  • global.util – KISA_SEED_CBC, AuthUtil, ParamOverrideRequest
  • domain – 토큰/저장소(예: Redis)
  • domain.member – memid/tmpkey 검증용 엔티티/리포지토리/서비스

---

2) 보안 구성: SecurityConfig

역할: Spring Security 및 Authorization Server 관련 엔드포인트(/oauth2/token, /oauth2/introspect, /oauth2/revoke)를 조합하고, 아래 전처리/핸들러/필터를 연결합니다.

• 전처리:
  PreValidateTokenRequestConverter, PreValidateValidRequestConverter,
  PreValidateClientAuthConverter, CommonVerboseAuthenticationConverter
• 핸들러:
  CustomAuthenticationSuccessHandler, CustomAuthenticationFailureHandler,
  CustomIntrospectionSuccessHandler, CustomRevocationSuccessHandler
• 필터:
  TokenBodyDecryptFilter (CBC+Base64 복호화 → 파라미터 주입)

포인트

• Basic 헤더/필수 파라미터 유효성을 사전에 강하게 검증하여 표준 오류로 빠르게 응답합니다.
• /oauth2/** 요청에서 본문은 text/plain을 사용하고, 필터에서 Base64→SEED-CBC 복호화 후 다음 체인에서 일반 폼 파라미터처럼 읽습니다.

---

3) 요청 본문 복호화 필터: TokenBodyDecryptFilter

조건: Content-Type: text/plain & URI.startsWith("/oauth2") 일 때 동작.
동작: Body를 읽어 URLDecode → Base64 디코드 → SEED-CBC 복호화 → key=value&... 파싱 → ParamOverrideRequest로 파라미터 교체 → 다음 체인.

복호화 실패 시에는 경고/에러 로깅 후 원본 요청 그대로 통과시켜, 하위 단계에서 검증 실패로 처리됩니다.

---

4) 전처리 컨버터(Validation Layer)

모두 AuthenticationConverter 계열로, 인증에 앞서 입력을 표준 에러코드(OAuth2ErrorCodes)로 검증합니다.

• PreValidateClientAuthConverter:
  Authorization: Basic ... 헤더의 존재/형식(Base64)/client_id:client_secret 복합값을 확인.
  포맷/디코드 오류 → invalid_request 또는 invalid_client.
• PreValidateTokenRequestConverter:
  /oauth2/token 요청의 grant_type, memid, tmpkey 등 필수 파라미터 점검.
  조건 불충족 → unsupported_grant_type/invalid_request.
• PreValidateValidRequestConverter:
  공통 파라미터/값 범위를 재확인하여 조기 실패.
• CommonVerboseAuthenticationConverter:
  오류 메시지를 풍부하게 제공(개발 시 디버깅 친화적). 운영에서는 메시지/로그 마스킹 권장.

---

5) 핸들러/예외 매퍼

• AuthExceptionMapper:
  Spring Security/OAuth2 예외를 표준 JSON 에러로 변환(invalid_request, invalid_client, invalid_token 등).
• 성공/실패 핸들러들:
  • /oauth2/token 성공 시: access_token, token_type, expires_in JSON → CBC_ENC+Base64 문자열을 text/plain으로 반환.
  • /oauth2/introspect 성공 시: active, sub, aud, client_id 등 → CBC_ENC+Base64.
  • /oauth2/revoke 성공 시: 항상 200 OK(RFC 7009 멱등 처리).

---

6) 유틸리티

• KISA_SEED_CBC: SEED-CBC 라운드/상수/연산 포함 클래스. (KISA 공개 구현 기반)
• AuthUtil: 키/IV 주입(app.seed-cbc-key, app.seed-cbc-iv), Base64 변환, 캐시방지 헤더, text/plain 응답 작성(암호화 후 Base64).
• ParamOverrideRequest: 복호화된 파라미터를 기존 요청에 오버라이드하여 다음 필터/컨버터가 그대로 getParameter(...)를 사용할 수 있게 함.

---

7) 도메인/저장소

• RedisOAuth2AuthorizationService:
  토큰 발급/검증/폐기를 Redis로 관리. 키 접두사 규칙과 TTL을 통해 활성/비활성 상태를 빠르게 판별.
• TokenRecord:
  토큰 메타 모델(발급 시각/만료/클라이언트/서브젝트 등).
• domain.member:
  MemberSsoRandomEntity 및 Repository/Service로 memid/tmpkey 검증을 담당. 발급 전에 임시키 조건을 체크.

---

8) 엔드포인트 동작 흐름 (요약)

1. 클라이언트는 본문을 SEED-CBC로 암호화 후 Base64 하여 text/plain으로 전송.
2. 서버는 TokenBodyDecryptFilter에서 복호화/파싱 → 파라미터 주입.
3. 전처리 컨버터가 Basic 헤더/필수 파라미터/값을 검증.
4. 성공 시 핸들러가 JSON을 만들고 CBC_ENC+Base64 문자열을 text/plain으로 응답.

• POST /oauth2/token – 발급/재발급
• POST /oauth2/introspect – 활성 상태 조회
• POST /oauth2/revoke – 폐기(항상 200)

---