View a markdown version of this page

OpenAPI 스키마 대상 - Amazon Bedrock AgentCore
주요 고려 사항 및 제한 사항권한 부여 전략OpenAPI 스키마 사양

OpenAPI 스키마 대상

OpenAPI(이전에는 Swagger라고 함)는 RESTful APIs. Gateway는 API 대상을 정의하기 위한 OpenAPI 3.0 사양을 지원합니다.

OpenAPI 대상은 게이트웨이를 OpenAPI 사양을 사용하여 정의된 REST APIs에 연결합니다. Gateway는 수신 MCP 요청을 이러한 APIs에 대한 HTTP 요청으로 변환하고 응답 형식을 처리합니다.

기능 지원을 포함한 주요 고려 사항 및 제한 사항을 검토하여 OpenAPI 대상을 사용 사례에 적용할 수 있는지 결정하는 데 도움이 됩니다. 이 경우 사양을 따르는 스키마를 생성한 다음 게이트웨이가 대상에 액세스할 수 있도록 권한을 설정할 수 있습니다. 주제 영역을 선택하여 자세히 알아보세요.

주요 고려 사항 및 제한 사항

중요

OpenAPI 사양에는 도구로 노출하려는 모든 작업에 대한 operationId 필드가 포함되어야 합니다. operationId는 MCP 인터페이스에서 도구 이름으로 사용됩니다.

OpenAPI 대상을 사용할 때는 다음 요구 사항 및 제한 사항에 유의하세요.

  • OpenAPI 버전 3.0 및 3.1이 지원됩니다(Swagger 2.0은 지원되지 않음).

  • OpenAPI 파일에는 의미 오류가 없어야 합니다.

  • 서버 속성에는 실제 엔드포인트의 유효한 URL이 있어야 합니다.

  • 애플리케이션/json 콘텐츠 유형만 완전히 지원됩니다.

  • oneOf, anyOf 및 allOf와 같은 복잡한 스키마 기능은 지원되지 않습니다.

  • 쿼리, 헤더 및 쿠키 파라미터에 대한 경로 파라미터 직렬 변환기 및 파라미터 직렬 변환기는 지원되지 않습니다.

  • 각 LLM에는 ToolSpec 제약 조건이 있습니다. OpenAPI에 해당 다운스트림 LLMs의 ToolSpec을 준수하지 않는 APIs/properties/object 이름이 있는 경우 데이터 영역이 실패합니다. 일반적인 오류는 허용된 길이를 초과하는 속성 이름 또는 지원되지 않는 문자가 포함된 이름입니다.

OpenAPI 대상에서 최상의 결과를 얻으려면:

  • 모든 작업에 항상 operationId 포함

  • 복잡한 직렬화 대신 간단한 파라미터 구조 사용

  • 사양 외부에서 인증 및 권한 부여 구현

  • 최대 호환성을 위해 지원되는 미디어 유형만 사용

URL 파라미터에 대한 보안 모범 사례

주의

OpenAPI 사양에서 서버 URLs을 정의할 때는 게이트웨이를 보안 위험에 노출시킬 수 있는 지나치게 허용적인 URL 파라미터 패턴을 사용하지 마세요.

OpenAPI 서버 정의의 URL 파라미터는 동적 엔드포인트 구성을 허용합니다. 그러나 특정 패턴이 제대로 제한되지 않으면 보안 취약성이 발생할 수 있습니다. 특히 다음과 같은 완전 동적 도메인 패턴을 사용하지 마세요.

  • https://{yourDomain}/ - 임의 도메인 대체 허용

  • https://{subdomain}.{env}.{domain}.com - 제약 없는 자리 표시자 여러 개

  • https://{host}/api/ - 무제한 호스트 파라미터

이러한 패턴은 잠재적으로 다음을 위해 악용될 수 있습니다.

  • 의도하지 않거나 악의적인 엔드포인트로 요청 리디렉션

  • 내부 네트워크 리소스에 액세스(서버 측 요청 위조)

  • 자격 증명 또는 민감한 데이터 유출

