OpenAPI 3 전역 보안 설정에 정의되지 않은 scope를 사용하는 경우

설명

OpenAPI 3.0의 전역 security에서 OAuth2 스코프를 요구할 때는 해당 components.securitySchemes의 flows에 스코프가 정의되어 있어야 합니다. 정의되지 않은 이름을 참조하면 요구하는 권한이 불명확해집니다.

잠재적 영향

API 사용자가 잘못된 스코프를 요청하거나 문서 검증과 클라이언트 생성 과정에서 오류가 발생할 수 있습니다.

해결 방법

전역 요구사항의 스코프를 해당 OAuth2 흐름의 scopes 및 인증 서버 설정과 맞추십시오. 잘못된 참조를 수정하되, 실제로 필요한 권한은 정의에 추가해 유지하십시오. OpenID Connect는 제공자의 스코프를 사용하므로 OAuth2 흐름의 정의와 구분하십시오.

예시

예시는 불필요한 error:api 참조를 제거합니다. 필요한 권한이 정의에서 빠진 경우에는 스코프 정의를 추가해야 합니다.

변경 전

json

{
  "openapi": "3.0.0",
  "security": [
    {
      "oAuth2AuthCode": [
        "read:api",
        "error:api"
      ]
    }
  ],
  "components": {
    "securitySchemes": {
      "oAuth2AuthCode": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://api.example.com/oauth/authorize",
            "tokenUrl": "https://api.example.com/oauth/token",
            "scopes": {
              "read:api": "read your apis"
            }
          }
        }
      }
    }
  }
}

변경 후

json

{
  "openapi": "3.0.0",
  "security": [
    {
      "oAuth2AuthCode": [
        "read:api"
      ]
    }
  ],
  "components": {
    "securitySchemes": {
      "oAuth2AuthCode": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://api.example.com/oauth/authorize",
            "tokenUrl": "https://api.example.com/oauth/token",
            "scopes": {
              "read:api": "read your apis"
            }
          }
        }
      }
    }
  }
}