CORS et origines autorisées
Une app navigateur appelle Facet depuis sa propre origine. Le navigateur
bloque l’appel tant que Facet ne nomme pas cette origine dans ses en-têtes
Cross-Origin Resource Sharing (CORS). Vous enregistrez les origines sur le
document de l’app, et Facet les reflète sur l’endpoint de token et sur toute
la surface /Api/*. La liste d’origines est active immédiatementà : une
modification prend effet à la requête suivante.
Pour les agentsà : Placez des origines nues dans
allowed_originssurapp.App— par exemplehttps://app.company.tldet des origines de dev commehttp://localhost:5173. Modifiez avecPATCH /Api/app/App/{id}(cookie de session plusX-Requested-With: XMLHttpRequest). Vérifiez aveccurl -X OPTIONSen envoyantOrigin,Access-Control-Request-MethodetAccess-Control-Request-Headers: Authorization, DPoP; une origine enregistrée reçoitAccess-Control-Allow-Originen écho. Le changement est actif à la requête suivante — sans redémarrage.
Quand l’utiliser
Section intitulée « Quand l’utiliser »Consultez cette page quandà :
- Un
fetchnavigateur échoue parce que la réponse ne porte aucun en-tête CORS. - Vous déployez l’app sur un nouvel hôte et devez ajouter son origine.
- Vous ajoutez une origine de dev, ou une WebSocket refuse de s’ouvrir.
Avant de commencer
Section intitulée « Avant de commencer »- Une app est enregistrée — voir Enregistrer une app.
- Il vous faut le droit
updatesurapp.Apppour modifier les origines. - Listez chaque origine depuis laquelle l’app navigateur est servie, origines de dev comprises.
1. Listez les origines
Section intitulée « 1. Listez les origines »Chaque entrée est une origine nueà : schéma, hôte et port facultatif.
Enregistrez chaque origine depuis laquelle l’app navigateur est servie.
Incluez les hôtes de production et les hôtes de dev, par exemple
http://localhost:5173.
2. Définissez-les sur l’app
Section intitulée « 2. Définissez-les sur l’app »L’étape de configuration de l’assistant recueille les origines à
l’enregistrement. Pour les changer plus tard, faites un PATCH sur le document de l’app. Connectez-vous comme opérateur et conservez les cookies de session :
curl -s -c cookies.txt -X POST https://facet.company.tld/Api/iam/login \ -H "Content-Type: application/json" \ -H "X-Requested-With: XMLHttpRequest" \ -d '{"email": "admin@company.tld", "password": "op-secret"}'Puis définissez la liste d’originesà :
curl -s -b cookies.txt -X PATCH \ https://facet.company.tld/Api/app/App/01JHQ9M4T8C3XK2PB5WY6RD7QF \ -H "Content-Type: application/json" \ -H "X-Requested-With: XMLHttpRequest" \ -d '{"allowed_origins": ["https://deal-board.company.tld", "http://localhost:5173"]}'3. Vérifiez avec une requête preflight
Section intitulée « 3. Vérifiez avec une requête preflight »Envoyez une requête preflight et vérifiez l’en-tête renvoyé en échoà :
curl -s -i -X OPTIONS https://facet.company.tld/Api/crm/Company \ -H "Origin: https://deal-board.company.tld" \ -H "Access-Control-Request-Method: GET" \ -H "Access-Control-Request-Headers: Authorization, DPoP" \ | grep -i access-control-allow-originUne origine enregistrée répond avec sa propre adresseà :
Access-Control-Allow-Origin: https://deal-board.company.tldUne origine non enregistrée répond sans cet en-tête. La même vérification
fonctionne sur l’endpoint de token, /OAuth/token.
Explication
Section intitulée « Explication »Où Facet reflète les origines
Section intitulée « Où Facet reflète les origines »Le gestionnaire CORS reflète les origines enregistrées sur /OAuth/* et
/Api/*, pour les réponses preflight comme pour les réponses réelles. Il
s’exécute avant la vérification d’authentification dans la chaîne de
gestionnairesà ; une requête preflight n’a donc pas besoin
d’authentification. Facet renvoie en écho l’en-tête Origin de la requête
seulement s’il figure dans allowed_origins d’au moins une app active.
Correspondance exacte, jamais de joker
Section intitulée « Correspondance exacte, jamais de joker »Facet n’envoie jamais Access-Control-Allow-Origin: *. Les navigateurs
ignorent la forme * quand Authorization figure dans
Access-Control-Allow-Headers, donc un joker ne protégerait de rien.
Enregistrez plutôt chaque origine exacte.
La liste d’origines est active immédiatement
Section intitulée « La liste d’origines est active immédiatement »Le cache d’origines se déclare périmé à chaque mutation de app.App et se
reconstruit à la lecture suivante. Une modification d’origine s’applique à la
requête suivante. Ni redémarrage, ni changement de configuration du backend.
Les WebSockets utilisent la même liste
Section intitulée « Les WebSockets utilisent la même liste »L’upgrade /Ws vérifie les mêmes origines enregistrées, plus l’hôte propre
de Facet. L’origine d’une app déployée peut ouvrir un socket sans
configuration du backend. Une origine enregistrée nulle part se ferme avec
4403 — voir Temps réel avec WebSockets.
Ce que CORS ne couvre pas
Section intitulée « Ce que CORS ne couvre pas »Facet sert le build d’une app sur l’hôte propre de l’app. C’est une
distribution par hôte, pas du CORS — voir Déployer votre
frontend. Les clients hors navigateur n’envoient
aucun en-tête Origin ; le CORS ne les concerne donc jamais.
Avec l’origine enregistrée, une app navigateur sur
https://deal-board.company.tld lit la liste des sociétés après la
connexion :
// L’app détient un access token venu de la connexion OAuth (voir /apps/oauth-login/).const res = await fetch("https://facet.company.tld/Api/crm/Company?per_page=5", { headers: { Authorization: `Bearer ${accessToken}` },});if (!res.ok) throw new Error(`List failed: ${res.status}`);const page = await res.json();Un token lié par DPoP (Demonstrating Proof of Possession) ajoute le schéma
DPoP et un en-tête de preuve — voir Liaison DPoP des
tokens. Le navigateur n’exécute l’appel que parce que
l’origine est enregistrée.
Dépannage
Section intitulée « Dépannage »Le fetch répond sans Access-Control-Allow-Origin.
L’origine n’est pas enregistrée, ou la seule app qui la porte n’est pas
active. Enregistrez l’origine sur une app active et renvoyez la requête.
Le client réclame à Facet l’en-tête *.
Facet n’envoie jamais *. Enregistrez l’origine exacte sur laquelle l’app
tourne.
La WebSocket se ferme avec 4403.
L’origine n’est pas dans la liste autorisée. Enregistrez-la sur une app active — voir Temps réel avec WebSockets.
Voir aussi
Section intitulée « Voir aussi »- Enregistrer une app — où se définissent les origines.
- Connexion utilisateurà : OAuth 2.1 + PKCE — le flux que les origines déverrouillent.
- Temps réel avec WebSockets — la vérification
d’origine de
/Ws. - Internes sur GitHubà : oauth.md.