Gestion des CORS

Le support de CORS (Cross-origin resource sharing) dans la plateforme Okapi a pour but de permettre à un fournisseur d'API de contrôler le comportement de l'API gateway afin d'autoriser les navigateurs web à consommer l'API en fonction de l'origine de la requête.

Sources :

• Cross-origin resource sharing — Wikipédia
• Cross-origin resource sharing (CORS) - HTTP | MDN
• Understanding CORS – Bartosz Szczeciński – Medium

Cas d'usages

• l'API SSU consommée par un navigateur

Principe de fonctionnement

• L'API gateway applique un comportement par défaut permissif (allow origin à true)
• L'API peut définir une configuration spécifique dans son raccordement pour adapter la stratégie CORS à son besoin
• L'API doit exposer les ressources nécessaires pour permettre des requêtes préliminaires (preflight), sans besoin de définir un endpoint car c'est le middleware CORS qui prendra en charge la requête

Le middleware CORS analyse la configuration courante et applique la stratégie souhaitée en définissant les valeurs des entêtes de réponse suivants :

• Access-Control-Allow-Origin
• Vary
• Access-Control-Allow-Credentials
• Access-Control-Expose-Headers

Ainsi que les entêtes supplémentaires suivant dans le cas d'une requête de preflight :

• Access-Control-Allow-Headers
• Access-Control-Allow-Methods
• Access-Control-Max-Age

Configuration

La configuration CORS peut être définie sous l'attribut extra.cors de l'API.

Exemple :

allowOrigin:
  - https://www.laposte.fr
  - https://laposte.fr
allowCredentials: true
allowHeaders:
  - Origin
  - X-Requested-With

allowOrigin

Agit sur la valeur de l'entête Access-Control-Allow-Origin.

La ou les origines à autoriser prennent la forme d'un élément ou d'une liste (tableau) respectant les types suivants :

• chaîne de caractère : la valeur exacte est utilisée comme seule origine autorisée
• true : l'origine autorisée est dynamique et vaut l'origine de la requête (cas par défaut)
• * : toutes les origines sont autorisées (attention au support inégal et non garanti dans les navigateurs...)
• RegExp : une expression régulière utilisée pour tester l'origine de la requête, l'origine autorisée sera l'origine de la requête si une correspondance est vérifiée.

Dans le cas de l'utilisation d'une liste, le premier élément qui matche fait foi.

allowCredentials

Si défini, agit directement sur la valeur de l'entête Access-Control-Allow-Credentials.

exposeHeaders

Si défini, agit sur la valeur de l'entête Access-Control-Expose-Headers.

Peut contenir une simple valeur, ou un tableau de valeurs.

allowHeaders

Si défini, agit sur la valeur de l'entête Access-Control-Allow-Headers.

Peut contenir une simple valeur, ou un tableau de valeurs.

allowMethods

Si défini, agit sur la valeur de l'entête Access-Control-Allow-Methods.

Peut contenir une simple valeur, ou un tableau de valeurs.

maxAge

Si défini, agit directement sur la valeur de l'entête Access-Control-Max-Age.

preflightContinue

Voir "continuer le preflight"

Ressource supportant le preflight

Pour permettre à l'API gateway de servir correctemnent les requêtes de preflight, il faut simplement déclarer les routes concernées avec une ressource supportant la méthode OPTIONS.

L'API gatewawy répondra par défaut avec un body vide et un code status 204, en incluant les entêtes CORS qui conviennent.

Exemple :

name: ma ressource de preflight
method: options
route: /ma/route

Remarque : inutile de définir un endpoint sauf si la stratégie CORS est configurée pour "continuer le preflight"

Continuer le preflight

Il est possible de signifier à l'API gateway de ne pas répondre à la requête de preflight, afin de pouvoir retourner une réponse spécifique / particulière si nécessaire.

Pour désactiver la réponse automatique de l'API gateway et permettre de "continuer", définir dans la configuration CORS :

preflightContinue: true