Considerazioni e limitazioni principali Strategia di autorizzazione Specifiche dello schema OpenAPI

Obiettivi dello schema OpenAPI

OpenAPI (precedentemente noto come Swagger) è uno standard ampiamente utilizzato per descrivere le API RESTful. Gateway supporta le specifiche OpenAPI 3.0 per la definizione delle destinazioni API.

I target OpenAPI connettono il gateway alle API REST definite utilizzando le specifiche OpenAPI. Il Gateway traduce le richieste MCP in arrivo in richieste HTTP a queste API e gestisce la formattazione delle risposte.

Esamina le principali considerazioni e limitazioni, incluso il supporto delle funzionalità, per aiutarti a decidere se un target OpenAPI è applicabile al tuo caso d'uso. In tal caso, puoi creare uno schema che segua le specifiche e quindi impostare le autorizzazioni per consentire al gateway di accedere alla destinazione. Per ulteriori informazioni, scegli un argomento:

Considerazioni e limitazioni principali

Importante

La specifica OpenAPI deve includere operationId campi per tutte le operazioni che si desidera esporre come strumenti. L'OperationID viene utilizzato come nome dello strumento nell'interfaccia MCP.

Quando utilizzi i target OpenAPI, tieni presente i seguenti requisiti e limitazioni:

Le versioni 3.0 e 3.1 di OpenAPI sono supportate (Swagger 2.0 non è supportato)
Il file OpenAPI deve essere privo di errori semantici
L'attributo server deve avere un URL valido dell'endpoint effettivo
Solo application/json il tipo di contenuto è completamente supportato
Le funzionalità di schemi complessi come OneOf, AnyOf e AllOf non sono supportate
I serializzatori dei parametri di percorso e i serializzatori di parametri per i parametri di query, header e cookie non sono supportati
Ogni LLM avrà dei vincoli. ToolSpec Se OpenAPI ha APIs/properties/object nomi non conformi a quelli ToolSpec dei rispettivi LLM downstream, il piano dati fallirà. Gli errori più comuni sono il nome della proprietà che supera la lunghezza consentita o il nome contenente caratteri non supportati.

Per ottenere i migliori risultati con gli obiettivi OpenAPI:

Includi sempre OperationID in tutte le operazioni
Usa strutture di parametri semplici invece di una serializzazione complessa
Implementa l'autenticazione e l'autorizzazione al di fuori delle specifiche
Utilizza solo i tipi di supporti supportati per la massima compatibilità

Procedure consigliate di sicurezza per i parametri URL

avvertimento

Quando definisci gli URL dei server nelle specifiche OpenAPI, evita di utilizzare modelli di parametri URL eccessivamente permissivi che potrebbero esporre il tuo gateway a rischi di sicurezza.

I parametri URL nelle definizioni dei server OpenAPI consentono la configurazione dinamica degli endpoint. Tuttavia, alcuni modelli possono introdurre vulnerabilità di sicurezza se non sono adeguatamente vincolati. In particolare, evita di utilizzare modelli di dominio completamente dinamici come:

https://{yourDomain}/- Consente la sostituzione arbitraria del dominio
https://{subdomain}.{env}.{domain}.com- Segnaposto multipli non vincolati
https://{host}/api/- Parametro host senza restrizioni

Questi modelli possono essere potenzialmente sfruttati per:

Reindirizza le richieste verso endpoint non intenzionali o dannosi
Accedi alle risorse di rete interne (Request Forgery) Server-Side
Esporta credenziali o dati sensibili

Pratiche consigliate:

Utilizza URL statici completi quando possibile: https://api.example.com/v1
Limita i parametri ai sottodomini all'interno del dominio controllato e implementa la convalida nella tua applicazione
Evita di utilizzare parametri che consentano la sostituzione arbitraria del dominio o dell'host
Implementa una convalida aggiuntiva nella tua API per verificare che i valori dei parametri di runtime corrispondano ai modelli previsti

AgentCore Il gateway convalida automaticamente i parametri regionali e blocca le richieste agli intervalli IP privati.

Esempio di configurazione sicura dell'URL di un server:


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

Se sono necessari parametri dinamici, utilizza domini completamente qualificati con segnaposto e restrizioni enumerative minime:


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

Questo approccio limita i parametri URL a sottodomini specifici all'interno del dominio controllato, pur mantenendo la flessibilità per le distribuzioni multi-tenant. L'utilizzo delle restrizioni enum previene i valori arbitrari e aiuta a proteggersi dagli attacchi SSRF limitando i parametri a valori predefiniti e sicuri. Inoltre, convalida sempre i valori dei tenant nella logica dell'applicazione.

Per valutare l'utilizzo degli obiettivi dello schema OpenAPI con AgentCore Gateway, consultate la seguente tabella di supporto delle funzionalità.

Supporto per le funzionalità OpenAPI

La tabella seguente illustra le funzionalità di OpenAPI supportate e non supportate da Gateway:

