[GPT Actions] 4. API 보안 및 인증 구현하기

파트 4: API 보안 및 인증 구현하기

안녕하세요! 이번 파트에서는 OpenAPI 스키마에서 API 보안과 인증을 구현하는 방법에 대해 알아보겠습니다. API를 안전하게 보호하는 것은 매우 중요합니다. 이를 통해 허가된 사용자만 API에 접근할 수 있도록 할 수 있습니다.

1. 보안 스키마 이해하기

OpenAPI에서는 다양한 보안 메커니즘을 지원합니다. 주요 보안 스키마는 다음과 같습니다:

• API Key: 간단한 키 기반 인증

• HTTP Authentication: 기본 인증 또는 Bearer 토큰 인증

• OAuth2: 더 복잡하지만 안전한 인증 방식

• OpenID Connect: OAuth2 기반의 인증 레이어

2. API Key 인증 추가하기

먼저 간단한 API Key 인증을 추가해 봅시다. my_api.yaml 파일의 components 섹션에 다음 내용을 추가해주세요:

components:
  # (이전 정의는 그대로 둡니다)
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

이 정의에 대해 설명드리겠습니다:

• type: apiKey는 API Key 방식의 인증을 사용한다는 의미입니다.

• in: header는 API Key를 HTTP 헤더에 포함시킨다는 뜻입니다.

• name: X-API-Key는 헤더의 이름을 지정합니다.

3. 보안 요구사항 적용하기

이제 정의한 보안 스키마를 API 전체 또는 특정 경로에 적용할 수 있습니다. 전체 API에 적용하려면 루트 레벨에 security 필드를 추가합니다:

openapi: 3.1.0
info:
  title: My Awesome Bookstore API
  version: 1.0.0
# (다른 최상위 필드들)
security:
  - ApiKeyAuth: []

특정 경로에만 적용하려면 해당 경로에 security 필드를 추가합니다:

paths:
  /books:
    get:
      summary: List all books
      security:
        - ApiKeyAuth: []
      # (나머지 정의는 그대로 둡니다)

4. Bearer 토큰 인증 추가하기

이번에는 좀 더 안전한 Bearer 토큰 인증을 추가해 봅시다. components 섹션에 다음 내용을 추가해주세요:

components:
  securitySchemes:
    ApiKeyAuth:
      # (이전 정의는 그대로 둡니다)
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

• type: http는 HTTP 인증 방식을 사용한다는 의미입니다.

• scheme: bearer는 Bearer 토큰 방식을 사용한다는 뜻입니다.

• bearerFormat: JWT는 JSON Web Token 형식을 사용한다는 것을 나타냅니다.

5. OAuth2 인증 추가하기

더 복잡한 시나리오에서는 OAuth2를 사용할 수 있습니다. OAuth2를 추가해 봅시다:

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read:books: Read access to books
            write:books: Write access to books

• type: oauth2는 OAuth2 인증 방식을 사용한다는 의미입니다.

• flows: OAuth2의 다양한 플로우 중 어떤 것을 사용할지 지정합니다.

• authorizationCode: 가장 일반적인 OAuth2 플로우입니다.

• scopes: 다양한 접근 권한을 정의합니다.

6. 여러 인증 방식 조합하기

때로는 여러 인증 방식을 조합해서 사용해야 할 수도 있습니다. 예를 들어, API Key와 OAuth2를 함께 사용하고 싶다면:

security:
  - ApiKeyAuth: []
    OAuth2: [read:books]
  - BearerAuth: []

이 정의는 "ApiKeyAuth와 OAuth2의 read:books 스코프를 모두 만족하거나, 또는 BearerAuth를 만족해야 한다"는 의미입니다.

[연습문제]

이제 여러분 차례입니다! 다음 요구사항을 만족하도록 보안 설정을 추가해보세요:

• '/books' GET 경로: ApiKeyAuth 또는 OAuth2의 read:books 스코프 필요

• '/books' POST 경로: OAuth2의 write:books 스코프 필요

• '/authors' 모든 경로: BearerAuth 필요

  [정답]

여러분의 설정이 다음과 비슷하다면 정답입니다:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read:books: Read access to books
            write:books: Write access to books

paths:
  /books:
    get:
      summary: List all books
      security:
        - ApiKeyAuth: []
        - OAuth2: [read:books]
      # (나머지 정의는 그대로 둡니다)
    post:
      summary: Add a new book
      security:
        - OAuth2: [write:books]
      # (나머지 정의는 그대로 둡니다)
  
  /authors:
    get:
      summary: List all authors
      security:
        - BearerAuth: []
      # (나머지 정의는 그대로 둡니다)
    post:
      summary: Add a new author
      security:
        - BearerAuth: []
      # (나머지 정의는 그대로 둡니다)

축하합니다! 이번 파트에서 우리는 OpenAPI 스키마에 보안과 인증을 추가하는 방법을 배웠습니다. API Key, Bearer 토큰, OAuth2 등 다양한 인증 방식을 정의하고 적용하는 방법을 알아보았습니다.

API 보안은 매우 중요한 주제입니다. 실제 운영 환경에서는 항상 HTTPS를 사용하고, 토큰을 안전하게 관리하며, 필요한 경우 rate limiting 등의 추가적인 보안 조치를 취해야 합니다.

다음 파트에서는 OpenAPI 스키마를 활용하여 API 문서를 생성하고 테스트하는 방법에 대해 알아보겠습니다.