[스나이퍼팩토리] 한컴AI 2기 - Fast API Security : Authorize 및 OAuth2PasswordBearer

Fast API 환경에서,

프론트엔드가 사용자 이름과 비밀번호를 사용하여 백엔드에 인증하는 방법은 OAuth2로 구현할 수 있다.

구현 방식

1. main.py 생성

from typing import Annotated

from fastapi import Depends, FastAPI
from fastapi.security import OAuth2PasswordBearer

app = FastAPI()

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


@app.get("/items/")
async def read_items(token: Annotated[str, Depends(oauth2_scheme)]):
    return {"token": token}

2. Swagger UI docs에서 확인

uvicorn main:app --reload

 

명령어로 Fast API 서버를 실행했다면, http://127.0.0.1:8000/docs링크에서 스웨거 문서를 확인할 수 있다.

Swagger docs

우상단의 Authorize 버튼을 클릭하면,

이런 창을 맞이하게 된다. 이 폼 양식은 API를 디버그, 확인, 테스트 하는 데 사용될 수 있다.

 

패스워드 플로우

플로우 방식은 OAuth2에서 정의된 보안 및 인증 처리 방법 중 하나이다. OAuth2는 백엔드나 API가 사용자를 인증하는 서버와 독립적으로 작동할 수 있도록 설계되었다. (예제에서는 동일한 FastAPI 애플리케이션이 API와 인증을 모두 처리하는 간소화 코드)

• 사용자가 프론트엔드에서 username과 password를 입력하고 Enter
• 프론트엔드(사용자의 브라우저에서 실행 중)는 해당 username과 password를 API의 특정 URL(tokenUrl="token"으로 선언됨)로 전송
• API는 사용자 이름과 비밀번호를 확인한 후 토큰을 응답으로 반환
  • 토큰은 (나중에 이 사용자를 확인하는 데 사용할 수 있는) 특정 내용이 담긴 문자열이다.
  • 일반적으로 토큰은 일정 시간이 지나면 만료되도록 설정된다.
    • 따라서 사용자는 나중에 다시 로그인해한다
    • 토큰이 도난당하더라도 위험은 상대적으로 적다. (영구적으로 작동하는 대부분의 경우와 다름)
• 프론트엔드는 어딘가에 토큰을 임시로 저장
• 사용자가 프론트엔드 웹 앱의 다른 섹션으로 이동하기 위해 클릭
• 프론트엔드는 API로부터 추가 데이터를 가져와야 함
  • 하지만 해당 특정 엔드포인트에 대한 인증이 필요
  • 따라서 API에 인증하기 위해, 헤더 Authorization에 값 Bearer와 토큰을 추가하여 전송
  • 토큰에 foobar 가 포함되어 있다면, Authorization헤더의 내용은 Bearer foobar와 같은 식

OAuth2PasswordBearer 예제

from typing import Annotated

from fastapi import Depends, FastAPI
from fastapi.security import OAuth2PasswordBearer

app = FastAPI()

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


@app.get("/items/")
async def read_items(token: Annotated[str, Depends(oauth2_scheme)]):
    return {"token": token}

OAuth2PasswordBearer클래스의 인스턴스를 생성할 때 tokenUrl 매개변수를 전달한다. 이 매개변수는 클라이언트(사용자 브라우저에서 실행되는 프론트엔드)가 토큰을 획득하기 위해 username과 password를 전송할 때 사용할 URL을 포함한다.

상대 URL 사용

여기서 tokenUrl="token"은 아직 생성하지 않은 상대 경로 토큰을 가리킨다. (상대 경로이므로 ./token과 동일)
상대 경로를 사용하므로, API가 https://example.com/에 위치해 있다면 https://example.com/token을 참조하게되고,
API가 https://example.com/api/v1/에 위치해 있다면, https://example.com/api/v1/token을 가리키게된다.

객체 호출 방식

oauth2_scheme 변수는 OAuth2PasswordBearer의 인스턴스이지만, 동시에 호출 가능 객체이기도하다.

oauth2_scheme(some, parameters)

Depends와 함께 사용된다.

• 이 종속성은 경로 작업 함수의 매개변수 token에 할당되는 문자열을 제공하고,
• FastAPI는 이 종속성을 사용하여 OpenAPI 스키마(및 자동 생성된 API 문서)에서 보안 체계를 정의할 수 있음을 인식한다.

FastAPI는 OAuth2PasswordBearer 클래스(의존성에서 선언됨)가 fastapi.security.oauth2.OAuth2를 상속하고, 이는 다시 fastapi.security.base.SecurityBase를 상속하기 때문에 OpenAPI에서 보안 체계를 정의하는 데 사용할 수 있음을 인식한다.

OpenAPI(및 자동 생성 API 문서)와 통합되는 모든 보안 유틸리티는 SecurityBase를 상속받는다. 이것이 FastAPI가 OpenAPI에 이를 통합하는 방법을 알 수 있는 방식이다.

기능 설명

요청에서 Authorization 헤더를 검색하고, 값이 Bearer와 토큰으로 구성되었는지 확인한 후 토큰을 문자열(str)로 반환다.
Authorization 헤더가 없거나 값에 Bearer 토큰이 포함되지 않은 경우, 직접 401 상태 코드 오류(UNAUTHORIZED)로 응답한다.
토큰 존재 여부를 확인하지 않고도 오류 응답을 반환할 수 있다. 함수가 실행되면 반드시 해당 토큰에 문자열이 포함되어 있을 것이므로 확신해도 된다.

Swagger 문서에서 테스트 해볼 수 있다.

---

예제 처럼 3~4줄만의 코드 추가만으로 기본적인 형태의 보안 기능을 구현할 수 있었다. 이후 JWT 토큰 사용을 위한 PyJWT 및 패스워드 해싱의 국룰과도 같은 passlib과 bcrypt 내용이 더해지면, 중규모 프로젝트에서도 충분한 수준이 될 것 같다.

Facebook, Google, GitHub, Microsoft, X 등의 빅테크의 인증 매커니즘까지 가려면, 스코프를 사용하는 심화 방법을 자세히 배워야 할 것 같다.

---

본 후기는 [한글과컴퓨터x한국생산성본부x스나이퍼팩토리] 한컴 AI 아카데미 2기 (B-log) 리뷰로 작성 되었습니다.