CORS

  • Articolo

SI APPLICA A: Tutti i livelli di Gestione API

Il criterio cors aggiunge il supporto per CORS (Cross-Origin Resource Sharing) a un'operazione o a un'API per permettere le chiamate tra domini da client basati su browser.

Nota

Impostare gli elementi e gli elementi figlio del criterio nell'ordine specificato nell'istruzione dei criteri. Per configurare questo criterio, il portale fornisce un editor guidato basato su moduli. Altre informazioni su come impostare o modificare i criteri di Gestione API.

Istruzione del criterio

<cors allow-credentials="false | true" terminate-unmatched-request="true | false">
    <allowed-origins>
        <origin>origin uri</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="number of seconds">
        <method>HTTP verb</method>
    </allowed-methods>
    <allowed-headers>
        <header>header name</header>
    </allowed-headers>
    <expose-headers>
        <header>header name</header>
    </expose-headers>
</cors>

Attributi

Nome Descrizione Richiesto Valore predefinito
allow-credentials L'intestazione Access-Control-Allow-Credentials nella risposta preliminare verrà impostata sul valore di questo attributo e influirà sulla capacità del client di inviare credenziali in richieste tra domini. Le espressioni di criteri sono consentite. No false
terminate-unmatched-request Controlla l'elaborazione delle richieste da più origini che non corrispondono alle impostazioni dei criteri. Le espressioni di criteri sono consentite.

Quando la richiesta OPTIONS viene elaborata come richiesta preliminare e l’intestazione Origin non corrisponde alle impostazioni dei criteri:
- Se l'attributo è impostato su true, terminare immediatamente la richiesta con una risposta vuota 200 OK
- Se l'attributo è impostato su false, controllare in ingresso altri criteri nell'ambito cors che sono elementi figlio diretti dell'elemento in ingresso e applicarli. Se non vengono trovati criteri cors, terminare la richiesta con una risposta vuota 200 OK.

Quando la richiesta GET o HEAD include l'intestazione Origin (e pertanto viene elaborata come semplice richiesta di più origini) e non corrisponde alle impostazioni dei criteri:
- Se l'attributo è impostato su true, terminare immediatamente la richiesta con una risposta vuota 200 OK.
- Se l'attributo è impostato su false, consentire alla richiesta di procedere normalmente e non aggiungere intestazioni CORS alla risposta.		 No true

Elementi

Nome Descrizione Richiesto Valore predefinito
allowed-origins Contiene elementi origin che descrivono le origini consentite per le richieste tra domini. allowed-origins può contenere un unico elemento origin che specifichi * per consentire qualsiasi origine oppure uno o più elementi origin che contengano un URI. Sì N/D
allowed-methods Questo elemento è obbligatorio se sono consentiti metodi diversi da GET o POST. Contiene elementi method che specificano i verbi HTTP supportati. Il valore * indica tutti i metodi. No Se questa sezione non è presente GET e POST sono supportati.
allowed-headers Questo elemento contiene elementi header che specificano i nomi delle intestazioni che è possibile includere nella richiesta. Sì N/D
expose-headers Questo elemento contiene elementi header che specificano i nomi delle intestazioni accessibili dal client. No N/D

Attenzione

Usare il carattere jolly * con attenzione nelle impostazioni dei criteri. Questa configurazione può essere eccessivamente permissiva e può rendere un'API più vulnerabile a determinate minacce alla sicurezza delle API.

elementi di origini consentite

Nome Descrizione Richiesto Valore predefinito
origin Il valore può essere * per consentire tutte le origini oppure un URI che specifichi una singola origine. L'URI deve includere uno schema, un host e una porta. Non includere le virgolette. Sì Se la porta viene omessa in un URI, vengono utilizzate la porta 80 per HTTP e la porta 443 per HTTPS.

attributi di metodi consentiti

Nome Descrizione Richiesto Valore predefinito
preflight-result-max-age L'intestazione Access-Control-Max-Age nella risposta preliminare verrà impostata sul valore di questo attributo e influirà sulla capacità dell'agente utente di memorizzare nella cache la risposta preliminare. Le espressioni di criteri sono consentite. No 0

elementi di metodi consentiti

Nome Descrizione Richiesto Valore predefinito
metodo Specifica un verbo HTTP. Le espressioni di criteri sono consentite. È richiesto almeno un elemento method se è presente la sezione allowed-methods. N/D

elementi di intestazioni consentite

Nome Descrizione Richiesto Valore predefinito
di autorizzazione Specifica un nome di intestazione. È richiesto almeno un elemento header in allowed-headers se è presente tale sezione. N/D

elementi expose-headers

Nome Descrizione Richiesto Valore predefinito
di autorizzazione Specifica un nome di intestazione. È richiesto almeno un elemento header in expose-headers se è presente tale sezione. N/D

Utilizzo

