Configuring (CORS) on a DreamObjects bucket

Overview

This article explains how to set up a Cross-Origin Resource Sharing (CORS) policy on a DreamObjects bucket. This allows you to use data stored in DreamObjects in your website. 

Cross Origin Resource Sharing (CORS) allows restricted resources from one source (a website or DreamObjects) to be requested from another domain outside the domain from which it was originally served.

This example explains how this works:

  • Site A adds CORS headers to allow site B access to a resource on site A, such as a font.
  • Site B can then access that resource due to the CORS header.

Without the CORS header, Site B would not be able to access the resource on Site A.

DreamObjects CORS usage

DreamObjects buckets do not have a CORS policy by default. You must add one in order to use your DreamObjects data on your website.

A CORS configuration on DreamObjects:

  • includes what site a request is for as well as what type of request,
  • is handled individually for each bucket, and
  • uses the Amazon S3 syntax for CORS configuration.

Rules for CORS policies

The following are the general rules for making a CORS configuration:

  • A valid CORS configuration consists of 0 to 100 CORS rules.
  • Each rule must include at least one origin.
  • An origin may contain at most one wildcard *
  • Each rule must include at least one method.
  • The supported methods are: GET, HEAD, PUT, POST, DELETE.
  • Each rule may contain an identifying string of up to 255 characters.
  • Each rule may specify zero or more allowed request headers (which the client may include in the request).
  • Each rule may specify zero or more exposed response headers (which are sent back from the server to the client).
  • Each rule may specify a cache validity time of zero or more seconds. If not included, the client should supply its own default.

Deploying a CORS configuration

A CORS policy can be deployed using a client or a command-line tool. The code can either be in XML or JSON format.

  • If you use a client, the CORS policy is added within the client software.
  • If you use a command-line tool, you must create a file with the CORS rules yourself. The command then uses this file to update the DreamObjects bucket's CORS policy.

Clients

Not all S3 clients support deploying CORS configurations. You would need to check the client's website to confirm if it supports CORS. The following client is one example that supports CORS:

Command-line tools

You can also use command-line tools like s3cmd and aws-cli to update your CORS policy as shown below.

Examples of CORS policies

WebFont policy in (XML format)

If you need to host a WebFont on DreamObjects, you’ll want to include a policy such as the following example (assuming your site is www.example.com and also works at example.com):

<CORSConfiguration>
<CORSRule>
    <ID>Allow WebFont for example.com</ID>
    <AllowedOrigin>https://www.example.com</AllowedOrigin>
    <AllowedOrigin>http://www.example.com</AllowedOrigin>
    <AllowedOrigin>https://example.com</AllowedOrigin>
    <AllowedOrigin>http://example.com</AllowedOrigin>
    <AllowedMethod>GET</AllowedMethod>
    <AllowedMethod>HEAD</AllowedMethod>
    <AllowedHeader>Content-*</AllowedHeader>
    <AllowedHeader>Host</AllowedHeader>
    <ExposeHeader>ETag</ExposeHeader>
    <MaxAgeSeconds>86400</MaxAgeSeconds>
</CORSRule>
</CORSConfiguration>

Example AWS S3 JS policy (in XML format)

The following policy permits users of the AWS S3 JavaScript SDK, on both example.com and www.example.com as well as both HTTP and HTTPS, to upload to DreamObjects, with both the PUT and POST methods:

<CORSConfiguration>
<CORSRule>
    <ID>example.com: Allow PUT and POST with AWS S3 JS SDK</ID>
    <AllowedOrigin>https://www.example.com</AllowedOrigin>
    <AllowedOrigin>http://www.example.com</AllowedOrigin>
    <AllowedOrigin>https://example.com</AllowedOrigin>
    <AllowedOrigin>http://example.com</AllowedOrigin>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedMethod>POST</AllowedMethod>
    <AllowedHeader>Origin</AllowedHeader>
    <AllowedHeader>Content-Length</AllowedHeader>
    <AllowedHeader>Content-Type</AllowedHeader>
    <AllowedHeader>Content-MD5</AllowedHeader>
    <AllowedHeader>X-Amz-User-Agent</AllowedHeader>
    <AllowedHeader>X-Amz-Date</AllowedHeader>
    <AllowedHeader>Authorization</AllowedHeader>
    <ExposeHeader>ETag</ExposeHeader>
    <MaxAgeSeconds>1800</MaxAgeSeconds>
</CORSRule>
<CORSRule>
    <ID>example.com: Allow GET with AWS S3 JS SDK</ID>
    <AllowedOrigin>*</AllowedOrigin>
    <AllowedMethod>GET</AllowedMethod>
    <AllowedMethod>HEAD</AllowedMethod>
    <AllowedHeader>*</AllowedHeader>
    <ExposeHeader>ETag</ExposeHeader>
    <MaxAgeSeconds>1800</MaxAgeSeconds>
</CORSRule>
</CORSConfiguration>

Example Wildcard policy (INSECURE!)

The following policy, while completely insecure, allows ALL methods from any origin. It does NOT however expose custom headers:

<CORSConfiguration>
<CORSRule>
    <ID>Allow
    everything</ID>
    <AllowedOrigin>*</AllowedOrigin>
    <AllowedMethod>GET</AllowedMethod>
    <AllowedMethod>HEAD</AllowedMethod>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedMethod>POST</AllowedMethod>
    <AllowedMethod>DELETE</AllowedMethod>
    <AllowedHeader>*</AllowedHeader>
    <MaxAgeSeconds>30</MaxAgeSeconds>