권장 사례:

  • 가능하면 정규화된 정적 URLs 사용합니다. https://api.example.com/v1

  • 파라미터를 제어된 도메인 내의 하위 도메인으로 제한하고 애플리케이션에서 검증을 구현합니다.

  • 임의의 도메인 또는 호스트 대체를 허용하는 파라미터를 사용하지 마세요.

  • API에서 추가 검증을 구현하여 런타임 파라미터 값이 예상 패턴과 일치하는지 확인합니다.

AgentCore Gateway는 리전 파라미터를 자동으로 검증하고 프라이빗 IP 범위에 대한 요청을 차단합니다.

보안 서버 URL 구성의 예:

{
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ]
}

동적 파라미터가 필요한 경우 자리 표시자 및 열거형 제한이 최소화된 정규화된 도메인을 사용합니다.

{
  "servers": [
    {
      "url": "https://{tenant}.api.example.com/v1",
      "variables": {
        "tenant": {
          "default": "default-tenant",
          "description": "Customer tenant identifier",
          "enum": ["tenant1", "tenant2", "tenant3"]
        }
      }
    }
  ]
}

이 접근 방식은 다중 테넌트 배포의 유연성을 유지하면서 URL 파라미터를 제어 도메인 내의 특정 하위 도메인으로 제한합니다. 열거형 제한을 사용하면 임의의 값을 방지하고 파라미터를 사전 정의된 안전한 값으로 제한하여 SSRF 공격으로부터 보호할 수 있습니다. 또한 애플리케이션 로직에서 테넌트 값을 항상 검증합니다.

AgentCore Gateway에서 OpenAPI 스키마 대상 사용을 고려할 때 다음 기능 지원 표를 검토하세요.

OpenAPI 기능 지원

다음 표에는 Gateway에서 지원 및 지원하지 않는 OpenAPI 기능이 요약되어 있습니다.

지원 기능 지원되지 않는 기능

스키마 정의 기본 데이터 유형(문자열, 숫자, 정수, 부울, 배열, 객체) 필수 필드 검증 중첩 객체 구조 항목 사양이 포함된 배열 정의

스키마 구성 oneOf 사양 anyOf 사양 allOf 사양

HTTP 메서드 표준 HTTP 메서드(GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)

OpenAPI 사양 수준의 보안 체계 보안 체계(게이트웨이의 아웃바운드 권한 부여 구성을 사용하여 인증을 구성해야 함)

미디어 유형 애플리케이션/json 애플리케이션/xml 멀티파트/form-data 애플리케이션/x-www-form-urlencoded

미디어 유형 지원되는 목록 바이너리 미디어 유형 이외의 사용자 지정 미디어 유형

경로 파라미터 단순 경로 파라미터 정의(예: /users/ { userId})

파라미터 직렬화 복합 경로 파라미터 직렬화기(예: /users { ;id\*} { ?metadata}) 복합 직렬화 헤더 파라미터 직렬화기를 사용하여 파라미터 배열 쿼리 쿠키 파라미터 직렬화기

쿼리 파라미터 기본 쿼리 파라미터 정의 단순 문자열, 숫자 및 부울 유형

콜백 및 Webhook 콜백 작업 Webhook 정의

요청/응답 본문 JSON 요청 및 응답 본문 XML 요청 및 응답 본문 표준 HTTP 상태 코드(200, 201, 400, 404, 500 등)

작업 간 링크

권한 부여 전략

OpenAPI 대상에는 다음과 같은 유형의 아웃바운드 권한 부여가 지원됩니다.

  • 권한 부여 없음 - 게이트웨이는 사전 구성된 권한 부여 없이 OpenAPI 대상을 호출합니다. 이 접근 방식은 권장되지 않습니다.

  • OAuth - 게이트웨이는 2각 OAuth(클라이언트 자격 증명 권한 부여 유형)와 3각 OAuth(권한 부여 코드 유형)를 모두 지원합니다. 게이트웨이와 동일한 계정 및 리전의 Amazon Bedrock AgentCore 자격 증명에서 권한 부여 공급자를 구성합니다.

  • API 키 - 게이트웨이는 API 키 자격 증명 공급자를 사용하여 OpenAPI 대상으로 인증합니다. 게이트웨이와 동일한 계정 및 리전의 Amazon Bedrock AgentCore Identity에서 API 키 공급자를 구성합니다.

  • IAM( AWS 서명 버전 4(Sig V4) ) - 게이트웨이는 게이트웨이 서비스 역할 자격 증명과 함께 SigV4를 사용하여 OpenAPI 대상에 대한 요청에 서명합니다. SigV4 서명에 IamCredentialProvider 필요한 서비스 이름과 선택적 리전(기본값은 게이트웨이 리전)으로를 구성합니다.