Note sull'utilizzo

  • È possibile configurare il criterio cors in più ambiti, ad esempio nell'ambito del prodotto e in quello globale. Assicurarsi che l'elemento base sia configurato nell'ambito dell'operazione, dell'API e del prodotto per ereditare i criteri necessari negli ambiti padre.
  • Solo il criterio cors viene valutato nella richiesta OPTIONS durante la fase preliminare. I criteri configurati rimanenti vengono valutati nella richiesta approvata.
  • Questo criterio può essere usato una sola volta in una sezione di criteri.

Informazioni su CORS

CORS è uno standard basato su intestazioni HTTP che permette a un browser e a un server di interagire e di determinare se permettere o meno richieste specifiche con origini diverse (chiamate XMLHttpRequest effettuate da JavaScript in una pagina Web in altri domini). Ciò offre una maggiore flessibilità rispetto a permettere solo richieste con la stessa origine e una maggiore sicurezza rispetto a permettere tutte le richieste con origini diverse.

CORS specifica due tipi di richieste con origini diverse:

  • Richieste preliminari (o “preflight”): il browser invia prima una richiesta HTTP usando il metodo OPTIONS al server per determinare se la richiesta effettiva è consentita per l'invio. Se la risposta del server include l'intestazione Access-Control-Allow-Origin che consente l'accesso, il browser procede con la richiesta effettiva.

  • Richieste semplici: queste richieste includono una o più intestazioni Origin aggiuntive, ma non attivano una verifica preliminare CORS. Sono consentite solo le richieste che usano i metodi GET e HEAD e un set limitato di intestazioni della richiesta.

Scenari di criteri cors

Configurare i criteri cors in Gestione API per gli scenari seguenti:

  • Abilitare la console di test interattiva nel portale per sviluppatori. Per informazioni dettagliate, vedere la documentazione del portale per sviluppatori.

    Nota

    Quando si abilita CORS per la console interattiva, per impostazione predefinita Gestione API configura i criteri cors a livello globale.

  • Abilitare Gestione API per rispondere alle richieste preliminari o passare attraverso semplici richieste CORS quando i back-end non forniscono il supporto CORS.

    Nota

    Se una richiesta corrisponde a un'operazione con un metodo OPTIONS definito nell'API, la logica di elaborazione preliminare delle richieste associata ai criteri cors non verrà eseguita. Di conseguenza, tali operazioni possono essere usate per implementare la logica di elaborazione preliminare personalizzata, ad esempio per applicare i criteri cors solo in determinate condizioni.

Problemi di configurazione comuni

  • Chiave di sottoscrizione nell'intestazione: se si configura il criterio cors nell'ambito del prodotto e l'API usa l'autenticazione della chiave di sottoscrizione, il criterio non funzionerà quando la chiave di sottoscrizione viene passata in un'intestazione. Come soluzione alternativa, modificare le richieste per includere una chiave di sottoscrizione come parametro di query.
  • API con controllo delle versioni delle intestazioni: se si configura il criterio cors nell'ambito dell'API e l'API usa uno schema di controllo delle versioni delle intestazioni, il criterio non funzionerà perché la versione viene passata in un'intestazione. Potrebbe essere necessario configurare un metodo di controllo delle versioni alternativo, ad esempio un percorso o un parametro di query.
  • Ordine criterio: è possibile che si verifichi un comportamento imprevisto se il criterio cors non è il primo criterio nella sezione in ingresso. Selezionare Calcola criterio valido nell'editor dei criteri per controllare l’ordine di valutazione del criterio in ogni ambito. In genere, viene applicato solo il primo criterio cors.
  • Risposta 200 OK vuota: in alcune configurazioni dei criteri, alcune richieste tra le origini vengono completate con una risposta 200 OK vuota. Questa risposta è prevista quando terminate-unmatched-request viene impostato sul valore predefinito di true e una richiesta in ingresso ha un’intestazione Origin che non corrisponde a un'origine consentita configurata nei criteri cors.

Esempio

In questo esempio viene illustrato come supportare richieste preliminari, ad esempio quelle con intestazioni personalizzate o metodi diversi da GET e POST. Per supportare le intestazioni personalizzate e altri verbi HTTP, consultare le sezioni allowed-methods e allowed-headers come illustrato nell'esempio seguente.

<cors allow-credentials="true">
    <allowed-origins>
        <!-- Localhost useful for development -->
        <origin>http://localhost:8080/</origin>
        <origin>http://example.com/</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="300">
        <method>GET</method>
        <method>POST</method>
        <method>PATCH</method>
        <method>DELETE</method>
    </allowed-methods>
    <allowed-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
        <header>x-zumo-version</header>
        <header>x-zumo-auth</header>
        <header>content-type</header>
        <header>accept</header>
    </allowed-headers>
    <expose-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
    </expose-headers>
</cors>

Contenuto correlato

Per ulteriori informazioni sull'utilizzo dei criteri, vedere: