View a markdown version of this page

Cibles du schéma OpenAPI - Amazon Bedrock AgentCore
Principales considérations et limitesStratégie d'autorisationSpécification du schéma OpenAPI

Cibles du schéma OpenAPI

OpenAPI (anciennement connu sous le nom de 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 demandes 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 limitations, y compris le support des fonctionnalités, pour vous aider à décider si une cible OpenAPI est applicable à votre cas d'utilisation. Si tel est le cas, vous pouvez créer un schéma conforme aux spécifications, puis configurer les autorisations permettant à la passerelle d'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 sous forme d'outils. L'OperationID est utilisé comme nom d'outil dans l'interface MCP.

Lorsque vous utilisez des cibles OpenAPI, gardez à l'esprit les 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 du 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 à ceux ToolSpec des LLM en aval respectifs, le plan de données échouera. Les erreurs courantes sont le fait que le nom de propriété dépasse la longueur autorisée ou que le nom contient des caractères non pris en charge.

Pour de meilleurs résultats avec les cibles OpenAPI :

  • Incluez toujours 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

  • Utilisez uniquement les types de supports pris en charge pour une compatibilité maximale

Bonnes 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 contenus dans les définitions du serveur OpenAPI permettent une configuration dynamique des points de terminaison. Toutefois, 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 la substitution arbitraire de domaines

  • https://{subdomain}.{env}.{domain}.com- Plusieurs espaces réservés non contraints

  • https://{host}/api/- Paramètre d'hôte illimité

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

  • Rediriger les demandes vers des points de terminaison involontaires ou malveillants

  • Accès aux ressources du réseau interne (Server-Side Request Forgery)

  • Exfiltrer les informations d'identification ou les données sensibles

Pratiques recommandées :

  • Utilisez des URL statiques entièrement qualifiées 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 la substitution arbitraire de domaines ou d'hôtes

  • 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 régionaux et bloque les demandes adressées à 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 entièrement qualifiés 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 au sein 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 support des fonctionnalités ci-dessous.

Support des fonctionnalités OpenAPI

Le tableau suivant décrit les fonctionnalités d'OpenAPI 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 de champ requise Structures d'objets imbriquées Définitions de tableaux avec spécifications d'éléments

Composition du schéma L'une des spécifications L'une des spécifications L'une des spécifications L'ensemble des spécifications

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 des autorisations sortantes 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 au-delà de la liste prise en charge Types de médias binaires

Paramètres de chemin Définitions simples des paramètres de chemin (exemple : /users/ {userId})

Sérialisation de 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 simples de chaînes, de nombres et de booléens

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 demande 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 branches (type d'octroi des informations d'identification du client) et l'OAuth à trois étapes (type d'autorisation du code d'autorisation). Vous configurez le fournisseur d'autorisation dans Amazon Bedrock AgentCore Identity dans le même compte et dans la même région que la passerelle.

  • Clé d'API — La passerelle utilise un fournisseur d'informations d'identification de clé d'API pour s'authentifier auprès de la cible OpenAPI. Vous configurez le fournisseur de clé d'API dans Amazon Bedrock AgentCore Identity dans le même compte et dans 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 requis pour la signature Sigv4 et une région facultative (par défaut, 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 nativement l'authentification IAM 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 directs Amazon EC2, 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 :

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