빠르게 진화하는 API 개발 환경에서 보안은 단순한 기능이 아니라 기본적인 필수 요소입니다. 무단 액세스로부터 엔드포인트를 보호하는 것이 가장 중요하지만, 여러 엔드포인트와 다양한 팀원 간에 인증을 일관되게 관리하는 것은 복잡하고 오류가 발생하기 쉽습니다. 전통적인 방법은 종종 각 엔드포인트마다 반복적인 구성을 포함하여 일관성을 저하시키고 잠재적인 취약점을 초래합니다. 이러한 문제를 인식하고, Apidog은 새로운 보안 스키마 기능의 출시를 발표하게 되어 기쁩니다. 이 기능은 이 올인원 API 개발 플랫폼 내에서 API 인증 및 권한 부여를 관리하는 방식을 간소화하고 표준화하도록 설계되었습니다.
이 강력한 새로운 기능은 OpenAPI 사양 (OAS)을 기반으로 재사용 가능한 인증 템플릿을 정의할 수 있게 하여, 준수 및 상호 운용성을 보장하면서 여러분의 작업 흐름을 극적으로 단순화합니다. 보안 스키마란 무엇인지, OpenAPI 사양과 어떻게 일치하는지, ApiDog에서 보안 스키마 기능을 어떻게 활용하여 API를 강화할 수 있는지를 이해하고 마스터하기 위해 이 포괄적인 가이드를 탐색해 보세요.
OpenAPI 사양에 따른 보안 스키마란 무엇인가요?
ApiDog의 구현에 들어가기 전에 명확히 해두겠습니다: 보안 스키마란 무엇인가요? OpenAPI 사양 (OAS) 3.0의 맥락에서 "보안 스키마"라는 용어는 엔드포인트에 대한 요청을 인증하거나 권한을 부여하는 데 사용되는 특정 방법의 정의를 나타냅니다. 이는 특정 자격 증명(실제 API 키나 비밀번호와 같은 것)보다는 인증이 어떻게 작동하는지를 설명하는 청사진이나 템플릿으로 생각할 수 있습니다.
OpenAPI는 보안 스키마에 대한 몇 가지 표준 유형을 정의합니다:
1. http: Authorization 헤더를 사용하는 표준 HTTP 인증 메커니즘을 포함합니다. 여기에는:
- 기본 인증: 사용자 이름/비밀번호 인증입니다.
- 베어러 인증: "Bearer "로 접두사가 붙은 토큰(예: JWT)을 사용합니다.
2. HTTP 인증 스키마 레지스트리에 등록된 기타 스키마입니다.
apiKey: 요청 헤더, 쿼리 매개변수 또는 쿠키로 전달되는 API 키를 위한 것입니다.oauth2: 다양한 흐름(인증 코드, 클라이언트 자격 증명 등)을 지원하는 널리 채택된 OAuth 2.0 권한 부여 프레임워크를 위한 것입니다.openIdConnect: OpenID Connect Discovery를 사용한 인증을 위한 것입니다.
OpenAPI 사양에서 정의한 핵심 원칙은 두 단계 과정입니다:
- 정의: API가 사용할 수 있는 모든 잠재적인 보안 스키마는 OpenAPI 문서의
components/securitySchemes섹션 내에서 전역적으로 정의됩니다. 각 스키마는 이름을 부여받고type에 따라 구성됩니다(예:type: http의 경우scheme: basic를 지정하거나type: apiKey의 경우in: header및name: X-API-Key를 정의합니다). - 적용: 정의된 후, 이러한 명명된 스키마는 전체 API(전역적으로) 또는
security키워드를 사용하여 특정 작업에 적용됩니다. 이 키워드는 접근을 위해 어떤 정의된 스키마가 필요한지를 지정하며, 잠재적으로 필요한 OAuth 2.0 범위를 포함할 수 있습니다.
이 접근 방식은 인증 방법(스키마)의 정의를 적용 및 특정 자격 증명과 분리하여 API 정의에서 일관성, 재사용성 및 명확성을 촉진합니다. Apidog의 보안 스키마 기능은 이 표준을 채택하여 강력한 사양 준수 보안 관리를 개발 작업 흐름에 직접 통합합니다.
ApiDog에서 보안 스키마 기능을 활용해야 하는 이유는 무엇인가요?
ApiDog에서 보안 스키마를 구현하는 것은 각 요청이나 엔드포인트를 개별적으로 인증을 수동으로 구성하는 데 비해 상당한 이점을 제공합니다. 이는 작업 흐름을 OpenAPI 사양의 모범 사례와 일치시키고 개별 개발자 및 팀에 실질적인 이점을 제공합니다:
- 한 번 정의하고 everywhere 재사용: 이것이 가장 중요한 이점입니다. 보안 스키마(예: 베어러 토큰 인증)를 한 번 만들 수 있습니다. 이후 몇 번의 클릭만으로 이 스키마를 수십 개 또는 수백 개의 엔드포인트나 전체 폴더에 적용할 수 있습니다. 이는 반복적인 설정을 크게 줄이고 일관성을 보장합니다.
- 명확한 관심사의 분리: 보안 스키마는 인증 방법 정의(템플릿, 예: "X-API-Key라는 이름의 헤더에서 API 키 사용")를 실제 자격 증명 값(특정 키 문자열)과 깔끔하게 분리합니다. 이는 유지 관리를 훨씬 쉽게 합니다. 인증 방법이 변경되면(예: 헤더 이름) 한 곳에서만 스키마를 업데이트하면 됩니다. 자격 증명은 별도로 관리할 수 있어, 환경별로 관리하며 기본 스키마 정의를 변경하지 않고도 사용할 수 있습니다.
- 향상된 보안 및 유출 감소: 스키마가 값과 분리되어 있기 때문에, Apidog 내에서 디버깅을 위해 설정된 기본 자격 증명은 자동으로 노출되거나 게시된 온라인 문서에서 테스트할 때 사용되지 않습니다. 문서에서 디버깅하는 사용자는 자격 증명을 수동으로 입력해야 하며, 공유 문서에서 중요한 키나 토큰의 우발적인 유출을 방지합니다.
- 간소화된 협업: 팀은 매우 큰 이점을 누립니다. 공유되고 중앙에서 관리되는 보안 스키마 라이브러리는 모든 사람이 프로젝트 전반에서 동일한 승인된 인증 방법을 일관되게 사용하도록 보장하여 구성 오류를 줄이고 보안 관행을 표준화합니다.
- 자동 상속: 보안 스키마를 폴더에 적용하면 해당 폴더 내의 모든 엔드포인트가 명시적으로 재정의되지 않는 한 설정을 자동으로 상속합니다. 이 계층적 접근 방식은 섹션 전체에 걸쳐 공통 보안 요구 사항이 있는 대규모 API에 대한 구성을 간소화합니다.
- 완전한 OpenAPI 준수: Apidog의 보안 스키마 기능을 사용함으로써 API 정의는 OpenAPI Specification 표준에 완전히 준수되어 상호 운용성 및 정확한 문서 생성을 보장합니다.
- Apidog 작업 흐름과의 통합: Apidog의 보안 스키마는 스프린트 브랜치, 버전 관리 및 변경 기록과 같은 핵심 기능과 통합되어 있습니다. 즉, 기능 변경과 함께 API 보안의 발전을 관리하고 수정 사항을 추적하며 기능 브랜치 내에서 안전하게 작업할 수 있습니다.
ApiDog에서의 보안 스키마 채택은 단순히 사양을 따르는 것이 아니라 API 인증 관리에 더 견고하고 효율적이며 안전하고 유지 관리가 용이한 접근 방식을 구현하는 것입니다.
ApiDog에서 보안 스키마를 생성하는 방법
ApiDog은 보안 스키마를 정의하고 구성하는 것을 직관적으로 만들며, OpenAPI 사양에서 개 outlines한 개념과 밀접하게 정렬됩니다. 이러한 재사용 가능한 템플릿을 수동으로 만들거나 기존 OpenAPI 문서를 가져올 때 자동 생성 기능을 활용할 수 있습니다.
방법 1: 수동으로 보안 스키마 생성
1. 탐색: ApiDog 프로젝트에서 왼쪽 사이드바의 Components 섹션으로 이동하고 Security Schemes을 선택합니다.
2. 새 스키마: + New Security Scheme 버튼을 클릭합니다.
3. 유형 선택: Apidog의 광범위한 목록에서 정의해야 하는 인증 유형을 선택합니다. 이는 핵심 OAS 유형을 반영하고 확장한 것입니다:
- API 키 (헤더, 쿼리, 쿠키)
- 베어러 토큰 (
Authorization: Bearer ...) - JWT (JSON 웹 토큰 특정)
- 기본 인증 (사용자 이름/비밀번호)
- 다이제스트 인증
- OAuth 2.0 (여러 그랜트 유형 지원)
- 기타 옵션으로 OAuth 1.0, Hawk, AWS Signature, Kerberos, NTLM, Akamai EdgeGrid 또는 사용자 정의.
4. 구성: 선택한 유형에 따라 필요한 세부 정보를 입력합니다. 여기에는:
- 이름: 스키마에 대한 설명적 이름(예:
MainApiKeyHeader,PetStoreOAuth)입니다. - 유형별 설정:
API Key의 경우In(헤더, 쿼리) 및Name(헤더/쿼리 이름)을 지정합니다.OAuth 2.0에 대해서는 그랜트 유형, URL(인증, 토큰, 새로 고침)을 구성하고 사용할 수 있는 범위를 정의합니다.
5. 저장: Save를 클릭합니다. 이제 재사용 가능한 보안 스키마를 사용할 수 있습니다.
고급 OAS 구성:
스키마 편집기 내에서 Advanced Configuration를 클릭하면 OpenAPI 사양에 부합하는 기본 JSON 또는 YAML 표현을 직접 보고 편집할 수 있습니다. 이는 필요할 경우 더 복잡한 구성을 세밀하게 조정하거나 정의할 수 있게 합니다.
방법 2: OAS를 통해 가져오기
이미 components/securitySchemes에 정의가 포함된 OpenAPI 파일(.json 또는 .yaml)을 가져오면 Apidog은 이를 자동으로 파싱하여 프로젝트의 구성 요소 라이브러리에 해당하는 보안 스키마를 생성하여 적용할 준비를 합니다.
사용자 친화적인 UI와 직접 OAS 편집 기능을 모두 제공함으로써 Apidog은 보안 스키마 기능을 효과적으로 사용하는 방법을 쉽게 만듭니다. 이는 OpenAPI 사양에 대한 친숙함 여부에 관계없이 이루어집니다.
ApiDog 작업 흐름에서 보안 스키마 활용하기
ApiDog의 구성 요소 라이브러리에서 보안 스키마를 정의하면, 이들을 엔드포인트에 대한 접근을 제어하는 데 적용하는 것은 간단하고 유연합니다. 재사용성 및 표준화의 힘이 여기서 진정으로 빛을 발합니다.
보안 스키마 적용:
두 가지 수준에서 보안 스키마를 적용할 수 있습니다:
폴더 수준:
- API 구조 내에서 폴더를 선택합니다.
- 오른쪽 패널의
Auth탭으로 이동합니다. - 인증 유형으로
Security Scheme를 선택합니다.
- 이전에 생성한 드롭다운 목록에서 원하는 스키마를 선택합니다.
- OAuth 2.0을 적용하는 경우 이 폴더 내의 엔드포인트에 대한 기본 요구 범위를 선택할 수 있습니다.
장점: 이 폴더 내의 모든 엔드포인트와 하위 폴더는 명시적으로 재정의되지 않는 한 이 보안 스키마를 자동으로 상속합니다. 이는 균일한 인증 요구 사항이 있는 API의 섹션에 적합합니다.
엔드포인트 수준:
- 특정 엔드포인트를 선택합니다.
Edit탭으로 이동하여Request섹션을 찾고 그 내에서Auth탭을 선택합니다.- 유형으로
Security Scheme를 선택합니다.
- 원하는 스키마를 선택합니다.
- OAuth 2.0의 경우 특정 작업에 필요한 범위를 정확하게 정의합니다.
장점: 엔드포인트 수준의 설정은 부모 폴더에서 상속된 모든 설정을 재정의하므로 고유한 보안 요구 사항이 있는 작업에 대한 세부 제어를 가능하게 합니다.
인증 값 관리:
보안 스키마는 방법을 정의하고 값을 정의하지 않는다는 점을 기억하세요. 디버깅할 때:
- 기본 인증 값: 개발 및 테스트 중에 편리함을 위해 ApiDog 내에서 폴더 또는 엔드포인트의
Auth설정에 대한 기본 자격 증명 값을 설정할 수 있습니다(예: 테스트 API 키를 입력하거나 기본 OAuth 2.0 토큰을 생성). 이러한 기본값은 해당 엔드포인트에 상속된 경우 Apidog에서 "Send"를 클릭할 때 자동으로 사용됩니다.
- 상속 vs. 사용자 지정: 디버깅할 때 엔드포인트의
Run탭Auth섹션은 값이 부모로부터 상속되는지 여부 또는 해당 특정 실행에 대해 수동으로 설정된 값인지 보여줍니다. 상속된 기본값을 사용하거나 단일 요청을 위해 임시로 재정의할 수 있습니다.
- 온라인 문서 디버깅: 앞서 언급했듯이, Apidog 내에서 설정된 기본값은 온라인 문서에서 디버깅할 때 자동으로 채워지지 않습니다. 사용자는 보안을 위해 "Try it" 패널의
Auth섹션에 자격 증명을 수동으로 입력해야 합니다.
ApiDog에서 보안 스키마 기능을 사용하는 방법을 마스터함으로써, OpenAPI 사양의 모범 사례를 활용하여 더 조직적이고 안전하며 유지 관리가 용이하고 협력적인 API 개발 환경을 조성할 수 있습니다.
결론: Apidog의 보안 스키마로 API 보안을 강화하세요
효과적으로 API 보안을 관리하는 것은 현대 소프트웨어 개발에서 협상할 수 없는 일입니다. Apidog의 보안 스키마는 OpenAPI 사양의 모범 사례와 직접적으로 일치하는 강력하고 표준화된 효율적인 솔루션을 제공합니다. 보안 스키마가 무엇인지 – API 키, 베어러 토큰, 기본 인증 및 OAuth 2.0과 같은 인증 방법을 정의하는 재사용 가능한 템플릿 –를 이해함으로써, 개발자는 오류가 발생하기 쉽고 반복적인 엔드포인트 수준 구성에서 벗어날 수 있습니다.