OpenAPI 인증 기술

OpenAPI 인증 기술 (Authentication)

API를 문서화할 때 인증·인가 방식도 빼놓을 수 없어요. OpenAPI는 인증·인가 방식을 security scheme이라는 용어로 표현하고, securitySchemes로 정의한 뒤 security로 적용해요.

출처: https://swagger.io/docs/specification/authentication/

OpenAPI 3.0이 지원하는 보안 스킴은 이래요.

  • HTTP 인증(Authorization 헤더 사용) — Basic, Bearer 등, RFC 7235가 정의한 스킴
  • API 키(헤더·쿼리·쿠키)
  • 쿠키 인증
  • OAuth 2
  • OpenID Connect Discovery

보안은 두 키워드로 기술해요. 먼저 securitySchemes에서 API가 지원하는 모든 보안 스킴의 정의를 만들고, 그다음 security로 특정 스킴을 API 전체 또는 개별 오퍼레이션에 적용해요.

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    OpenID:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration

루트 레벨에 security를 두면 모든 오퍼레이션에 전역 적용돼요. 개별 오퍼레이션에서 덮어써서 다른 인증을 쓰거나, 스코프를 바꾸거나, 인증을 아예 끌 수도 있어요.

paths:
  /billing_info:
    get:
      security:
        - OAuth2: [admin]
      responses:
        "200":
          description: OK

OAuth 2와 OpenID Connect는 적용할 때 필요한 스코프 목록을 함께 적어요. 예를 들어 /users의 GET은 [read], POST는 [write]처럼 오퍼레이션별로 스코프를 달리할 수 있어요. 그리고 security 항목이 하나일 땐 "그리고(AND)", 여러 security 항목이 있을 땐 "또는(OR)"으로 해석돼요.

OpenAPI 2.0에서 바뀐 점도 기억해 두면 좋아요. securityDefinitions는 components.securitySchemes로 이동하고 이름도 바뀌었고, type: basic은 type: http + scheme: basic으로 바뀌었어요. API 키가 쿠키(in: cookie)를 지원하게 됐고, OAuth 2 플로우가 OAuth 2 스펙에 맞춰 authorizationCode·clientCredentials로 이름이 바뀌었어요.

더 알아보기