중요

IAM(SigV4) 아웃바운드 권한 부여를 사용하려면 기본적으로 IAM 인증을 지원하는 AWS 서비스 뒤에 OpenAPI 대상이 호스팅되어야 합니다. 게이트웨이는 SigV4를 사용하여 아웃바운드 요청에 서명하지만 대상의 인증 구성은 수정하지 않습니다. 대상 서비스는 SigV4 서명을 확인할 수 있어야 합니다.

다음 AWS 서비스는 기본적으로 IAM 인증을 지원하며 OpenAPI 대상에 대한 IAM 아웃바운드 권한 부여와 호환됩니다.

  • Amazon API Gateway

  • Lambda 함수 URLs

  • Amazon Bedrock AgentCore Gateway

Application Load Balancer 또는 직접 Amazon EC2 엔드포인트와 같이 SigV4 서명을 기본적으로 확인하지 않는 서비스는 IAM 아웃바운드 권한 부여와 호환되지 않습니다. OpenAPI 대상이 이러한 서비스 중 하나 뒤에 호스팅되는 경우 OAuth 또는 API 키 권한 부여를 대신 사용합니다.

아웃바운드 권한 부여 설정에 대한 자세한 내용은 게이트웨이에 대한 아웃바운드 권한 부여 설정을 참조하세요.

OpenAPI 스키마 사양

OpenAPI 사양은 게이트웨이가 노출할 REST API를 정의합니다. OpenAPI 사양을 설정할 때 다음 리소스를 참조하세요.

  • OpenAPI 사양의 형식에 대한 자세한 내용은 OpenAPI 사양을 참조하세요.

  • AgentCore Gateway에서 OpenAPI 사양을 사용할 때 지원되는 기능과 지원되지 않는 기능에 대한 자세한 내용은 OpenAPI 기능 지원의 표를 참조하세요. 대상 생성 및 호출 중에 오류를 방지하려면 이러한 요구 사항을 준수하세요.

OpenAPI 스키마를 정의한 후 다음 중 하나를 수행할 수 있습니다.

  • Amazon S3 버킷에 업로드하고 게이트웨이에 대상을 추가할 때 S3 위치를 참조합니다.

  • 게이트웨이에 대상을 추가할 때 정의를 인라인으로 붙여 넣습니다.

섹션을 확장하여 지원되는 OpenAPI 사양과 지원되지 않는 OpenAPI 사양의 예를 확인합니다.

다음은 지원되는 OpenAPI 사양의 예를 보여줍니다.

지원되는 OpenAPI 사양의 예:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Weather API",
    "version": "1.0.0",
    "description": "API for retrieving weather information"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ],
  "paths": {
    "/weather": {
      "get": {
        "summary": "Get current weather",
        "description": "Returns current weather information for a location",
        "operationId": "getCurrentWeather",
        "parameters": [
          {
            "name": "location",
            "in": "query",
            "description": "City name or coordinates",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "units",
            "in": "query",
            "description": "Units of measurement (metric or imperial)",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["metric", "imperial"],
              "default": "metric"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "location": {
                      "type": "string"
                    },
                    "temperature": {
                      "type": "number"
                    },
                    "conditions": {
                      "type": "string"
                    },
                    "humidity": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "404": {
            "description": "Location not found"
          }
        }
      }
    }
  }
}

다음은 지원되는 OpenAPI 사양의 또 다른 예를 보여줍니다.

{
  "openapi": "3.0.0",
  "info": {
    "title": "Search API",
    "version": "1.0.0",
    "description": "API for searching content"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ],
  "paths": {
    "/search": {
      "get": {
        "summary": "Search for content",
        "operationId": "searchContent",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "description": "Search query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "snippet": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          }
        }
      }
    }
  }
}

다음은 oneOf가 있는 지원되지 않는 스키마의 예입니다.

{
  "oneOf": [
    {"$ref": "#/components/schemas/Pencil"},
    {"$ref": "#/components/schemas/Pen"}
  ]
}