추가 인증이 필요한 화면을 Annotation + Guard로 다루는 구조

특정 화면만 한 번 더 인증해야 하는 요구사항은 자주 등장합니다.

다만 이 로직이 화면 조회 API, 로그인 API, 세션 관리, 레거시 인증 규칙과 뒤섞이기 시작하면 구조가 빠르게 복잡해집니다.

이 글은 Protected Screen API와 Additional Login API를 분리하고, Annotation + Guard 조합으로 화면 단위 추가 인증을 다루는 구조를 정리한 글입니다.

왜 화면 단위 추가 인증이 필요한가

서비스 전체 로그인과 별개로, 일부 화면만 추가 인증이 필요한 경우가 있습니다.

예를 들어 민감한 조회 화면이나 출력 화면은 사용자가 이미 로그인한 상태여도 한 번 더 확인하는 정책을 둘 수 있습니다.

이때 중요한 점은 화면 조회 자체가 로그인 API가 아니라는 것입니다.

먼저 세션이 있는지 확인하고, 없을 때만 별도 로그인 과정을 시작해야 합니다.

 

 

핵심 구조 한눈에 보기

구성요소	역할	무엇을 하지 않는가
API Gateway	Guard 실행, 메모리 세션 확인, 인증 성공 후 세션 저장, 보호 API 접근 제어	DB 직접 조회, 비밀번호 해시 비교, 레거시 인증 판단
Backend Server	추가 로그인 검증, 비밀번호 해시 비교, Legacy User Table 조회, 레거시 규칙 처리	화면 접근용 메모리 세션 관리
Protected Screen API	화면 데이터 조회	로그인 수행
Additional Login API	추가 인증 수행	화면 데이터 조회

 

구조의 핵심: 조회와 로그인을 분리한다

이 구조의 핵심은 두 가지입니다.

첫째, Protected Screen API는 데이터를 조회하는 역할만 가집니다.

둘째, Additional Login API는 추가 인증을 수행하는 역할만 가집니다.

두 책임이 섞이면 조회 요청 안에서 인증, DB 조회, 세션 저장까지 모두 처리하게 되고, 결과적으로 유지보수가 어려워집니다.

Client
  └─ Protected Screen API 호출
        └─ Guard가 메모리 세션 확인
             ├─ 세션 있음  → 조회 허용
             └─ 세션 없음  → 401 반환

Client
  └─ Additional Login API 호출
        └─ API Gateway가 Backend Server에 인증 위임
             └─ 성공 시 세션 생성
                  └─ 이후 Protected Screen API 재호출 허용

 

요청 흐름을 표로 보면 더 단순하다

단계	호출/행동	주체	결과
1	Protected Screen API 호출	Client	화면 조회 시도
2	Annotation + Guard로 세션 확인	API Gateway	세션 있으면 통과, 없으면 401
3	Additional Login API 호출	Client	추가 인증 시작
4	로그인 요청 전달	API Gateway	Backend Server에 인증 위임
5	Legacy User Table 조회 및 해시 비교	Backend Server	인증 성공/실패 판단
6	성공 시 메모리 세션 저장	API Gateway	동일 화면 재접근 허용

 

Annotation + Guard 패턴이 단순한 이유

 

화면별 추가 인증을 깔끔하게 적용하려면 엔드포인트마다 분기문을 넣기보다, Annotation으로 보호 대상을 표시하고 Guard가 공통 로직을 수행하게 만드는 편이 낫습니다.

예를 들어 screenKey를 Annotation으로 지정하고, Guard가 platformUserId + screenKey 기준으로 메모리 세션을 조회하도록 만들 수 있습니다.

@Get('/protected-screen')
@ScreenAccess(PROTECTED_SCREEN_KEY)
@UseGuards(ScreenAccessGuard)
getProtectedScreen() {
  // 조회 로직만 수행
}

이 방식의 장점은 명확합니다. 화면 API는 조회 로직에만 집중하고, 접근 제어는 Guard가 맡습니다. 새로운 화면이 생겨도 screenKey만 다르게 주면 같은 패턴을 재사용할 수 있습니다.

레거시 인증을 함께 다룰 때 주의할 점

추가 로그인 구조를 도입할 때 가장 많이 생기는 문제는 기존 인증 규칙을 어디에 둘 것인가입니다.

기준은 단순합니다.

Password Hash Type 변환, 해시 비교, 레거시 성공 조건 판단처럼 업무 의미가 있는 로직은 모두 Backend Server에 둡니다. Gateway는 그 결과를 받아 세션을 만들지 말지만 결정합니다.

이 원칙을 지키면 레거시 호환과 구조 단순화를 동시에 가져갈 수 있습니다.

판단 위치	예시
Guard	메모리 세션이 있는가
Backend Server	비밀번호가 맞는가, Legacy User Table 조건을 만족하는가, Password Hash Type 업데이트가 필요한가

 

이 구조에서 배운 점

추가 인증이 필요한 화면을 다룰 때는 로그인 로직을 화면 조회 요청 안에 섞지 않는 것이 중요합니다.

조회 API와 로그인 API를 분리하고, Guard는 세션만 확인하며, 실제 인증은 Backend Server에 맡기는 구조가 가장 단순하고 확장하기 쉽습니다.

특히 Annotation + Guard 패턴은 화면 단위 보호 요구사항이 늘어날수록 더 일관된 구조를 유지하게 해줍니다.