terriajs

<!DOCTYPE html> <html lang="en" class="no-js"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width,initial-scale=1"> <meta http-equiv="x-ua-compatible" content="ie=edge"> <meta name="lang:clipboard.copy" content="Copy to clipboard"> <meta name="lang:clipboard.copied" content="Copied to clipboard"> <meta name="lang:search.language" content="en"> <meta name="lang:search.result.none" content="No matching documents"> <meta name="lang:search.result.one" content="1 matching document"> <meta name="lang:search.result.other" content="# matching documents"> <meta name="lang:search.tokenizer" content="[\s\-]+"> <link rel="shortcut icon" href="../../assets/images/favicon.png"> <meta name="generator" content="mkdocs-0.17.2, mkdocs-material-2.2.3"> <title>Cross-Origin Resource Sharing - TerriaJS</title> <link rel="stylesheet" href="../../assets/stylesheets/application.bcabdff3.css"> <script src="../../assets/javascripts/modernizr.1aa3b519.js"></script> <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,400i,700|Roboto+Mono"> <style>body,input{font-family:"Roboto","Helvetica Neue",Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"Roboto Mono","Courier New",Courier,monospace}</style> <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons"> </head> <body> <svg class="md-svg"> <defs> </defs> </svg> <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="drawer"> <input class="md-toggle" data-md-toggle="search" type="checkbox" id="search"> <label class="md-overlay" data-md-component="overlay" for="drawer"></label> <header class="md-header" data-md-component="header"> <nav class="md-header-nav md-grid"> <div class="md-flex"> <div class="md-flex__cell md-flex__cell--shrink"> <a href="../.." title="TerriaJS" class="md-header-nav__button md-logo"> <img src="../../terria.png" width="24" height="24"> </a> </div> <div class="md-flex__cell md-flex__cell--shrink"> <label class="md-icon md-icon--menu md-header-nav__button" for="drawer"></label> </div> <div class="md-flex__cell md-flex__cell--stretch"> <div class="md-flex__ellipsis md-header-nav__title" data-md-component="title"> <span class="md-header-nav__topic"> TerriaJS </span> <span class="md-header-nav__topic"> Cross-Origin Resource Sharing </span> </div> </div> <div class="md-flex__cell md-flex__cell--shrink"> <label class="md-icon md-icon--search md-header-nav__button" for="search"></label> <div class="md-search" data-md-component="search" role="dialog"> <label class="md-search__overlay" for="search"></label> <div class="md-search__inner"> <form class="md-search__form" name="search"> <input type="text" class="md-search__input" name="query" required placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="query"> <label class="md-icon md-search__icon" for="search"></label> <button type="reset" class="md-icon md-search__icon" data-md-component="reset"></button> </form> <div class="md-search__output"> <div class="md-search__scrollwrap" data-md-scrollfix> <div class="md-search-result" data-md-component="result"> <div class="md-search-result__meta"> Type to start searching </div> <ol class="md-search-result__list"></ol> </div> </div> </div> </div> </div> </div> </div> </nav> </header> <div class="md-container"> <main class="md-main"> <div class="md-main__inner md-grid" data-md-component="container"> <div class="md-sidebar md-sidebar--primary" data-md-component="navigation"> <div class="md-sidebar__scrollwrap"> <div class="md-sidebar__inner"> <nav class="md-nav md-nav--primary" data-md-level="0"> <label class="md-nav__title md-nav__title--site" for="drawer"> <span class="md-nav__button md-logo"> <img src="../../terria.png" width="24" height="24"> </span> TerriaJS </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../.." title="Home" class="md-nav__link"> Home </a> </li> <li class="md-nav__item"> <a href="../../getting-started/" title="Getting Started" class="md-nav__link"> Getting Started </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-toggle md-nav__toggle" data-md-toggle="nav-3" type="checkbox" id="nav-3"> <label class="md-nav__link" for="nav-3"> Customizing </label> <nav class="md-nav" data-md-component="collapsible" data-md-level="1"> <label class="md-nav__title" for="nav-3"> Customizing </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../customizing/" title="Overview" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../customizing/client-side-config/" title="Client-side Config" class="md-nav__link"> Client-side Config </a> </li> <li class="md-nav__item"> <a href="../../customizing/initialization-files/" title="Initialization Files" class="md-nav__link"> Initialization Files </a> </li> <li class="md-nav__item"> <a href="../../customizing/server-side-config/" title="Server-side Config" class="md-nav__link"> Server-side Config </a> </li> <li class="md-nav__item"> <a href="../../customizing/skinning/" title="Skinning" class="md-nav__link"> Skinning </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--active md-nav__item--nested"> <input class="md-toggle md-nav__toggle" data-md-toggle="nav-4" type="checkbox" id="nav-4" checked> <label class="md-nav__link" for="nav-4"> Connecting to Data </label> <nav class="md-nav" data-md-component="collapsible" data-md-level="1"> <label class="md-nav__title" for="nav-4"> Connecting to Data </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../" title="Overview" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item md-nav__item--active"> <input class="md-toggle md-nav__toggle" data-md-toggle="toc" type="checkbox" id="toc"> <label class="md-nav__link md-nav__link--active" for="toc"> Cross-Origin Resource Sharing </label> <a href="./" title="Cross-Origin Resource Sharing" class="md-nav__link md-nav__link--active"> Cross-Origin Resource Sharing </a> <nav class="md-nav md-nav--secondary"> <label class="md-nav__title" for="toc">Table of contents</label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="#more-detailed-explanation" title="More Detailed Explanation" class="md-nav__link"> More Detailed Explanation </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../catalog-groups/" title="Catalog Groups" class="md-nav__link"> Catalog Groups </a> </li> <li class="md-nav__item"> <a href="../catalog-items/" title="Catalog Items" class="md-nav__link"> Catalog Items </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-toggle md-nav__toggle" data-md-toggle="nav-4-5" type="checkbox" id="nav-4-5"> <label class="md-nav__link" for="nav-4-5"> Customizing Data Appearance </label> <nav class="md-nav" data-md-component="collapsible" data-md-level="2"> <label class="md-nav__title" for="nav-4-5"> Customizing Data Appearance </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../customizing-data-appearance/overview/" title="Overview" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../customizing-data-appearance/imagery-data/" title="Imagery Data" class="md-nav__link"> Imagery Data </a> </li> <li class="md-nav__item"> <a href="../customizing-data-appearance/tabular-data/" title="Tabular Data" class="md-nav__link"> Tabular Data </a> </li> <li class="md-nav__item"> <a href="../customizing-data-appearance/feature-info-template/" title="Feature Information Template" class="md-nav__link"> Feature Information Template </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../catalog-functions/" title="Catalog Functions" class="md-nav__link"> Catalog Functions </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-toggle md-nav__toggle" data-md-toggle="nav-4-7" type="checkbox" id="nav-4-7"> <label class="md-nav__link" for="nav-4-7"> Catalog Type Details </label> <nav class="md-nav" data-md-component="collapsible" data-md-level="2"> <label class="md-nav__title" for="nav-4-7"> Catalog Type Details </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../catalog-type-details/abs-itt-dataset-list/" title="ABS ITT (group)" class="md-nav__link"> ABS ITT (group) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/abs-itt/" title="ABS ITT (item)" class="md-nav__link"> ABS ITT (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/esri-featureServer-group/" title="ArcGIS FeatureServer (group)" class="md-nav__link"> ArcGIS FeatureServer (group) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/esri-featureServer/" title="ArcGIS FeatureServer (item)" class="md-nav__link"> ArcGIS FeatureServer (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/esri-mapServer-group/" title="ArcGIS MapServer (group)" class="md-nav__link"> ArcGIS MapServer (group) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/esri-mapServer/" title="ArcGIS MapServer (item)" class="md-nav__link"> ArcGIS MapServer (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/esri-group/" title="ArcGIS Server (group)" class="md-nav__link"> ArcGIS Server (group) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/bing-maps/" title="Bing Maps (item)" class="md-nav__link"> Bing Maps (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/csw/" title="Catalog Service for the Web (CSW) (group)" class="md-nav__link"> Catalog Service for the Web (CSW) (group) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/czml/" title="Cesium Language (CZML) (item)" class="md-nav__link"> Cesium Language (CZML) (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/cesium-terrain/" title="Cesium Terrain (item)" class="md-nav__link"> Cesium Terrain (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/ckan/" title="CKAN (group)" class="md-nav__link"> CKAN (group) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/ckan-resource/" title="CKAN Resource (item)" class="md-nav__link"> CKAN Resource (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/csv/" title="Comma-Separated Values (CSV) (item)" class="md-nav__link"> Comma-Separated Values (CSV) (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/composite/" title="Composite (item)" class="md-nav__link"> Composite (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/ogr/" title="Format Conversion Service (based on OGR) (item)" class="md-nav__link"> Format Conversion Service (based on OGR) (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/geojson/" title="GeoJSON (item)" class="md-nav__link"> GeoJSON (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/gpx/" title="GPX (item)" class="md-nav__link"> GPX (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/group/" title="Group (Manual) (group)" class="md-nav__link"> Group (Manual) (group) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/kml/" title="Keyhole Markup Language (KML) (item)" class="md-nav__link"> Keyhole Markup Language (KML) (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/open-street-map/" title="OpenStreetMap (item)" class="md-nav__link"> OpenStreetMap (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/places-like-me-function/" title="Places Like Me (function)" class="md-nav__link"> Places Like Me (function) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/sdmx-json/" title="SDMX-JSON (item)" class="md-nav__link"> SDMX-JSON (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/sos/" title="Sensor Observation Service (SOS) (item)" class="md-nav__link"> Sensor Observation Service (SOS) (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/socrata/" title="Socrata (group)" class="md-nav__link"> Socrata (group) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/spatial-detailing-function/" title="Spatial Detailing (function)" class="md-nav__link"> Spatial Detailing (function) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/terria-json/" title="TerriaJS JSON (function)" class="md-nav__link"> TerriaJS JSON (function) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/url-template/" title="URL Template (item)" class="md-nav__link"> URL Template (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/wfs-getCapabilities/" title="Web Feature Service (WFS) (group)" class="md-nav__link"> Web Feature Service (WFS) (group) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/wfs/" title="Web Feature Service (WFS) (item)" class="md-nav__link"> Web Feature Service (WFS) (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/wms-getCapabilities/" title="Web Map Service (WMS) (group)" class="md-nav__link"> Web Map Service (WMS) (group) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/wms/" title="Web Map Service (WMS) (item)" class="md-nav__link"> Web Map Service (WMS) (item) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/wps/" title="Web Processing Service (WPS) (function)" class="md-nav__link"> Web Processing Service (WPS) (function) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/wps-getCapabilities/" title="Web Processing Service (WPS) (group)" class="md-nav__link"> Web Processing Service (WPS) (group) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/wfs-features-group/" title="WFS Features (group)" class="md-nav__link"> WFS Features (group) </a> </li> <li class="md-nav__item"> <a href="../catalog-type-details/why-am-i-special-function/" title="Why Am I Special (function)" class="md-nav__link"> Why Am I Special (function) </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-toggle md-nav__toggle" data-md-toggle="nav-5" type="checkbox" id="nav-5"> <label class="md-nav__link" for="nav-5"> Deploying </label> <nav class="md-nav" data-md-component="collapsible" data-md-level="1"> <label class="md-nav__title" for="nav-5"> Deploying </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../deploying/" title="Overview" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../deploying/deploying-terriamap/" title="Deploying TerriaMap" class="md-nav__link"> Deploying TerriaMap </a> </li> <li class="md-nav__item"> <a href="../../deploying/deploying-to-aws/" title="Deploying to AWS" class="md-nav__link"> Deploying to AWS </a> </li> <li class="md-nav__item"> <a href="../../deploying/deploying-with-kubernetes/" title="Deploying with Kubernetes" class="md-nav__link"> Deploying with Kubernetes </a> </li> <li class="md-nav__item"> <a href="../../deploying/setting-up-a-region-mapping-server/" title="Setting Up a Region Mapping Server" class="md-nav__link"> Setting Up a Region Mapping Server </a> </li> <li class="md-nav__item"> <a href="../../deploying/setting-up-geoserver/" title="Setting Up Geoserver" class="md-nav__link"> Setting Up Geoserver </a> </li> <li class="md-nav__item"> <a href="../../deploying/using-as-a-ckan-previewer/" title="Using as a CKAN Previewer" class="md-nav__link"> Using as a CKAN Previewer </a> </li> <li class="md-nav__item"> <a href="../../deploying/controlling-with-url-parameters/" title="Controlling with URL Parameters" class="md-nav__link"> Controlling with URL Parameters </a> </li> <li class="md-nav__item"> <a href="../../deploying/controlling-in-an-iframe-or-popup/" title="Controlling in an <iframe> or Popup" class="md-nav__link"> Controlling in an <iframe> or Popup </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-toggle md-nav__toggle" data-md-toggle="nav-6" type="checkbox" id="nav-6"> <label class="md-nav__link" for="nav-6"> Contributing </label> <nav class="md-nav" data-md-component="collapsible" data-md-level="1"> <label class="md-nav__title" for="nav-6"> Contributing </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../contributing/" title="Overview" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../contributing/development-environment/" title="Development Environment" class="md-nav__link"> Development Environment </a> </li> <li class="md-nav__item"> <a href="../../contributing/architecture/" title="Architecture" class="md-nav__link"> Architecture </a> </li> <li class="md-nav__item"> <a href="../../contributing/using-a-custom-version-of-cesium/" title="Using a Custom Version of Cesium" class="md-nav__link"> Using a Custom Version of Cesium </a> </li> <li class="md-nav__item"> <a href="../../contributing/setting-up-saucelabs/" title="Setting up Saucelabs" class="md-nav__link"> Setting up Saucelabs </a> </li> <li class="md-nav__item"> <a href="../../contributing/problems-and-solutions/" title="Problems and Solutions" class="md-nav__link"> Problems and Solutions </a> </li> </ul> </nav> </li> </ul> </nav> </div> </div> </div> <div class="md-sidebar md-sidebar--secondary" data-md-component="toc"> <div class="md-sidebar__scrollwrap"> <div class="md-sidebar__inner"> <nav class="md-nav md-nav--secondary"> <label class="md-nav__title" for="toc">Table of contents</label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="#more-detailed-explanation" title="More Detailed Explanation" class="md-nav__link"> More Detailed Explanation </a> </li> </ul> </nav> </div> </div> </div> <div class="md-content"> <article class="md-content__inner md-typeset"> <h1>Cross-Origin Resource Sharing</h1> <p>To ensure that TerriaJS is able to access your data, you must add all servers you intend to access to <code>devserverconfig.json</code>'s <code>allowProxyFor</code> list. This "whitelist" authorizes the proxy to work with those servers.</p> <p>Failing to do this may result in an error like this:</p> <p><code>...the server does not support CORS. If this is your server, verify that CORS is enabled and enable it if it is not. If you do not control the server, please contact the administrator of the server and ask them to enable CORS. Or ... ask us to add this server to the list of non-CORS-supporting servers that may be proxied.</code></p> <p>Next, you should add servers that <em>do</em> support Cross-Origin Resource Sharing (CORS) to the <code>corsDomains</code> list in your <a href="../../customizing/initialization-files/">initialization file</a>. Servers in this list are contacted directly instead of going through the proxy... except:</p> <ul> <li>in Internet Explorer 9</li> <li>if an HTTPS web page is accessing an HTTP server (this way we avoid a mixed content warning from the browser).</li> </ul> <p>If your server does <em>not</em> support CORS, then you still need to add it to the <code>allowProxyFor</code> whitelist, but do not add it to the <code>corsDomains</code> list. It will then be proxied.</p> <p>Sometimes we deliberately exclude CORS-supporting servers from the <code>corsDomains</code> list; the proxy caches its data, so we leverage its caching to improve performance.</p> <p>In both lists, a server name <code>foo.org</code> will be interpreted as <code>*.foo.org</code>. The port must match exactly. It's not very smart, so if you specify port 80 that won't match a server without a port specified, and vice-versa.</p> <p>The downside to a permissive whitelist is that you'll proxy for more servers, and people could use your proxy to make their (malicious?) traffic look like it's coming from your server instead of from theirs.</p> <h2 id="more-detailed-explanation">More Detailed Explanation</h2> <p>As a general rule, web browsers do not allow web sites running on one host (e.g. <code>nationalmap.gov.au</code>) from accessing data running on another host (e.g. <code>data.gov.au</code>) unless the data server (<code>data.gov.au</code> in our example) explicitly enables a feature called Cross-Origin Resource Sharing (CORS) by including a special HTTP header in its response. Unfortunately, many servers still do not support CORS. If you control the server you're trying to access data on, enabling CORS is almost certainly a good idea, and you can read more about how to do it at <a href="http://enable-cors.org/">enable-cors.org</a>.</p> <p>TerriaJS has a trick to allow it to access data from a server even if that server doesn't support CORS: it uses a proxy server built into <a href="https://github.com/TerriaJS/terriajs-server">terriajs-server</a>, which is included with TerriaMap. The idea is simple: we avoid the need for cross-origin support from servers by running a proxy on the same host that runs our app. That proxy can make requests to <em>other</em> servers on our application's behalf. This works because cross-origin restrictions are a security feature of web browsers, not web servers. The proxy makes it look to the browser like the data comes from the same origin. There's nothing dodgy about this. The risks that browsers are defending against by imposing cross-origin restrictions are not present in this scenario.</p> <p>However, by running a proxy server, our TerriaMap server potentially opens itself up to risks. We don't want people to be able to bounce arbitrary requests through our proxy, because that could be used to make (malicious?) traffic look like it is coming from your server instead of from the real source. This is why <code>terriajs-server</code> uses a whitelist of servers that it is willing to proxy for. The <code>allowProxyFor</code> property in <code>devserverconfig.json</code> specifies the whitelist. If the server is asked to proxy for any server not in the whitelist, the request will be rejected.</p> </article> </div> </div> </main> <footer class="md-footer"> <div class="md-footer-nav"> <nav class="md-footer-nav__inner md-grid"> <a href="../" title="Overview" class="md-flex md-footer-nav__link md-footer-nav__link--prev" rel="prev"> <div class="md-flex__cell md-flex__cell--shrink"> <i class="md-icon md-icon--arrow-back md-footer-nav__button"></i> </div> <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title"> <span class="md-flex__ellipsis"> <span class="md-footer-nav__direction"> Previous </span> Overview </span> </div> </a> <a href="../catalog-groups/" title="Catalog Groups" class="md-flex md-footer-nav__link md-footer-nav__link--next" rel="next"> <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title"> <span class="md-flex__ellipsis"> <span class="md-footer-nav__direction"> Next </span> Catalog Groups </span> </div> <div class="md-flex__cell md-flex__cell--shrink"> <i class="md-icon md-icon--arrow-forward md-footer-nav__button"></i> </div> </a> </nav> </div> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class="md-footer-copyright"> powered by <a href="http://www.mkdocs.org">MkDocs</a> and <a href="https://squidfunk.github.io/mkdocs-material/"> Material for MkDocs</a> </div> </div> </div> </footer> </div> <script src="../../assets/javascripts/application.6cdc17f0.js"></script> <script>app.initialize({version:"0.17.2",url:{base:"../.."}})</script> </body> </html>