View a markdown version of this page

Objetivos del esquema OpenAPI - Amazon Bedrock AgentCore
Consideraciones y limitaciones claveEstrategia de autorizaciónEspecificación del esquema OpenAPI

Objetivos del esquema OpenAPI

OpenAPI (anteriormente conocido como Swagger) es un estándar ampliamente utilizado para describir las API RESTful. Gateway admite las especificaciones de OpenAPI 3.0 para definir los objetivos de las API.

Los objetivos de OpenAPI conectan su puerta de enlace con las API REST definidas mediante las especificaciones de OpenAPI. El Gateway traduce las solicitudes MCP entrantes en solicitudes HTTP para estas API y gestiona el formato de las respuestas.

Revisa las consideraciones y limitaciones clave, incluida la compatibilidad con las funciones, para ayudarte a decidir si un objetivo de OpenAPI es aplicable a tu caso de uso. Si es así, puede crear un esquema que siga las especificaciones y, a continuación, configurar los permisos para que la puerta de enlace pueda acceder al destino. Elija un tema para obtener más información:

Consideraciones y limitaciones clave

importante

La especificación OpenAPI debe incluir operationId campos para todas las operaciones que desee exponer como herramientas. El OperationID se utiliza como nombre de la herramienta en la interfaz MCP.

Cuando utilice objetivos de OpenAPI, tenga en cuenta los siguientes requisitos y limitaciones:

  • Se admiten las versiones 3.0 y 3.1 de OpenAPI (no se admite Swagger 2.0)

  • El archivo OpenAPI debe estar libre de errores semánticos

  • El atributo del servidor debe tener una URL válida del punto final real

  • Solo application/json el tipo de contenido es totalmente compatible

  • No se admiten funciones de esquemas complejos como OneOf, anyOf y AllOf

  • No se admiten los serializadores de parámetros de ruta ni los serializadores de parámetros para los parámetros de consulta, encabezado y cookie

  • Cada LLM tendrá restricciones. ToolSpec Si OpenAPI tiene APIs/properties/object nombres que no cumplen con ToolSpec los respectivos LLM descendentes, el plano de datos fallará. Los errores más comunes son que el nombre de la propiedad supere la longitud permitida o que el nombre contenga caracteres no admitidos.

Para obtener los mejores resultados con los objetivos de OpenAPI:

  • Incluya siempre el OperationID en todas las operaciones

  • Utilice estructuras de parámetros simples en lugar de serializaciones complejas

  • Implemente la autenticación y la autorización fuera de la especificación

  • Utilice únicamente los tipos de medios compatibles para lograr la máxima compatibilidad

Prácticas recomendadas de seguridad para los parámetros de URL

aviso

Al definir las URL del servidor en las especificaciones de OpenAPI, evite utilizar patrones de parámetros de URL demasiado permisivos que puedan exponer su puerta de enlace a riesgos de seguridad.

Los parámetros de URL en las definiciones de servidor OpenAPI permiten una configuración dinámica de puntos finales. Sin embargo, ciertos patrones pueden introducir vulnerabilidades de seguridad si no se limitan adecuadamente. En concreto, evite utilizar patrones de dominio totalmente dinámicos, como:

  • https://{yourDomain}/- Permite la sustitución arbitraria de dominios

  • https://{subdomain}.{env}.{domain}.com- Múltiples marcadores de posición sin restricciones

  • https://{host}/api/- Parámetro de host sin restricciones

Estos patrones pueden explotarse potencialmente para:

  • Redirigir las solicitudes a puntos finales no deseados o maliciosos

  • Acceda a los recursos de la red interna (Server-Side solicitud de falsificación)

  • Exfiltre credenciales o datos confidenciales

Prácticas recomendadas:

  • Utilice URL estáticas y totalmente cualificadas siempre que sea posible: https://api.example.com/v1

  • Limite los parámetros a los subdominios de su dominio controlado e implemente la validación en su aplicación

  • Evite utilizar parámetros que permitan la sustitución arbitraria de dominios o hosts

  • Implemente una validación adicional en su API para verificar que los valores de los parámetros de tiempo de ejecución coincidan con los patrones esperados

AgentCore Gateway valida automáticamente los parámetros de la región y bloquea las solicitudes a los rangos de IP privadas.

Ejemplo de configuración de URL de servidor seguro:

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

Si se necesitan parámetros dinámicos, utilice dominios totalmente cualificados con un mínimo de marcadores de posición y restricciones de enumeración:

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

Este enfoque restringe los parámetros de URL a subdominios específicos dentro del dominio controlado y, al mismo tiempo, mantiene la flexibilidad para las implementaciones con varios inquilinos. El uso de restricciones de enumeración evita los valores arbitrarios y ayuda a proteger contra los ataques de la SSRF al limitar los parámetros a valores seguros y predefinidos. Además, valide siempre los valores de los inquilinos en la lógica de su aplicación.

Si desea utilizar los objetivos del esquema OpenAPI con AgentCore Gateway, consulte la siguiente tabla de compatibilidad de funciones.

