CORS-tarkistin

Cross-Origin Resource Sharing (CORS) -käytännön ymmärtäminen

Cross-Origin Resource Sharing eli CORS on selaimen turvamekanismi, joka säätelee sitä, miten yhdestä verkko-osoitteesta (alkuperästä) ladattu komentosarja voi pyytää resursseja toisesta alkuperästä. Kun selain tekee ristiinalkuperäisen pyynnön, se käyttää HTTP-vastausotsikoita määrittääkseen, onko pyynnön tekevällä sivustolla oikeus lukea vastauksen sisältö.

CORS-tarkistin auttaa kehittäjiä analysoimaan näitä sääntöjä. Työkalu selvittää, salliiko selain tietyn ristiinalkuperäisen pyynnön antamiesi HTTP-vastausotsikoiden ja pyynnön yksityiskohtien perusteella. Se ei ota yhteyttä palvelimeen, lue URL-osoitteita, aseta evästeitä, tarkista DNS- tai TLS-tietoja eikä muuta palvelimen kokoonpanoja. Kaikki analyysi tapahtuu paikallisesti, ja otsikkosi ja pyyntösi tiedot pysyvät selaimessasi. BroBroGo ei lataa tai tallenna mitään.

Työkalun syötteet ja vaatimukset

CORS-tarkistin vaatii tarkat tiedot sekä palvelimen antamasta vastauksesta että suunnitellusta pyynnöstä. Syötteet jakautuvat seuraaviin kenttiin:

• Vastaus tarkastukseen: Valinta vaihtoehtojen "Todellinen vastaus" ja "Lentoa edeltävä vastaus" välillä.
• HTTP-vastausotsikot: Tekstikenttä, johon liitetään palvelimen palauttamat HTTP-vastausotsikot. Esitarkastusvastauksia analysoitaessa kenttään on sisällytettävä myös HTTP-tilarivi. Syötteen enimmäispituus on 200 000 merkkiä. Jos kenttä jätetään tyhjäksi, työkalu näyttää virheen "Liitä HTTP-vastausotsikot ennen tarkistamista.". Jos pituus ylittyy, virheilmoitus on "Tämä vastaus on poikkeuksellisen suuri. Pidä se ‹max›-merkkien alla.". Virheelliset rivit tai otsikkonimet tuottavat virheet "Rivi ‹line› ei ole kelvollinen HTTP-otsikko tai tilarivi." tai "Rivi ‹line› sisältää virheellisen HTTP-otsikon nimen.".
• Pyydä alkuperää: Pyynnön tekevän sivuston skeema (malli), isäntä ja valinnainen portti. Esimerkkimuoto on https://app.example.com. Alkuperän on oltava puhdas alkuperä tai null; se ei saa sisältää URL-polkua, kyselyä tai tunnistetietoja. Virheellinen syöte palauttaa virheen "Anna alkuperä, jossa on vain malli, isäntä ja valinnainen portti, kuten https://app.example.com.".
• Pyydetty menetelmä: Suunniteltu HTTP-menetelmä. Jos menetelmä on virheellinen, näytetään virhe "Anna kelvollinen HTTP-menetelmätunnus.". Jos kyseessä on selaimen estämä metodi, virheilmoitus on "Selaimet eivät salli ‹method›-menetelmää fetch-pyynnöissä.".
• Pyydetyt otsikkonimet: Luettelo otsikoista, jotka lähetetään Access-Control-Request-Headers-otsikossa. Otsikot erotetaan toisistaan pilkuilla tai rivinvaihdoilla, esimerkiksi Content-Type, Authorization. Virheellinen nimi laukaisee virheen "‹header›" ei ole kelvollinen HTTP-pyynnön otsikon nimi.".
• Sisällytä tunnistetiedot: Valintakytkin, jolla ilmaistaan, sisältääkö pyyntö evästeitä tai HTTP-todennuksen.

Jos jossakin syötekentässä on virhe, työkalu ilmoittaa: "Korjaa korostettu syöte ja yritä uudelleen.".

Selaimen päätökset ja tulosten tulkinta

Kun tiedot on syötetty ja tarkistus suoritettu, työkalu antaa jonkin seuraavista päätöksistä:

