Consideraciones y limitaciones clave Estrategia de autorización Especificación del esquema de OpenAPI

Objetivos del esquema OpenAPI

OpenAPI (antes conocido como Swagger) es un estándar muy 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 a las API REST definidas mediante las especificaciones de OpenAPI. El Gateway traduce las solicitudes MCP entrantes en solicitudes HTTP a estas API y gestiona el formato de las respuestas.

Revisa las principales consideraciones y limitaciones, incluida la compatibilidad de funciones, para ayudarte a decidir si un objetivo de OpenAPI es aplicable a tu caso de uso. Si lo es, 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 de OpenAPI debe incluir operationId campos para todas las operaciones que desee exponer como herramientas. El OperationID se usa 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 de servidor debe tener una URL válida del punto final real
Solo se admite completamente el tipo de application/json contenido
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 los ToolSpec de los respectivos LLM posteriores, 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 OperationID en todas las operaciones
Utilice estructuras de parámetros simples en lugar de una serialización compleja
Implemente la autenticación y la autorización fuera de la especificación
Utilice únicamente los tipos de medios compatibles para obtener la máxima compatibilidad

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

aviso

Al definir las URL de los servidores en las especificaciones de OpenAPI, evite utilizar patrones de parámetros de URL demasiado permisivos, ya que podrían exponer su puerta de enlace a riesgos de seguridad.

Los parámetros de URL en las definiciones de los servidores OpenAPI permiten la configuración dinámica de los puntos finales. Sin embargo, ciertos patrones pueden introducir vulnerabilidades de seguridad si no se restringen adecuadamente. En concreto, evite usar 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 aprovecharse potencialmente para:

Redirigir las solicitudes a puntos finales no deseados o malintencionados
Acceda a los recursos de la red interna (falsificación de Server-Side solicitudes)
Exfiltre credenciales o datos confidenciales

Prácticas recomendadas:

Utilice URL estáticas 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 el uso de 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 rangos de IP privados.

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 de tu dominio controlado, a la vez que 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.

Al considerar la posibilidad de utilizar los objetivos del esquema de OpenAPI con AgentCore Gateway, consulte la siguiente tabla de compatibilidad de funciones.

Soporte de funciones de 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 campos requerida Estructuras de objetos anidados Definiciones de matrices con especificaciones de elementos	Composición del esquema Especificaciones 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 saliente del Gateway)
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 ruta complejos (ejemplo:`/users { ;id\*} { ?metadata}`), matrices de parámetros de consulta con serialización compleja, serializadores de parámetros de encabezado, serializadores de parámetros de cookies
Parámetros de consulta: definiciones básicas de parámetros de consulta: tipos simples de cadenas, números y booleanos	Devoluciones de llamadas y webhooks Operaciones de devolución de llamadas Definiciones de webhooks
Request/Response Cuerpos 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 objetivos de OpenAPI admiten los siguientes tipos de autorización saliente:

Sin autorización: la puerta de enlace invoca el objetivo de OpenAPI sin una autorización preconfigurada. No se recomienda este enfoque.
OAuth: la puerta de enlace admite tanto el OAuth bilateral (tipo de concesión de credenciales de cliente) como el OAuth triple (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 claves de API para autenticarse con el objetivo de OpenAPI. El proveedor de claves de API se configura en Amazon Bedrock AgentCore Identity en la misma cuenta y región que la puerta de enlace.
IAM (AWS Signature, versión 4 (Sig V4)): la puerta de enlace firma las solicitudes dirigidas al objetivo de OpenAPI mediante SigV4 con las credenciales del rol de servicio de puerta de enlace. La configuras IamCredentialProvider con un nombre de servicio obligatorio para la firma de Sigv4 y una región opcional (de forma predeterminada, la región de la puerta de enlace).

importante

La autorización saliente de IAM (SigV4) requiere que el destino de OpenAPI esté alojado en 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 del 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 saliente de IAM para los objetivos de OpenAPI:

Amazon API Gateway
URL de funciones Lambda
Amazon Bedrock Gateway AgentCore

Los servicios que no verifican de forma nativa las firmas de SIGv4, como el balanceador de carga de aplicaciones o los puntos de enlace directos de Amazon EC2, no son compatibles con la autorización de salida de IAM. Si su destino de OpenAPI está alojado en uno de estos servicios, utilice en su lugar la autorización mediante claves de API o OAuth.

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

Especificación del esquema de OpenAPI

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

Para obtener información sobre el formato de la especificación de OpenAPI, consulte la especificación de OpenAPI.
Para obtener información sobre las funciones compatibles y no compatibles al utilizar una especificación de OpenAPI con AgentCore Gateway, consulte la tabla de compatibilidad de funciones de OpenAPI. Soporte de funciones de OpenAPI Cumpla estos requisitos para evitar errores durante la creación y la invocación de los objetivos.

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 destino a su puerta de enlace.
Pegue la definición en línea cuando añada el destino 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"}
  ]
}

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Etapas de API Gateway

Modelos Smithy