CORS

  • Article

S’APPLIQUE À : tous les niveaux Gestion des API

La stratégie cors ajoute la prise en charge du partage des ressources cross-origin (CORS) à une opération ou une API afin de permettre les appels inter-domaines à partir des navigateurs clients.

Notes

Définissez les éléments enfants et de stratégie dans l’ordre fourni dans l’instruction de stratégie. Pour vous aider à configurer cette stratégie, le portail fournit un éditeur guidé basé sur des formulaires. En savoir plus sur comment définir ou modifier des stratégies du service Gestion des API.

Instruction de la stratégie

<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>

Attributs

Nom Description Obligatoire Default
allow-credentials L’en-tête Access-Control-Allow-Credentials de la réponse en amont est défini sur la valeur de cet attribut et influe sur la capacité du client à envoyer des informations d’identification dans les demandes inter-domaines. Les expressions de stratégie sont autorisées. Non false
terminate-unmatched-request Contrôle le traitement des demandes cross-origin qui ne correspondent pas aux paramètres de la stratégie. Les expressions de stratégie sont autorisées.

Lorsque la demande OPTIONS est traitée en tant que demande préliminaire et que l’en-tête Origin ne correspond pas aux paramètres de stratégie :
- Si l’attribut est défini sur true, arrêtez immédiatement la demande avec une réponse vide 200 OK
- Si l’attribut est défini sur false, vérifiez dans l’élément entrant les autres stratégies cors du champ d’application qui sont des enfants directs de l’élément entrant et appliquez-les. Si aucune stratégie cors n’est trouvée, mettez fin à la demande avec une réponse 200 OK vide.

Quand la demande GET ou HEAD inclut l’en-tête Origin (et est donc traitée comme une simple demande cross-origin) et ne correspond pas aux paramètres de stratégie :
- Si l’attribut est défini sur true, arrêtez immédiatement la demande avec une réponse vide 200 OK.
- Si l’attribut est défini sur false, autorisez la demande à se poursuivre normalement et n’ajoutez pas d’en-têtes CORS à la réponse.		 Non true

Éléments

Nom Description Obligatoire Default
allowed-origins Contient des éléments origin qui décrivent les origines autorisées pour les demandes inter-domaines. allowed-origins peut contenir un seul élément origin qui spécifie * pour autoriser toute origine, ou un ou plusieurs éléments origin contenant un URI. Oui N/A
allowed-methods Cet élément est requis si les méthodes autres que GET ou POST sont autorisées. Contient des éléments method qui spécifient les verbes HTTP pris en charge. La valeur * indique toutes les méthodes. Non Si cette section n’est pas présente, les méthodes GET et POST sont prises en charge.
allowed-headers Cet élément contient des éléments header spécifiant les noms des en-têtes qui peuvent être inclus dans la demande. Oui N/A
expose-headers Cet élément contient des éléments header spécifiant les noms des en-têtes accessibles par le client. Non N/A

Attention

Utilisez le caractère générique * avec précaution dans les paramètres de stratégie. Cette configuration peut être trop permissive et rendre une API plus vulnérable à certaines menaces de sécurité des API.

éléments allowed-origins

Nom Description Obligatoire Default
origin La valeur peut être * pour autoriser toutes les origines, ou un URI qui spécifie une origine unique. L'URI doit comprendre un modèle, un hôte et un port. N’incluez pas les guillemets. Oui Si le port n’est pas spécifié dans l’URI, le port 80 est utilisé pour HTTP et le port 443 pour HTTPS.

Attributs allowed-methods

Nom Description Obligatoire Default
preflight-result-max-age L’en-tête Access-Control-Max-Age de la réponse en amont est défini sur la valeur de cet attribut et influe sur la capacité de l’agent utilisateur à mettre en cache la réponse en amont. Les expressions de stratégie sont autorisées. Non 0

éléments allowed-methods

Nom Description Obligatoire Default
method Spécifie un verbe HTTP. Les expressions de stratégie sont autorisées. Au moins un élément method est requis si la section allowed-methods est présente. N/A

éléments allowed-headers

Nom Description Obligatoire Default
en-tête Spécifie un nom d’en-tête. Au moins un headerélément est requis dans allowed-headers si cette section est présente. N/A

éléments expose-headers

Nom Description Obligatoire Default
en-tête Spécifie un nom d’en-tête. Au moins un headerélément est requis dans expose-headers si cette section est présente. N/A

Usage

