정의되지 않은 작업별 보안 스킴 참조

설명

OpenAPI 3.0 작업의 security에 사용한 이름은 components.securitySchemes에 정의되어 있어야 합니다. 작업별 security는 전역 보안 요구 사항을 재정의하므로 실제로 필요한 인증 방식을 정확히 연결해야 합니다.

잠재적 영향

특정 작업의 인증 요구 사항을 도구나 API 사용자가 잘못 이해하여 호출이 실패할 수 있습니다. 문서 오류가 곧 서버의 인증 우회를 의미하지는 않습니다.

해결 방법

작업에서 참조하는 보안 스킴을 같은 이름으로 정의하고 인증 유형과 범위를 확인하세요. OAuth2와 OpenID Connect 외의 유형은 범위 목록을 빈 배열로 두세요. 해당 작업의 실제 인증 동작도 확인하세요.

예시

GET 작업의 petstore_auth에 대응하는 정의를 추가하는 예시입니다. 과거 implicit 흐름과 HTTP 인증 주소를 운영 권장으로 사용하지 마세요. 새 OAuth2 구성은 HTTPS와 인증 코드 흐름 및 PKCE를 검토하세요.

변경 전

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "security": [
          {
            "petstore_auth": [
              "write:pets",
              "read:pets"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "content": {
              "application/json": {
                "examples": {
                  "foo": {
                    "value": {
                      "versions": [
                        {
                          "status": "CURRENT",
                          "updated": "2011-01-21T11:33:21Z",
                          "id": "v2.0",
                          "links": [
                            {
                              "href": "http://127.0.0.1:8774/v2/",
                              "rel": "self"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

변경 후

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "security": [
          {
            "petstore_auth": [
              "write:pets",
              "read:pets"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "content": {
              "application/json": {
                "examples": {
                  "foo": {
                    "value": {
                      "versions": [
                        {
                          "status": "CURRENT",
                          "updated": "2011-01-21T11:33:21Z",
                          "id": "v2.0",
                          "links": [
                            {
                              "href": "http://127.0.0.1:8774/v2/",
                              "rel": "self"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "regularSecurity": {
        "type": "http",
        "scheme": "basic"
      },
      "petstore_auth": {
        "type": "oauth2",
        "flows": {
          "implicit": {
            "scopes": {
              "write:pets": "modify pets in your account",
              "read:pets": "read your pets"
            },
            "authorizationUrl": "http://example.org/api/oauth/dialog"
          }
        }
      }
    }
  }
}

변경 후 GET 작업의 보안 요구 사항이 정의된 petstore_auth에 연결됩니다. 스킴을 정의하는 것과 서버가 요청을 인증하는 것은 별도입니다.