🔐 FastAPI 보안(OAuth2, JWT)

🕒 약 2분 읽는 데 소요됩니다

이전 글 보기(FastAPI의 중간처리와 이벤트 시스템)

– OAuth2, JWT, 사용자 인증을 안전하고 효율적으로 구현해보자

“API의 기능보다 중요한 건 바로 보안이다. 아무리 잘 만든 API라도 보안이 허술하면 무용지물이다.”

FastAPI는 보안에 대한 기능을 매우 강력하게 지원하며, 특히 OAuth2 및 JWT 기반 인증 시스템을 통해 API 접근을 제어할 수 있도록 설계되어 있다.

---

1. 🧭 인증(Authentication) vs 권한(Authorization)

먼저 가장 중요한 두 개념을 구분하자.

• 인증(Authentication): 이 사용자가 누구인지 확인하는 절차. 예: 로그인
• 권한(Authorization): 이 사용자가 특정 리소스에 접근 가능한지를 결정. 예: 관리자만 글 삭제 가능

FastAPI는 이 두 개념을 구분해서 처리할 수 있는 기능을 제공한다.

---

2. 🔑 OAuth2란 무엇인가?

OAuth2는 인증을 위한 표준 프로토콜이다. 보통 **”토큰 기반 인증 방식”**을 의미하며, 클라이언트는 사용자 이름과 비밀번호로 토큰을 발급받고 이후 요청에 이 토큰을 포함해 인증을 받는다.

FastAPI는 OAuth2의 흐름을 단순화하여 다음 구조를 제공한다:

1. /token 경로로 사용자 인증 요청
2. 서버에서 JWT 토큰 발급
3. 클라이언트는 이 토큰을 Authorization 헤더에 담아 API 요청

---

3. 🔐 JWT(Json Web Token)란?

JWT는 JSON 기반의 서명된 문자열 토큰으로, 사용자 정보를 안전하게 담을 수 있다. 구조는 다음과 같다:

Header.Payload.Signature

예시:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTYifQ.signature

• Header: 알고리즘 정보
• Payload: 사용자 정보 (예: user_id, username 등)
• Signature: 위 정보를 기반으로 서명된 값 (위조 방지)

FastAPI는 JWT 토큰을 만들어서 사용자가 로그인할 때마다 이를 클라이언트에 전달하고, 이후 요청마다 토큰을 검증해 인증을 처리한다.

---

4. ⚙️ JWT 인증 흐름 구성하기

1. 로그인 요청을 받아 사용자의 정보를 검증한다.
2. 검증에 성공하면 JWT 토큰을 생성해서 응답으로 보낸다.
3. 클라이언트는 이 토큰을 매 API 요청 시 헤더에 담는다.
4. 서버는 해당 토큰을 검증하고 사용자 정보를 식별한다.

---

5. 🛠 실제 예제 코드로 이해해보자

필요한 라이브러리 설치

먼저 아래 라이브러리를 설치하자:

pip install python-jose[cryptography] passlib[bcrypt]

사용자 모델 정의

from pydantic import BaseModel

class User(BaseModel):
    username: str
    password: str

JWT 토큰 생성 함수

from jose import jwt
from datetime import datetime, timedelta

SECRET_KEY = "secret-key"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30

def create_access_token(data: dict):
    to_encode = data.copy()
    expire = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)

로그인 라우터

from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
app = FastAPI()

@app.post("/token")
async def login(form_data: OAuth2PasswordRequestForm = Depends()):
    if form_data.username != "admin" or form_data.password != "1234":
        raise HTTPException(status_code=401, detail="Invalid credentials")
    token = create_access_token({"sub": form_data.username})
    return {"access_token": token, "token_type": "bearer"}

---

6. 🔍 사용자 인증 및 권한 확인

인증된 사용자 가져오기

from jose import JWTError, jwt

def get_current_user(token: str = Depends(oauth2_scheme)):
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str = payload.get("sub")
        if username is None:
            raise HTTPException(status_code=401, detail="Invalid token")
        return {"username": username}
    except JWTError:
        raise HTTPException(status_code=401, detail="Invalid token")

이 함수를 Depends로 다른 라우터에 주입하면, 자동으로 인증된 사용자 정보가 전달된다.

인증이 필요한 API 예시

@app.get("/users/me")
async def read_users_me(current_user: dict = Depends(get_current_user)):
    return {"user": current_user}

---

7. 🛡 권한 관리 – 관리자만 접근 가능하게 만들기

권한을 세분화하려면 사용자 정보에 role이나 is_admin 같은 속성을 넣어주면 된다.

def get_admin_user(current_user: dict = Depends(get_current_user)):
    if current_user.get("username") != "admin":
        raise HTTPException(status_code=403, detail="관리자만 접근 가능합니다.")
    return current_user

@app.get("/admin")
async def read_admin_dashboard(admin_user: dict = Depends(get_admin_user)):
    return {"msg": "관리자 페이지입니다."}

이렇게 하면 admin이라는 사용자만 /admin 경로에 접근할 수 있다.

---

8. 🔒 보안을 위한 팁

• JWT의 SECRET_KEY는 외부에 노출되지 않도록 환경 변수로 관리하자.
• ACCESS_TOKEN_EXPIRE_MINUTES를 너무 길게 설정하지 말자. 일반적으로 15~30분이 적절하다.
• 클라이언트는 토큰을 반드시 HTTPS로 전달해야 한다.
• 사용자 정보는 토큰에 과도하게 담지 말고 최소화하자.

---

9. ✅ 정리해보자

보안은 복잡하지만, 한 번 구조를 잡아두면 안정적인 API 운영이 가능하다. FastAPI는 OAuth2와 JWT 토큰을 통한 인증 시스템을 비교적 쉽게 구축할 수 있도록 도와준다.

기능	역할	구성 요소
OAuth2	인증 프로토콜	Token 발급 및 인증 흐름
JWT	사용자 정보 토큰화	Header, Payload, Signature
Depends	인증 및 권한 검사 주입	get_current_user, get_admin_user 등

FastAPI 공식 문서 : https://fastapi.tiangolo.com/ko/