Notes d’utilisation

  • Vous pouvez configurer la stratégie cors sur plusieurs étendues (par exemple, sur l’étendue du produit et sur l’étendue globale). Vérifiez que l’élément base est configuré pour les étendues d’opération, d’API et de produit pour hériter des stratégies nécessaires aux étendues parentes.
  • Seule la stratégie cors est évaluée sur la demande OPTIONS pendant la préversion. Les stratégies configurées restantes sont évaluées sur la demande approuvée.
  • Cette stratégie ne peut être employée qu’une seule fois dans une section stratégie.

À propos de CORS

CORS est une norme basée sur les en-têtes HTTP qui permet à un navigateur et à un serveur d'interagir et de déterminer si les demandes cross-origin doivent être autorisées ou non (appels XMLHttpRequest passés via JavaScript sur une page web vers d'autres domaines). Cette stratégie offre plus de flexibilité que de simplement autoriser les demandes de même origine, mais elle est plus sûre que d'autoriser toutes les demandes cross-origin.

CORS spécifie deux types de demandes cross-origin :

  • Demandes prédéfinies (ou « préversion ») : le navigateur envoie d’abord au serveur une requête HTTP à l’aide de la méthode OPTIONS pour déterminer si la requête réelle est autorisée pour l’envoi. Si la réponse du serveur inclut l’en-tête Access-Control-Allow-Origin qui autorise l’accès, le navigateur poursuit avec la requête réelle.

  • Demandes simples : ces demandes incluent un ou plusieurs en-têtes Origin supplémentaires, mais ne déclenchent pas de préversion CORS. Seules les demandes utilisant les méthodes GET et HEAD, ainsi qu’un ensemble limité d’en-têtes de demande sont autorisées.

Scénarios de stratégie cors

Configurez la stratégie cors dans API Management pour les scénarios suivants :

  • Activez la console de test interactive dans le portail des développeurs. Pour plus d’informations, reportez-vous à la documentation du portail des développeurs.

    Notes

    Lorsque vous activez CORS pour la console interactive, par défaut, API Management configure la stratégie cors dans l’étendue globale.

  • Activez API Management pour répondre aux demandes préliminaires ou transmettre des demandes CORS simples lorsque les back-ends ne fournissent pas leur propre support CORS.

    Notes

    Si la demande correspond à une opération avec une méthode OPTIONS définie dans l’API, la logique de traitement des demandes préliminaires associée aux stratégies cors n’est pas exécutée. Par conséquent, ces opérations peuvent être utilisées pour implémenter une logique de traitement préliminaire personnalisée, par exemple pour appliquer la stratégie cors uniquement dans certaines conditions.

Problèmes de configuration courants

  • Clé d’abonnement dans l’en-tête : si vous configurez la stratégie cors dans l’étendue du produit et que votre API utilise l’authentification par clé d’abonnement, la stratégie ne fonctionnera pas lorsque la clé d’abonnement est transférée dans un en-tête. Pour résoudre ce problème, modifiez les demandes pour inclure une clé d’abonnement en tant que paramètre de requête.
  • API avec contrôle de version d’en-tête : si vous configurez la stratégie cors dans l’étendue API et que votre API utilise un schéma de contrôle de version d’en-tête, la stratégie ne fonctionnera pas, car la version est transférée dans un en-tête. Vous devrez peut-être configurer une autre méthode de contrôle de version, telle qu’un chemin d’accès ou un paramètre de requête.
  • Ordre de stratégie : vous pouvez rencontrer un comportement inattendu si la stratégie cors n’est pas la première stratégie dans la section entrante. Sélectionnez Calculer la stratégie actuelle dans l’éditeur de stratégie pour vérifier l’ordre d’évaluation de la stratégie pour chaque étendue. En règle générale, seule la première stratégie cors est appliquée.
  • Réponse 200 OK vide : dans certaines configurations de stratégie, certaines demandes cross-origin se terminent par une réponse vide 200 OK . Cette réponse est attendue lorsque terminate-unmatched-request est défini sur sa valeur par défaut true et qu’une demande entrante a un en-tête Origin qui ne correspond pas à une origine autorisée configurée dans la stratégie cors.

Exemple

Cet exemple montre comment prendre en charge les demandes en amont, telles que celles comportant des en-têtes personnalisés ou des méthodes autres que GET et POST. Pour prendre en charge les en-têtes personnalisés et autres verbes HTTP, utilisez les sections allowed-methods et allowed-headers comme indiqué dans l’exemple suivant.

<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>

Contenu connexe

Pour plus d’informations sur l’utilisation des stratégies, consultez :