Caratteristiche supportate	Caratteristiche non supportate
Definizioni dello schema Tipi di dati di base (stringa, numero, intero, booleano, array, oggetto) Convalida dei campi obbligatori Strutture di oggetti annidati Definizioni di array con specifiche degli elementi	Composizione dello schema Specifiche OneOF Specifiche AnyOf Tutte le specifiche OF
Metodi HTTP Metodi HTTP standard (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)	Schemi di sicurezza Schemi di sicurezza a livello di specifica OpenAPI (l'autenticazione deve essere configurata utilizzando la configurazione di autorizzazione in uscita del Gateway)
Tipi application/json application/xml multipart/form di file multimediali -data -www-form-urlencoded application/x	Tipi di file multimediali Tipi di file multimediali personalizzati oltre all'elenco supportato Tipi di file multimediali binari
Parametri di percorso Definizioni semplici dei parametri di percorso (esempio: /users/ {userId})	Serializzazione dei parametri Serializzatori di parametri di percorso complessi (Esempio:`/users { ;id\*} { ?metadata}`) Array di parametri di interrogazione con serializzazione complessa Serializzatori di parametri di intestazione Serializzatori di parametri di cookie
Parametri di interrogazione Definizioni di base dei parametri di interrogazione Tipi semplici di stringhe, numeri e booleani	Callback e Webhook Operazioni di callback Definizioni di webhook
Request/Response Corpi di richiesta e risposta JSON Corpi di richiesta e risposta XML Codici di stato HTTP standard (200, 201, 400, 404, 500, ecc.)	Collegamenti Collegamenti tra operazioni

Strategia di autorizzazione

I seguenti tipi di autorizzazione in uscita sono supportati per i target OpenAPI:

Nessuna autorizzazione: il gateway richiama il target OpenAPI senza autorizzazione preconfigurata. Questo approccio non è consigliato.
OAuth: il gateway supporta sia OAuth a due fasi (tipo di concessione delle credenziali client) che OAuth a tre fasi (tipo di concessione del codice di autorizzazione). È possibile configurare il provider di autorizzazione in Amazon AgentCore Bedrock Identity nello stesso account e nella stessa regione del gateway.
Chiave API: il gateway utilizza un fornitore di credenziali con chiave API per autenticarsi con il target OpenAPI. È possibile configurare il fornitore di chiavi API in Amazon Bedrock AgentCore Identity nello stesso account e nella stessa regione del gateway.
IAM (AWS Signature Version 4 (Sig V4)): il gateway firma le richieste al target OpenAPI utilizzando SigV4 con le credenziali del ruolo di servizio del gateway. Si configura una IamCredentialProvider con un nome di servizio obbligatorio per la firma Sigv4 e una regione opzionale (l'impostazione predefinita è la regione del gateway).

Importante

L'autorizzazione in uscita IAM (Sigv4) richiede che il target OpenAPI sia ospitato dietro un servizio che supporta nativamente l'autenticazione IAM. AWS Il gateway firma le richieste in uscita con Sigv4 ma non modifica la configurazione di autenticazione sulla destinazione. Il servizio di destinazione deve essere in grado di verificare le firme SIGv4.

I seguenti AWS servizi supportano in modo nativo l'autenticazione IAM e sono compatibili con l'autorizzazione IAM in uscita per le destinazioni OpenAPI:

Gateway Amazon API
URL delle funzioni Lambda
Amazon Bedrock Gateway AgentCore

I servizi che non verificano in modo nativo le firme SIGv4, come Application Load Balancer o endpoint Amazon EC2 diretti, non sono compatibili con l'autorizzazione in uscita IAM. Se il tuo target OpenAPI è ospitato dietro uno di questi servizi, utilizza invece l'autorizzazione con chiave OAuth o API.

Per ulteriori informazioni sull'impostazione dell'autorizzazione in uscita, consulta Configurare l'autorizzazione in uscita per il gateway.

Specifiche dello schema OpenAPI

La specifica OpenAPI definisce l'API REST che il tuo Gateway esporrà. Fai riferimento alle seguenti risorse per configurare le specifiche OpenAPI:

Per informazioni sul formato della specifica OpenAPI, vedere Specifica OpenAPI.
Per informazioni sulle funzionalità supportate e non supportate quando si utilizza una specifica OpenAPI con AgentCore Gateway, vedere la tabella nel supporto delle funzionalità OpenAPI. Rispetta questi requisiti per prevenire errori durante la creazione e l'invocazione del target.

Dopo aver definito lo schema OpenAPI, puoi effettuare una delle seguenti operazioni:

Caricalo in un bucket Amazon S3 e fai riferimento alla posizione S3 quando aggiungi la destinazione al tuo gateway.
Incolla la definizione in linea quando aggiungi la destinazione al gateway.

Espandi una sezione per vedere esempi di specifiche OpenAPI supportate e non supportate:

Di seguito viene mostrato un esempio di specifica OpenAPI supportata

Esempio di una specifica OpenAPI supportata:


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

Di seguito viene mostrato un altro esempio di specifica OpenAPI supportata.


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

Di seguito viene mostrato un esempio di schema non supportato con OneOf:


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

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Fasi di API Gateway

Modelli Smithy