Soporte de funciones OpenAPI

En la siguiente tabla se describen las funciones de OpenAPI compatibles y no compatibles con Gateway:

Características admitidas Características no admitidas

Definiciones de esquema Tipos de datos básicos (cadena, número, entero, booleano, matriz, objeto) Validación de campo obligatoria Estructuras de objetos anidados Definiciones de matriz con especificaciones de elementos

Composición del esquema Una de las especificaciones Cualquiera de las especificaciones Todas las especificaciones

Métodos HTTP Métodos HTTP estándar (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)

Esquemas de seguridad Esquemas de seguridad a nivel de especificación de OpenAPI (la autenticación debe configurarse mediante la configuración de autorización de salida de la pasarela)

Tipos application/json application/xml multipart/form de medios: data -www-form-urlencoded application/x

Tipos de medios: tipos de medios personalizados más allá de la lista admitida: tipos de medios binarios

Parámetros de ruta Definiciones simples de parámetros de ruta (ejemplo: /users/ {userId})

Serialización de parámetros Serializadores de parámetros de rutas complejas (Ejemplo:/users { ;id\*} { ?metadata}) Consulte matrices de parámetros con serialización compleja Serializadores de parámetros de cabecera Serializadores de parámetros de cookies

Parámetros de consulta Definiciones de parámetros de consulta básicos de tipos simples de cadenas, números y booleanos

Callbacks y Webhooks Operaciones de callback Definiciones de Webhook

Request/Response Cuerpos de solicitud y respuesta JSON Cuerpos de solicitud y respuesta XML Códigos de estado HTTP estándar (200, 201, 400, 404, 500, etc.)

Vínculos: enlaces entre operaciones

Estrategia de autorización

Los destinos de OpenAPI admiten los siguientes tipos de autorización de salida:

  • Sin autorización: la puerta de enlace invoca el destino de OpenAPI sin una autorización preconfigurada. No se recomienda este enfoque.

  • OAuth: la puerta de enlace admite OAuth de dos vías (tipo de concesión de credenciales de cliente) y OAuth de tres vías (tipo de concesión de código de autorización). El proveedor de autorización se configura en Amazon Bedrock AgentCore Identity en la misma cuenta y región que la puerta de enlace.

  • Clave de API: la puerta de enlace utiliza un proveedor de credenciales de clave de API para autenticarse con el objetivo de OpenAPI. El proveedor de claves de API en Amazon Bedrock AgentCore Identity se configura en la misma cuenta y región que la puerta de enlace.

  • IAM (AWS Signature Version 4 (Sig V4)): la puerta de enlace firma las solicitudes al objetivo de OpenAPI mediante SigV4 con las credenciales del rol de servicio de puerta de enlace. Se configura una IamCredentialProvider con un nombre de servicio obligatorio para la firma de SigV4 y una región opcional (el valor predeterminado es la región de la puerta de enlace).

importante

La autorización de salida de IAM (SiGv4) requiere que el destino de OpenAPI esté alojado detrás de un AWS servicio que admita de forma nativa la autenticación de IAM. La puerta de enlace firma las solicitudes salientes con SiGv4, pero no modifica la configuración de autenticación en el destino. El servicio de destino debe poder verificar las firmas de SigV4.

Los siguientes AWS servicios admiten de forma nativa la autenticación de IAM y son compatibles con la autorización de salida de IAM para los destinos de OpenAPI:

  • Amazon API Gateway

  • URL de funciones Lambda

  • Amazon Bedrock Gateway AgentCore

Los servicios que no verifican de forma nativa las firmas SiGv4, como Application Load Balancer o los puntos de enlace directos de Amazon EC2, no son compatibles con la autorización saliente de IAM. Si tu objetivo de OpenAPI está alojado detrás de uno de estos servicios, usa OAuth o la autorización de clave API en su lugar.

Para obtener más información sobre cómo configurar la autorización de salida, consulta Cómo configurar la autorización de salida para tu puerta de enlace.

Especificación del esquema OpenAPI

La especificación OpenAPI define la API REST que expondrá su Gateway. Consulte los siguientes recursos al configurar su especificación de OpenAPI:

Tras definir el esquema de OpenAPI, puede realizar una de las siguientes acciones:

  • Cárguelo en un bucket de Amazon S3 y consulte la ubicación de S3 cuando añada el objetivo a su puerta de enlace.

  • Pegue la definición en línea cuando añada el objetivo a su puerta de enlace.

Amplíe una sección para ver ejemplos de especificaciones de OpenAPI compatibles y no compatibles:

A continuación se muestra un ejemplo de una especificación de OpenAPI compatible

Ejemplo de una especificación de OpenAPI compatible:

{
  "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"
          }
        }
      }
    }
  }
}

A continuación se muestra otro ejemplo de una especificación de OpenAPI compatible.

{
  "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"
          }
        }
      }
    }
  }
}

A continuación, se muestra un ejemplo de un esquema no compatible con OneOf:

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