• "Liitä vastaus tarkistaaksesi sen CORS-käytännön." (Alkutila, kun tietoja ei ole vielä syötetty).
• "Anna vastauksen ja pyynnön tiedot ja tarkista sitten CORS-käytäntö." (Kun tarkistus käynnistetään tyhjillä tiedoilla).
• "Sallii liitetyn CORS-vasteen.".
• "Estetty liitetyn CORS-vastauksen takia.".
• "Otsikot menevät läpi, mutta esilentotilaa ei tiedetä.".

Päätöksen ohella työkalu näyttää jäsennetyt Access-Control-* -kentät ja antaa yksityiskohtaiset perustelut päätökselle.

CORS-säännöt ja erikoistapaukset

CORS-käytännön arvioinnissa sovelletaan useita tarkkoja sääntöjä, jotka liittyvät alkuperään, menetelmiin, otsikoihin ja tunnistetietoihin.

Alkuperän tarkistus (Access-Control-Allow-Origin)

Palvelimen on ilmoitettava sallitut alkuperät Access-Control-Allow-Origin-otsikolla. Päätöksen perustelut riippuvat otsikon arvosta ja pyynnön tiedoista:

• Jos arvo vastaa täsmälleen pyynnön alkuperää, perusteena on "Access-Control-Allow-Origin vastaa täsmälleen ‹origin›.".
• Jos käytössä on yleismerkki, perusteena on "Access-Control-Allow-Origin sallii tämän pyynnön minkä tahansa alkuperän.".
• Jos otsikko puuttuu kokonaan, tulos on "Access-Control-Allow-Origin puuttuu.".
• Jos otsikon arvo ei täsmää pyynnön alkuperään, tulos on "Access-Control-Allow-Origin on ‹actual›, ei ‹expected›.".
• Jos otsikko sisältää useita arvoja tai on pilkuilla erotettu lista, se katsotaan virheelliseksi, jolloin tulos on "Access-Control-Allow-Origin:ssa on virheellinen arvo: ‹value›.".

Tunnistetietojen vaikutus (Credentials)

Kun pyyntöön sisällytetään tunnistetietoja (kuten evästeitä tai HTTP-todennus), CORS-säännöt tiukentuvat huomattavasti:

• Access-Control-Allow-Origin ei saa olla jokerimerkki *. Jos se on, selain estää pyynnön perustelulla "Access-Control-Allow-Origin ei voi olla *, kun tunnistetiedot ovat mukana.".
• Access-Control-Allow-Credentials-otsikon on oltava tarkalleen true. Jos se on, perusteena on "Access-Control-Allow-Credentials on aivan totta.". Jos se puuttuu tai on jotain muuta, pyyntö estetään perustelulla "Valtuustietopyyntö vaatii Access-Control-Allow-Credentials: true.".
• Jos tunnistetietoja ei lähetetä, otsikon puuttuminen ei vaikuta päätökseen: "Valtuustietoja ei sisällytetä, joten Access-Control-Allow-Credentials ei vaikuta tähän päätökseen.".
• Tunnistetietojen läsnäolo poistaa myös menetelmien ja otsikoiden jokerimerkkien (*) yleismerkityksen.

Esitarkastus ja HTTP-tila (Preflight)

Esitarkastuspyyntö (Preflight) tehdään OPTIONS-menetelmällä ennen varsinaista pyyntöä, jotta varmistetaan palvelimen hyväksyntä menetelmälle ja otsikoille.

• Esitarkastusvastauksen HTTP-tilan on oltava onnistunut 2xx-tila. Jos se on, perusteena on "Preflight-tila ‹status› on onnistunut.". Jos tila on jokin muu, tulos on "Preflight-tila ‹status› ei ole onnistunut 2xx-tila.".
• Jos HTTP-tilariviä ei ole liitetty syötteeseen, esitarkastuksen tilaa ei voida vahvistaa, jolloin tulos on "HTTP-tilariviä ei liitetty, joten vaadittua 2xx-esitarkastustilaa ei voida tarkistaa.".

Menetelmät ja otsikot esitarkastuksessa

Esitarkastuksessa selain varmistaa, että pyydetty menetelmä ja otsikot ovat sallittuja:

