Principales considérations et limites Stratégie d'autorisation Spécification du schéma OpenAPI

Cibles du schéma OpenAPI

OpenAPI (anciennement Swagger) est une norme largement utilisée pour décrire les API RESTful. Gateway prend en charge les spécifications OpenAPI 3.0 pour définir les cibles d'API.

Les cibles OpenAPI connectent votre passerelle aux API REST définies à l'aide des spécifications OpenAPI. La passerelle traduit les requêtes MCP entrantes en requêtes HTTP destinées à ces API et gère le formatage des réponses.

Passez en revue les principales considérations et limites, y compris la prise en charge des fonctionnalités, pour vous aider à décider si une cible OpenAPI est applicable à votre cas d'utilisation. Si c'est le cas, vous pouvez créer un schéma conforme aux spécifications, puis configurer des autorisations pour que la passerelle puisse accéder à la cible. Choisissez une rubrique pour en savoir plus :

Principales considérations et limites

Important

La spécification OpenAPI doit inclure des operationId champs pour toutes les opérations que vous souhaitez exposer en tant qu'outils. L'OperationID est utilisé comme nom d'outil dans l'interface MCP.

Lorsque vous utilisez des cibles OpenAPI, tenez compte des exigences et limites suivantes :

Les versions 3.0 et 3.1 d'OpenAPI sont prises en charge (Swagger 2.0 n'est pas pris en charge)
Le fichier OpenAPI doit être exempt d'erreurs sémantiques
L'attribut de serveur doit avoir une URL valide du point de terminaison réel
Seul application/json le type de contenu est entièrement pris en charge
Les fonctionnalités de schéma complexes telles que OneOf, AnyOf et AllOf ne sont pas prises en charge
Les sérialiseurs de paramètres de chemin et les sérialiseurs de paramètres pour les paramètres de requête, d'en-tête et de cookie ne sont pas pris en charge
Chaque LLM aura des ToolSpec contraintes. Si les APIs/properties/object noms d'OpenAPI ne sont pas conformes à ToolSpec ceux des LLM en aval respectifs, le plan de données échouera. Les erreurs courantes sont le nom de la propriété dépassant la longueur autorisée ou le nom contenant un caractère non pris en charge.

Pour de meilleurs résultats avec les cibles OpenAPI :

Incluez toujours l'OperationID dans toutes les opérations
Utilisez des structures de paramètres simples au lieu d'une sérialisation complexe
Implémenter l'authentification et l'autorisation en dehors de la spécification
N'utilisez que les types de supports pris en charge pour une compatibilité maximale

Meilleures pratiques de sécurité pour les paramètres d'URL

Avertissement

Lorsque vous définissez des URL de serveur dans vos spécifications OpenAPI, évitez d'utiliser des modèles de paramètres d'URL trop permissifs qui pourraient exposer votre passerelle à des risques de sécurité.

Les paramètres d'URL dans les définitions de serveurs OpenAPI permettent une configuration dynamique des points de terminaison. Cependant, certains modèles peuvent introduire des failles de sécurité s'ils ne sont pas correctement limités. En particulier, évitez d'utiliser des modèles de domaine entièrement dynamiques tels que :

https://{yourDomain}/- Permet une substitution de domaine arbitraire
https://{subdomain}.{env}.{domain}.com- Plusieurs espaces réservés sans contraintes
https://{host}/api/- Paramètre hôte illimité

Ces modèles peuvent potentiellement être exploités pour :

Rediriger les demandes vers des terminaux non intentionnels ou malveillants
Accès aux ressources du réseau interne (Server-Side Request Forgery)
Exfiltrez des informations d'identification ou des données sensibles

Pratiques recommandées :

Utilisez des URL statiques complètes dans la mesure du possible : https://api.example.com/v1
Limitez les paramètres aux sous-domaines de votre domaine contrôlé et implémentez la validation dans votre application
Évitez d'utiliser des paramètres qui autorisent une substitution arbitraire de domaine ou d'hôte
Implémentez une validation supplémentaire dans votre API pour vérifier que les valeurs des paramètres d'exécution correspondent aux modèles attendus

AgentCore Gateway valide automatiquement les paramètres de région et bloque les requêtes vers des plages d'adresses IP privées.

Exemple de configuration d'URL de serveur sécurisé :


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

Si des paramètres dynamiques sont nécessaires, utilisez des domaines complets avec un minimum d'espaces réservés et de restrictions d'énumération :


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

Cette approche limite les paramètres d'URL à des sous-domaines spécifiques de votre domaine contrôlé tout en préservant la flexibilité pour les déploiements multi-locataires. L'utilisation de restrictions d'énumération empêche les valeurs arbitraires et contribue à la protection contre les attaques SSRF en limitant les paramètres à des valeurs prédéfinies et sûres. En outre, validez toujours les valeurs des locataires dans la logique de votre application.

Si vous envisagez d'utiliser des cibles de schéma OpenAPI avec AgentCore Gateway, consultez le tableau de prise en charge des fonctionnalités suivant.

Prise en charge des fonctionnalités OpenAPI

Le tableau suivant décrit les fonctionnalités OpenAPI qui sont prises en charge et non prises en charge par Gateway :

Fonctionnalités prises en charge	Fonctions non prises en charge
Définitions de schéma Types de données de base (chaîne, nombre, entier, booléen, tableau, objet) Validation des champs requise Structures d'objets imbriqués Définitions de tableaux avec spécifications des éléments	Composition du schéma Spécifications OneOf Spécifications AnyOf Spécifications AllOf
Méthodes HTTP Méthodes HTTP standard (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)	Schémas de sécurité Schémas de sécurité au niveau de la spécification OpenAPI (l'authentification doit être configurée à l'aide de la configuration d'autorisation sortante de la passerelle)
Types de médias application/json application/xml multipart/form -data -www-form-urlencoded application/x	Types de médias Types de médias personnalisés en dehors de la liste prise en charge Types de médias binaires
Paramètres de chemin Définitions de paramètres de chemin simples (exemple : /users/ {userId})	Sérialisation des paramètres Sérialiseurs de paramètres de chemin complexes (Exemple :`/users { ;id\*} { ?metadata}`) Tableaux de paramètres de requête avec sérialisation complexe Sérialiseurs de paramètres d'en-tête Sérialiseurs de paramètres de cookies
Paramètres de requête Définitions de base des paramètres de requête Types de chaînes, de nombres et de booléens simples	Callbacks et Webhooks Opérations de rappel Définitions des Webhooks
Request/Response Corps Corps de requête et de réponse JSON Corps de requête et de réponse XML Codes d'état HTTP standard (200, 201, 400, 404, 500, etc.)	Liens Liens entre les opérations

Stratégie d'autorisation

Les types d'autorisation sortante suivants sont pris en charge pour les cibles OpenAPI :

Aucune autorisation : la passerelle invoque la cible OpenAPI sans autorisation préconfigurée. Cette approche n'est pas recommandée.
OAuth — La passerelle prend en charge à la fois l'OAuth à deux étapes (type d'autorisation des informations d'identification du client) et l'OAuth à trois étapes (type d'autorisation de code d'autorisation). Vous configurez le fournisseur d'autorisation dans Amazon Bedrock AgentCore Identity dans le même compte et la même région que la passerelle.
Clé API : la passerelle utilise un fournisseur d'informations d'identification de clé API pour s'authentifier auprès de la cible OpenAPI. Vous configurez le fournisseur de clés d'API dans Amazon Bedrock AgentCore Identity dans le même compte et la même région que la passerelle.
IAM (AWS Signature Version 4 (Sig V4)) — La passerelle signe les demandes adressées à la cible OpenAPI à l'aide de SigV4 avec les informations d'identification du rôle de service de passerelle. Vous configurez un IamCredentialProvider avec un nom de service obligatoire pour la signature SIGv4 et une région facultative (la valeur par défaut est la région de passerelle).

Important

L'autorisation sortante IAM (Sigv4) nécessite que la cible OpenAPI soit hébergée derrière un AWS service qui prend en charge nativement l'authentification IAM. La passerelle signe les demandes sortantes avec SIGv4 mais ne modifie pas la configuration d'authentification sur la cible. Le service cible doit être en mesure de vérifier les signatures SIGv4.

Les AWS services suivants prennent en charge l'authentification IAM de manière native et sont compatibles avec l'autorisation sortante IAM pour les cibles OpenAPI :

Amazon API Gateway
URL des fonctions Lambda
Passerelle Amazon Bedrock AgentCore

Les services qui ne vérifient pas de manière native les signatures Sigv4, tels que Application Load Balancer ou les points de terminaison Amazon EC2 directs, ne sont pas compatibles avec l'autorisation sortante IAM. Si votre cible OpenAPI est hébergée derrière l'un de ces services, utilisez plutôt OAuth ou l'autorisation par clé API.

Pour plus d'informations sur la configuration de l'autorisation sortante, voir Configurer l'autorisation sortante pour votre passerelle.

Spécification du schéma OpenAPI

La spécification OpenAPI définit l'API REST que votre passerelle exposera. Reportez-vous aux ressources suivantes lors de la configuration de votre spécification OpenAPI :

Pour plus d'informations sur le format de la spécification OpenAPI, consultez la section Spécification OpenAPI.
Pour plus d'informations sur les fonctionnalités prises en charge et non prises en charge lors de l'utilisation d'une spécification OpenAPI avec AgentCore Gateway, consultez le tableau dans la rubrique Prise en charge des fonctionnalités OpenAPI. Respectez ces exigences pour éviter les erreurs lors de la création et de l'invocation de la cible.

Après avoir défini votre schéma OpenAPI, vous pouvez effectuer l'une des opérations suivantes :

Téléchargez-le dans un compartiment Amazon S3 et faites référence à l'emplacement S3 lorsque vous ajoutez la cible à votre passerelle.
Collez la définition en ligne lorsque vous ajoutez la cible à votre passerelle.

Développez une section pour voir des exemples de spécifications OpenAPI prises en charge et non prises en charge :

Voici un exemple de spécification OpenAPI prise en charge

Exemple de spécification OpenAPI prise en charge :


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

Voici un autre exemple de spécification OpenAPI prise en charge.


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

Voici un exemple de schéma non pris en charge avec OneOf :


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

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Étapes de la passerelle API

Modèles Smithy