OpenAPI 보안 스키마로 API를 보안하는 방법

API를 개발하거나 사용하는 경우, 무단 액세스 및 오용으로부터 보호하는 것이 얼마나 중요한지 잘 알고 있을 것입니다. API는 많은 현대 애플리케이션의 중추이며, 적절한 인증 및 권한 부여 메커니즘으로 보안을 유지해야 합니다.

그런데 API의 보안 요구 사항을 어떻게 설명하고 문서화합니까? API 소비자가 API에 안전하고 정확하게 접근하는 방법을 어떻게 보장합니까? 서로 다른 API 및 보안 체계 간의 혼란과 불일치 문제를 어떻게 피합니까?

이것이 OpenAPI 보안 체계가 유용하게 사용되는 곳입니다. OpenAPI는 기계 판별 가능하고 인간 친화적인 형식으로 API를 설명하고 문서화하는 데 널리 사용되는 표준입니다. OpenAPI 보안 체계는 API를 보호하는 보안 메커니즘을 정의하고 참조할 수 있게 해주는 OpenAPI 사양의 일부입니다.

이 블로그 게시물에서는 OpenAPI 보안 체계가 무엇인지, 어떻게 작동하는지, 그리고 이를 사용하여 API를 보안하는 방법을 설명합니다. 또한 OpenAPI 보안 체계의 몇 가지 예와 API를 설계하고 테스트하며 문서화하는 데 유용한 도구인 Apidog와 함께 사용하는 방법도 보여 드리겠습니다.

button

OpenAPI 보안 체계란 무엇인가요?

OpenAPI 보안 체계는 OpenAPI 사양을 사용하여 API의 보안 요구 사항을 설명하는 방법입니다. 이것은 OpenAPI 문서의 components/securitySchemes 섹션에 정의되어 있으며, API의 루트 레벨 또는 작업 레벨에서 security 키워드를 사용하여 참조할 수 있습니다.

OpenAPI 보안 체계는 다음과 같은 다양한 유형의 보안 메커니즘을 설명할 수 있습니다:

API 키
HTTP 인증 체계 (기본 인증, 베어러 등)
OAuth 2.0
OpenID Connect

각 보안 체계는 보안 메커니즘의 유형을 나타내는 type 속성과 해당 유형에 따라 달라지는 다른 속성을 가집니다. 예를 들어, API 키 보안 체계는 API 키를 포함하는 헤더, 쿼리 파라미터 또는 쿠키의 이름을 지정하는 name 속성과 API 키의 위치를 지정하는 in 속성을 가집니다.

다음은 API 키 보안 체계의 예입니다:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header

API 또는 특정 작업에 보안 체계를 적용하려면 security 키워드를 사용하고 보안 요구 사항 객체의 배열을 제공해야 합니다. 보안 요구 사항 객체는 보안 체계 이름을 범위 이름 (OAuth 2.0 및 OpenID Connect의 경우) 또는 빈 배열 (다른 유형의 경우)로 매핑하는 것입니다.

예를 들어, 전체 API에 API 키 보안 체계를 적용하려면 다음 구문을 사용할 수 있습니다:

security:
  - ApiKeyAuth: []

특정 작업에 API 키 보안 체계를 적용하려면 다음 구문을 사용할 수 있습니다:

paths:
  /pets:
    get:
      security:
        - ApiKeyAuth: []

API 또는 특정 작업에 대해 여러 보안 체계를 사용할 수 있으며, 이것은 대체 (논리적 OR) 또는 조합 (논리적 AND)으로 적용할 수 있습니다. 예를 들어, 특정 작업에 대해 API 키 또는 베어러 토큰 중 하나를 요구하려면 다음 구문을 사용할 수 있습니다:

paths:
  /pets:
    get:
      security:
        - ApiKeyAuth: []
        - BearerAuth: []

특정 작업에 대해 API 키와 베어러 토큰을 모두 요구하려면 다음 구문을 사용할 수 있습니다:

paths:
  /pets:
    get:
      security:
        - ApiKeyAuth: []
          BearerAuth: []

왜 OpenAPI 보안 체계를 사용해야 하나요?

OpenAPI 보안 체계는 API 제공자와 소비자 모두에게 여러 가지 이점을 제공합니다:

API의 보안 요구 사항을 설명하는 명확하고 일관된 방법을 제공하여 서로 다른 API 소비자와 개발자 간의 혼란과 오류를 피할 수 있습니다.
API에 안전하고 올바르게 액세스하는 방법을 보여주는 대화형 문서 및 코드 샘플을 생성할 수 있어 사용자 경험을 개선하고 API 학습 곡선을 줄일 수 있습니다.
OpenAPI 사양을 지원하는 다양한 도구와 플랫폼에 API를 통합할 수 있어 API를 보다 쉽게 설계, 테스트 및 문서화할 수 있도록 도와줍니다.

Apidog와 함께 OpenAPI 보안 체계를 사용하는 방법

Apidog는 API를 설계하고 테스트하며 문서화하기 위한 강력한 도구입니다. OpenAPI 사양을 지원하며 시각적이고 직관적인 방식으로 OpenAPI 문서를 생성하고 편집할 수 있습니다. 또한 라이브 테스트, 모의 서버, 코드 생성 및 대화형 문서화와 같은 기능을 제공합니다.

button

Apidog의 장점 중 하나는 OpenAPI 문서에서 정의한 보안 체계를 자동으로 감지하고 적용할 수 있다는 것입니다. 예를 들어, API 키 보안 체계를 정의하면 Apidog가 API 키를 입력하라는 프롬프트를 표시하고 요청과 함께 이를 전송합니다. OAuth 2.0 보안 체계를 정의하면 Apidog가 권한 부여 프로세스를 안내하고 액세스 토큰을 얻고 새로 고칩니다.

Apidog와 함께 OpenAPI 보안 체계를 사용하려면 다음 단계를 따르십시오:

Apidog에서 새 프로젝트를 생성하거나 기존 OpenAPI 문서를 가져옵니다.
앞서 설명한 구문과 속성을 사용하여 OpenAPI 문서의 components/securitySchemes 섹션에 보안 체계를 정의합니다.
API의 루트 레벨 또는 작업 레벨에서 security 키워드에 보안 체계를 참조합니다.
OpenAPI 문서를 저장하고 Apidog의 테스트 탭으로 전환합니다.
보안을 요구하는 작업을 선택하고 오른쪽 패널에서 보안 버튼을 클릭합니다.
보안 체계 유형에 따라 API 키, 사용자 이름 및 비밀번호 또는 권한 부여 코드를 요구하는 보안 매개변수를 입력합니다.
보안 매개변수와 함께 요청을 전송하려면 보내기 버튼을 클릭합니다.

Apidog는 API의 응답을 표시하고 요청 및 보안 매개변수의 세부 정보를 보여줍니다. 또한 코드 탭에서 원시 OpenAPI 문서를 보고 편집할 수 있으며, 문서 및 코드 탭에서 대화형 문서 및 코드 샘플을 생성할 수 있습니다.

결론

OpenAPI 보안 체계는 API의 보안 요구 사항을 설명하고 문서화할 수 있는 OpenAPI 사양의 유용한 기능입니다. 이는 API 소비자와 개발자에게 API를 보호하는 보안 메커니즘을 전달하고, API에 안전하고 올바르게 액세스하는 방법을 보여주는 대화형 문서 및 코드 샘플을 생성할 수 있게 해줍니다.

또한 OpenAPI 사양을 지원하는 다양한 도구 및 플랫폼과 API를 통합할 수 있도록 도와줍니다. Apidog와 같은 도구는 API를 보다 쉽게 설계, 테스트 및 문서화하는 데 큰 도움이 됩니다.

button