</CORSRule>
</CORSConfiguration>

s3cmd — deploying a CORS policy

S3cmd is a command-line tool you can use to manage your DreamObjects data. It is not installed by default on DreamHost servers, so you must install it manually.

Make sure you have a working installation of S3cmd before proceeding.

The example below creates a corsrules.xml file in your user's home directory, but you can add it anywhere you like. You would just need to update the path to the file in the command if you change this location.

Make sure to change my-bucket to the name of your DreamObjects bucket.

This example uses an XML file containing your CORS policy.

You can run these commands on a Mac or Linux computer, or your DreamHost server after logging in via SSH. These examples run the command on the server.

  1. Log in to your DreamHost server via SSH.
  2. Make sure you're in your user's home directory. 
    [server]$ cd ~
  3. Run the following to view your bucket's current CORS policy: 
    [server]$ s3cmd info s3://my-bucket
   Location:  us-east-1
   Payer:     BucketOwner
   Expiration Rule: none
   Policy:    none
   CORS:      none
   ACL:       *anon*: READ
   ACL:       my_user: FULL_CONTROL
   URL:       http://my-bucket.objects-us-east-1.dream.io/
    This output shows that no CORS policy has been added yet.
  4. Create an XML file named corsrules.xml with the following content. Make sure to change the AllowedOrigin value to your website name. 
    <CORSConfiguration>
<CORSRule>
    <ID>Alloweverything</ID>
    <AllowedOrigin>http://example.com</AllowedOrigin>
        <AllowedOrigin>https://example.com</AllowedOrigin>
    <AllowedMethod>GET</AllowedMethod>
    <AllowedHeader>*</AllowedHeader>
    <MaxAgeSeconds>3000</MaxAgeSeconds>
</CORSRule>
</CORSConfiguration>
  5. Run the setcors command. This uses the corsrules.xml file to set the CORS policy. 
    [server]$ s3cmd setcors corsrules.xml s3://my-bucket
  6. Run the info command again to view your CORS configuration. You should see your new policy displayed. 
    [server]$ s3cmd info s3://bucketname
   Location:  us-east-1
   Payer:     BucketOwner
   Expiration Rule: none
   Policy:    none
   CORS:      <CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"><CORSRule>
                  <ID>Alloweverything</ID><AllowedMethod>GET</AllowedMethod>
                  <AllowedOrigin>http://example.com</AllowedOrigin>
                  <AllowedOrigin>https://example.com</AllowedOrigin>
                  <AllowedHeader>*</AllowedHeader><MaxAgeSeconds>3000</MaxAgeSeconds>
                  </CORSRule></CORSConfiguration>    
   ACL:       *anon*: READ
   ACL:       my_user: FULL_CONTROL
   URL:       http://my-bucket.objects-us-east-1.dream.io/

If necessary, you can run the following to delete your bucket's CORS policy:

[server]$ s3cmd delcors s3://my-bucket

AWS CLI — deploying a CORS policy

AWS CLI is a command-line tool you can use to manage your DreamObjects data and is installed by default on DreamHost servers.

aws-cli is installed by default on all DreamHost servers.

The example below creates a cors.json file in your user's home directory, but you can add it anywhere you like. You would just need to update the path to the file in the command if you change this location.

Make sure to change my-bucket to the name of your DreamObjects bucket.

This example uses a JSON containing your CORS policy.

You can run these commands on a Mac or Linux computer, or your DreamHost server after logging in via SSH. These examples run the command on the server.

  1. Log in to your DreamHost server via SSH.
  2. Make sure you're in your user's home directory. 
    [server]$ cd ~
  3. Create a JSON file named cors.json with the following content. Make sure to change the AllowedOrigins value to your website name. 
    {
  "CORSRules": [
    {
      "AllowedOrigins": ["http://example.com"],
          "AllowedOrigins": ["https://example.com"],
      "AllowedHeaders": ["*"],
      "AllowedMethods": ["GET"],
      "MaxAgeSeconds": 3000,
      "ExposeHeaders": []
    }
  ]
}
  4. Run the following command to view your current CORS configuration for your bucket: 
    [server]$ aws s3api get-bucket-cors --endpoint-url https://objects-us-east-1.dream.io --bucket my-bucket
    If there is currently no CORS policy configured, the following error appears: 
    An error occurred (NoSuchCORSConfiguration) when calling the GetBucketCors operation: Unknown
    Ignore this and proceed with the following step.
  5. Run the put-bucket-cors command. This uses the cors.json file to set the CORS policy. 
    [server]$ aws s3api put-bucket-cors --endpoint-url https://objects-us-east-1.dream.io --bucket my-bucket --cors-configuration file://cors.json
  6. Run the command to view your CORS configuration again. You should see your new policy displayed.

If necessary, you can run the following to delete your bucket's CORS policy:

[server]$ aws s3api delete-bucket-cors --endpoint-url https://objects-us-east-1.dream.io --bucket s3://my-bucket

See also

 
 

Did this article answer your questions?

Article last updated PST.

Still not finding what you're looking for?

Contact Support

Status Updates

Go subscribe

ARTICLES & TUTORIALS

Visit the Blog

COMPANY ANNOUNCEMENTS

Visit DreamHost News