• Jos menetelmä on sallittu, perusteena on "Esilento sallii ‹method›.". Jos se on estetty, perusteena on "Access-Control-Allow-Methods ei salli ‹method›:ta.".
• CORS-suojatut menetelmät (kuten tavallinen GET tai POST) eivät vaadi erillistä mainintaa: "‹method› on CORS-suojattu menetelmä, eikä sen tarvitse näkyä Access-Control-Allow-Methods:ssa.".
• Jos pyynnössä ei ole erityisiä otsikoita, esitarkastusta ei vaadita niiden osalta: "Mikään pyydetty otsikkonimi ei vaadi esitarkastushyväksyntää.".
• Sallitut otsikot ilmoitetaan perusteella "Esitarkastus sallii pyydetyt otsikkonimet: ‹headers›.". Jos ne estetään, peruste on "Access-Control-Allow-Headers ei salli: ‹headers›.".

Erityistapaus: Authorization-otsikko

Authorization-otsikko vaatii aina erityiskäsittelyn. Vaikka palvelin palauttaisi jokerimerkin Access-Control-Allow-Headers: *, se ei kata Authorization-otsikkoa. Jos pyynnössä käytetään kyseistä otsikkoa ilman tunnistetietoja, se on silti mainittava erikseen. Jos näin ei tehdä, selain estää pyynnön perustelulla "Authorization on mainittava nimenomaisesti; Access-Control-Allow-Headers: * ei kata sitä.". Muutoin jokerimerkki toimii normaalisti: "Access-Control-Allow-Headers: * kattaa nämä nimet pyynnölle ilman valtuustietoja: ‹headers›.".

Kenelle työkalu on tarkoitettu?

CORS-sääntöjen ja -virheiden selvittäminen on yleinen tehtävä useissa ohjelmistokehityksen rooleissa. Työkalusta on hyötyä erityisesti seuraaville ryhmille:

• Front-end-kehittäjät, jotka yrittävät selvittää, miksi selain estää API-kutsun tekemisen tai vastauksen lukemisen.
• Back-end-kehittäjät, joiden vastuulla on määrittää oikeat HTTP-vastausotsikot palvelimelle.
• API-alustojen kehittäjät, jotka suunnittelevat rajapintojen julkisia ja yksityisiä CORS-käytäntöjä.
• Ylläpito- ja DevOps-kehittäjät, jotka konfiguroivat välityspalvelimia, sovelluspalomuureja tai API-yhdyskäytäviä.
• Kuka tahansa, joka haluaa varmistaa, salliiko selainkoodi tietyn vastauksen lukemisen tai hyväksyykö OPTIONS-vastaus myöhemmän menetelmän ja sen pyytämät otsikot.

On tärkeää huomata, että työkalun antama hyväksyvä tulos koskee vain liitettyä vastausta ja syötettyjä pyynnön tietoja. Se ei takaa live-pyynnön toimivuutta, sillä todelliseen suoritukseen voivat vaikuttaa uudelleenohjaukset, välimuistissa olevat vastaukset, muuttuvat palvelinsäännöt, selainlaajennukset tai varsinainen vastaus esitarkastuksen jälkeen.

Usein kysytyt kysymykset

Pitäisikö minun liittää varsinainen vastaus vai esitarkastusvastaus?

Käytä Todellinen vastaus tarkistaaksesi, pystyykö selainkoodi lukemaan yhden vastauksen. Käytä Preflight-vastausta OPTIONS-vastaukselle, joka hyväksyy myöhemmän menetelmän ja sen pyydetyt otsikonimet.

Miksi jokerimerkki voi epäonnistua tunnistetiedoilla?

Kun evästeet tai HTTP-todennus sisällytetään, sallitun alkuperän on vastattava tarkasti pyynnön alkuperää. Myös sallittujen menetelmien ja otsikoiden jokerimerkit menettävät yleismerkin merkityksensä.

Todistaako ohimenevä tulos, että live-pyyntö toimii?

Ei. Tämä tulos kattaa vain liitetyn vastauksen ja tähän syötetyt pyynnön tiedot. Uudelleenohjaukset, välimuistissa olevat vastaukset, muuttuvat palvelinsäännöt, selainlaajennukset ja varsinainen vastaus esitarkastuksen jälkeen voivat silti muuttaa lopputulosta.