RAG 기반 문서 검색 시스템 - 4(인증/권한/사용자/ORM 연동)

개요

앞선 글에서는 Next.js 기반 프론트엔드 구조를 수립하고, 인증 및 사용자 경험을 강화하기 위한 세부 작업을 정리했다. 이번 글에서는 인증/권한/사용자/ORM 연동을 중심으로 다루며 FastAPI 기반 백엔드 프로젝트의 사용자 인증 및 권한 시스템을 구축하면서의 전 과정을 정리한다. 본 작업은 초기 백엔드 시스템의 기초 골격을 형성하는 핵심 작업이다.

1. DB 환경 설정과 Alembic 마이그레이션 문제 해결

초기 DB 설정 단계에서는 Alembic 마이그레이션 오류가 지속적으로 발생했다. 원인은 인코딩 문제, 계정 설정 오류, 권한 부족 등이 복합적으로 작용한 것이었다. 다음과 같은 조치를 통해 문제를 해결했다.

• 모든 설정 파일을 UTF-8(BOM 없음) 형식으로 저장
• DB 계정, 비밀번호, 데이터베이스명은 영문/숫자 조합으로 구성
• DB 계정에 public 스키마 소유권 및 모든 권한 부여
• 환경 변수, 시스템 로케일, 가상환경, psycopg2 설치 상태 점검
• 직접 psycopg2로 DB 연결 테스트 후 Alembic 마이그레이션 정상 완료 확인

2. OAuth2.0 + JWT 기반 인증 플로우 구현

인증 플로우는 FastAPI의 OAuth2PasswordBearer를 기반으로 JWT를 발급하고, 이를 통해 사용자 인증을 처리하도록 구성했다. 주요 내용은 다음과 같다.

• /api/auth/token 엔드포인트에서 사용자 로그인 시 JWT 토큰 발급
• 토큰에는 사용자 ID, 권한(Role), 만료 시간 등의 정보 포함
• 비밀번호는 해시 후 저장하고, 비교 시 해시 기반 검증 수행
• 토큰 만료 및 인증 실패 시 명확한 에러 메시지 반환

Swagger UI를 통해 테스트 계정으로 로그인, 토큰 발급, 인증 검증을 정상적으로 확인했다.

3. Role 기반 권한 제어 미들웨어 적용

JWT 토큰 내 Role 정보를 기반으로 사용자의 권한을 제어하는 미들웨어 require_role을 구현하였다. 이를 통해 관리자, 에디터, 뷰어 권한에 따라 API 접근을 제한하였다.

• require_role 데코레이터를 통해 각 API 엔드포인트에 권한 조건 부여
• 권한이 부족한 사용자는 403 Forbidden 응답 처리
• Swagger UI를 통해 각 권한별 접근 제한 정상 작동 확인

4. 사용자 모델 및 CRUD API 구현

사용자 관리를 위한 SQLAlchemy 기반 ORM 모델과 Pydantic 스키마를 정의하고, 이를 활용한 CRUD API를 구현했다. 인증 및 권한 미들웨어와 연동하여 실질적인 사용자 관리 기능을 완성했다.

• User ORM 모델 정의 및 Pydantic 모델(UserCreate, UserRead, UserUpdate) 분리
• UserService를 통해 비즈니스 로직 분리 및 캡슐화
• 사용자 생성/조회/수정/삭제 API 구현
• CRUD API 모두 인증 및 권한 미들웨어 적용

Swagger UI에서 테스트 계정으로 모든 CRUD 요청이 정상 동작하는 것을 확인하였다.

사용된 용어 정리

용어	설명
JWT	JSON Web Token. 사용자 인증 정보를 담아 서버-클라이언트 간 인증을 처리하는 토큰
OAuth2.0	외부 인증 방식을 위한 표준 프로토콜. 토큰 기반 인증을 제공함
psycopg2	Python에서 PostgreSQL에 접속하기 위한 라이브러리
Alembic	SQLAlchemy 기반의 DB 마이그레이션 도구
Role	사용자 권한 수준을 구분하는 값 (예: viewer, editor, admin)
Pydantic	Python 타입 검증 및 직렬화를 지원하는 라이브러리. FastAPI에서 요청/응답 모델로 활용됨

마무리

이번 작업을 통해 FastAPI 기반 백엔드의 인증 및 사용자 관리의 기반을 안정적으로 구축했다. DB 환경설정부터 시작해 인증 플로우, 권한 미들웨어, CRUD API까지 전반적인 흐름을 갖춘 구조를 완성했으며, 이후 확장되는 서비스에서도 해당 구조를 재사용 가능하도록 모듈화하였다. 다음 작업에서는 문서 업로드 및 AWS S3 저장/바이러스 검사 기능 구현을 진행할 예정이다.