|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: Configuring Server CORS |
| 4 | +nav_order: 4 |
| 5 | +permalink: /docs/cors-settings |
| 6 | +--- |
| 7 | + |
| 8 | +ReplayWeb.page doesn't require any specific server side settings, just the ability to server file and respond to `Range` requests, |
| 9 | +loading parts of files. It can load files from any web server. However, a common obstacle is configuring CORS settings to give |
| 10 | +ReplayWeb.page access to the data. |
| 11 | + |
| 12 | +# Configuring CORS |
| 13 | + |
| 14 | +Browsers restrict access to files hosted on a different domain than the websites that is trying to load them for security reasons. |
| 15 | + |
| 16 | +If you are loading web archives hosted on a different domain (for example, S3 or other cloud storage) and your site is hosted on a different domain, |
| 17 | +the site hosting the file needs to 'allow' the website to load the file using special CORS (Cross-Origin Resource Sharing) headers. |
| 18 | + |
| 19 | +These settings apply whenever the archive is hosted on a different domain than the viewer, so if you are loading via our main ReplayWeb.page site, you need to grant access to *https://replayweb.page* to load these archives. |
| 20 | + |
| 21 | +The minimum requirement is to return an `Access-Control-Allow-Origin: https://replayweb.page` and most CORS settings include at least this option. |
| 22 | + |
| 23 | +## Differences between Chrome and Firefox and Safari |
| 24 | + |
| 25 | +Unfortunately, different browsers have diverged in how they handle in enforcing the CORS policy. |
| 26 | + |
| 27 | +At the moment, it seems Firefox and Safari sometimes send a [pre-flight OPTIONS request](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request) when handling ReplayWeb.page requests, because the ReplayWeb.page uses the `Range` header. |
| 28 | + |
| 29 | +Chrome currently considers it a 'safe' header, but the other browsers have not yet made this change. |
| 30 | + |
| 31 | +To be compatible with all browsers, we recommend including all headers as 'allowed headers' for use with ReplayWeb.page, eg. |
| 32 | +by setting `Access-Control-Allow-Headers: '*'` as part of the CORS response in addition to `Access-Control-Allow-Origin`. |
| 33 | + |
| 34 | +The following provides different ways of configuring CORS for different hosting environments. |
| 35 | + |
| 36 | + |
| 37 | +## S3 and Compatible Configurations |
| 38 | + |
| 39 | +If you are hosting from S3 or S3-compatible service, here are a few CORS bucket configurations that should work. |
| 40 | + |
| 41 | +Amazon S3 and other services now support a JSON based bucket policy, as well as an older XML-based policy. |
| 42 | + |
| 43 | +The below examples provide access to `https://replayweb.page` to load your archive. |
| 44 | +If you are instead [embedding replayweb.page](./embedding), replace that with the server (origin) of the URL where the `<replay-web-page>` embed is hosted. |
| 45 | + |
| 46 | +Both JSON and XML options provide a way to specify multiple origins via the JSON list or multiple `<AllowedOrigin>` tags |
| 47 | + |
| 48 | +### JSON-Based Configuration |
| 49 | + |
| 50 | +The JSON-based configuration will look as follows: |
| 51 | + |
| 52 | +```json |
| 53 | +[ |
| 54 | + { |
| 55 | + "AllowedOrigins": [ |
| 56 | + "https://replayweb.page" |
| 57 | + ], |
| 58 | + "AllowedMethods": [ |
| 59 | + "GET", |
| 60 | + "HEAD" |
| 61 | + ], |
| 62 | + "AllowedHeaders": [ |
| 63 | + "*" |
| 64 | + ] |
| 65 | + } |
| 66 | +] |
| 67 | +``` |
| 68 | + |
| 69 | +### XML-Based Configuration |
| 70 | + |
| 71 | + |
| 72 | +```xml |
| 73 | +<CORSConfiguration |
| 74 | +xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> |
| 75 | +<CORSRule> |
| 76 | + <AllowedMethod>GET</AllowedMethod> |
| 77 | + <AllowedMethod>HEAD</AllowedMethod> |
| 78 | + <AllowedOrigin>https://replayweb.page</AllowedOrigin> |
| 79 | + <AllowedHeader>*</AllowedHeader> |
| 80 | + <ExposeHeader>Content-Range</ExposeHeader> |
| 81 | + <ExposeHeader>Content-Encoding</ExposeHeader> |
| 82 | + <ExposeHeader>Content-Length</ExposeHeader> |
| 83 | +</CORSRule> |
| 84 | +</CORSConfiguration> |
| 85 | +``` |
| 86 | + |
| 87 | +One way to set this policy is to use the popular [s3cmd](https://s3tools.org/usage) command-line tool: |
| 88 | + |
| 89 | +1) Paste the above snippet into a file, eg. `cors.xml` |
| 90 | +2) Be sure to set the 'Allowed Origin' to the site hosting the embed. You can add as many of these as necessary. |
| 91 | +3) Run `s3cmd setcors ./cors.xml s3://<your-bucket>` |
| 92 | + |
| 93 | +See the s3cmd docs for how to configure it s3cmd to work with your setup. |
| 94 | + |
| 95 | +See [S3 Docs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ManageCorsUsing.html) for more info on how to set this policy. |
| 96 | + |
| 97 | +Other cloud providers may have a similar settings for configuring CORS. |
| 98 | + |
| 99 | +## Manual Setup / Nginx |
| 100 | + |
| 101 | +The recommended setup for nginx is to include the following CORS settings. |
| 102 | +As above, you can replay `https://replayweb.page` with your domain: |
| 103 | + |
| 104 | +```nginx |
| 105 | +location / { |
| 106 | + if ($request_method = 'OPTIONS') { |
| 107 | + add_header 'Access-Control-Allow-Origin' 'https://replayweb.page'; |
| 108 | + add_header 'Access-Control-Allow-Methods' 'GET, HEAD, OPTIONS' always; |
| 109 | + add_header 'Access-Control-Allow-Headers' '*' |
| 110 | + return 204; |
| 111 | + } |
| 112 | +
|
| 113 | + if ($request_method = 'GET') { |
| 114 | + add_header 'Access-Control-Allow-Origin' 'https://replayweb.page' always; |
| 115 | + add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always; |
| 116 | + add_header 'Access-Control-Allow-Headers' '*' always; |
| 117 | + add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always; |
| 118 | + } |
| 119 | +} |
| 120 | +``` |
| 121 | + |
| 122 | +For more examples of CORS configurations for different servers, see: [https://enable-cors.org/](https://enable-cors.org/) |
| 123 | + |
| 124 | + |
0 commit comments