[api-quick-start]Make cors work better.

[OpenStack Infra]

https://review.openstack.org/69419
commit 2abb829a5dd965b99bc8f18f13c3bfbe1ece27b2
Author: David Goetz <email address hidden>
Date: Wed Jan 15 14:49:31 2014 -0800

    Make cors work better.

    CORS doesn't really work with swift right now. OPTIONS calls for the most part
    work but for so called "simple cross-site requests" (i.e. those that don't
    require a pre-flight OPTIONS request) Swift always returns the Origin it was
    given as the Access-Control-Allow-Origin in the response. This makes CORS
    "work" for these requests but if you actually wanted the javascript user agent
    to restrict anything for you it wouldn't be able to!

    You can duplicate the issue with updated CORS test page:

    http://docs.openstack.org/developer/swift/cors.html#test-cors-page

    And a public container with an 'X-Container-Meta-Access-Control-Allow-Origin'
    that does NOT match the webserver hosting the test-cors-page.

    e.g.

    with a public container that accepts cross-site requests from "example.com":

    `swift post cors-container -m access-control-allow-origin:example.com -r .r:*`

    You could point your browser at a copy of the test-cors-page on your
    filesystem (the browser will will send 'Origin: null')

    Without a token the XMLHttpRequest will not request any custom headers (i.e.
    Access-Control-Request-Headers: x-auth-token) and the request will be made
    with-out a preflight OPTIONS request (which Swift would have denied anyway
    because the origin's don't match)

    i.e. fill in "http://saio:8080/v1/AUTH_test/cors-container" for "URL" and
    leave "Token" blank.

    You would expect that the browser would not complete the request because
    "Origin: null" does not match the configured "Access-Control-Allow-Origin:
    example.com" on the container metadata, and indeed with this patch - it won't!

    Also:

    The way cors is set up does not play well with certain applications for swift.
    If you are running a CDN on top of swift and you have the
    Access-Control-Allow-Origin cors header set to * then you probably want the *
    to be cached on the the CDN, not the Origin that happened to result in an
    origin request.

    Also:

    If you were unfortunate enough to allow cors headers to be saved directly
    onto objects then this allows them to supersede the headers coming from the
    container.

    NOTE: There is a change is behavior with this patch. Because its cors, a
          spec that was created only to cause annoyance to all, I'll write out
          what's being changed and hopefully someone will speak up if it breaks
          there stuff.

    previous behavior: When a request was made with a Origin header set the
                       cors_validation decorator would always add that origin as
                       the Access-Control-Allow-Origin header in the response-
                       whether the passed origin was a match with the container's
                       X-Container-Meta-Access-Control-Allow-Origin or not, or even
                       if the container did not have CORS set up at all.
    new behavior: If strict_cors_mode is set to True in the proxy-server.conf
                  (which is the default) the cors_validation decorator will only
                  add the Access-Control-Allow-Origin header to the response when
                  the request's Origin matches the value set in
                  X-Container-Meta-Access-Control-Allow-Origin. NOTE- if the
                  container does not have CORS set up it won't just magically start
                  working. Furthremore, if the Origin doesn't match the
                  Access-Control-Allow-Origin - a successfully authorized request
                  (either by token or public ACL) won't be *denied* - it just
                  won't include the Access-Control-Allow-Origin header (it's up
                  to the security model in the browser to cancel the request
                  if the response doesn't include a matching Allow-Origin
                  header). On the other hand, if you want to restrict requests
                  with CORS, you can actually do it now.

                  If you are worried about breaking current functionality you
                  must set:

                  strict_cors_mode = False

                  in the proxy-server.conf. This will continue with returning the
                  passed in Origin as the Access-Control-Allow-Origin in the
                  response.

    previous: If you had X-Container-Meta-Access-Control-Allow-Origin set to *
              and you passed in Origin: http://hey.com you'd get
              Access-Control-Allow-Origin: http://hey.com back. This was true for
              both OPTIONS and regular reqs.
    new: With X-Container-Meta-Access-Control-Allow-Origin set to * you get * back
         for both OPTIONS and regular reqs.

    previous: cors headers saved directly onto objects (by allowing them to be
              saved via the allowed_headers config in the object-server conf)
              would be overridden by whatever container cors you have set up.
    new: For regular (non-OPTIONS) calls the object headers will be kept. The
         container cors will only be applied to objects without the
         'Access-Control-Allow-Origin' and 'Access-Control-Expose-Headers' headers.
         This behavior doesn't make a whole lot of sense for OPTIONS calls so I
         left that as is. I don't think that allowing cors headers to be saved
         directly onto objects is a good idea and it should be discouraged.

    DocImpact

    Change-Id: I9b0219407e77c77a9bb1133cbcb179a4c681c4a8

[Atsushi SAKAI (sakaia)]

I think CORS mechanism is not related to api-reference.
It should be systematically documented (how to) on api-guide, or somthing.

Ref.
http://www.html5rocks.com/en/tutorials/cors/

[Alexandra Settle (alexandra-settle)]

This needs to be documented in the api-guide and currently there is no real need for this to be documented in the OS docs.

[Anne Gentle (annegentle)]

CORS headers here: https://review.openstack.org/#/c/290641/ in the API reference.

Yes, this information belongs in this guide: http://developer.openstack.org/api-guide/quick-start/ which is sourced here:

https://github.com/openstack/api-site/blob/master/api-quick-start/source/api-quick-start.rst

[Anne Gentle (annegentle)]

This can stay.