02c49fe3f7
The "enabled" config option has been removed already. Change-Id: I35586d11e93b6d62513738dd6263e6fe1032d2af
120 lines
3.7 KiB
ReStructuredText
120 lines
3.7 KiB
ReStructuredText
..
|
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
not use this file except in compliance with the License. You may obtain
|
|
a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
License for the specific language governing permissions and limitations
|
|
under the License.
|
|
|
|
==========
|
|
CORS Guide
|
|
==========
|
|
|
|
Zaqar supports Cross-Origin Resource Sharing (CORS) now. The function is
|
|
provided by oslo.middleware. Please see `Official Doc`_ and `OpenStack Spec`_
|
|
for more detail. This guide is mainly tell users how to use it in Zaqar.
|
|
|
|
|
|
New Config Options
|
|
------------------
|
|
|
|
There are some new config options.
|
|
|
|
**allowed_origin**
|
|
|
|
Indicate whether this resource may be shared with the domain received in the
|
|
requests "origin" header. Format: "<protocol>://<host>[:<port>]", no trailing
|
|
slash. Example: https://horizon.example.com'.
|
|
|
|
**allow_credentials**
|
|
|
|
Indicate that the actual request can include user credentials. The default
|
|
value is True.
|
|
|
|
**expose_headers**
|
|
|
|
Indicate which headers are safe to expose to the API. Defaults to HTTP Simple
|
|
Headers. The default value is [].
|
|
|
|
**max_age**
|
|
|
|
Maximum cache age of CORS preflight requests. The default value is 3600.
|
|
|
|
**allow_methods**
|
|
|
|
Indicate which methods can be used during the actual request. The default value
|
|
is ['OPTIONS', 'GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'TRACE', 'PATCH'].
|
|
|
|
**allow_headers**
|
|
|
|
Indicate which header field names may be used during the actual request. The
|
|
default value is [].
|
|
|
|
|
|
Request and Response example
|
|
----------------------------
|
|
The CORS feature is enabled by default in Zaqar. Here is a config example:::
|
|
|
|
[cors]
|
|
allowed_origin = http://example
|
|
allow_methods = GET
|
|
|
|
the above example config options mean that Zaqar only receive the GET request
|
|
from http://example domain. Here are some example request:
|
|
1. Zaqar will do nothing if the request doesn't contain "Origin" header::
|
|
|
|
# curl -I -X GET http://10.229.47.217:8888 -H "Accept: application/json"
|
|
|
|
HTTP/1.1 300 Multiple Choices
|
|
content-length: 668
|
|
content-type: application/json; charset=UTF-8
|
|
Connection: close
|
|
|
|
2. Zaqar will return nothing in response headers if the "Origin" is not in
|
|
``allowed_origin``::
|
|
|
|
# curl -I -X GET http://10.229.47.217:8888 -H "Accept: application/json" -H "Origin: http://"
|
|
|
|
HTTP/1.1 300 Multiple Choices
|
|
content-length: 668
|
|
content-type: application/json; charset=UTF-8
|
|
Connection: close
|
|
|
|
In the Zaqar log, we can see a message::
|
|
|
|
CORS request from origin 'http://' not permitted.
|
|
|
|
3. Zaqar will return CORS information if the "Origin" header is in
|
|
``allowed_origin``::
|
|
|
|
# curl -I -X GET http://10.229.47.217:8888 -H "Accept: application/json" -H "Origin: http://example"
|
|
|
|
HTTP/1.1 300 Multiple Choices
|
|
content-length: 668
|
|
content-type: application/json; charset=UTF-8
|
|
Vary: Origin
|
|
Access-Control-Allow-Origin: http://example
|
|
Access-Control-Allow-Credentials: true
|
|
Connection: close
|
|
|
|
4. Zaqar will return more information if the request doesn't follow Zaqar's\
|
|
CORS rule::
|
|
|
|
# curl -I -X PUT http://10.229.47.217:8888 -H "Accept: application/json" -H "Origin: http://example"
|
|
HTTP/1.1 405 Method Not Allowed
|
|
content-length: 0
|
|
content-type: application/json; charset=UTF-8
|
|
allow: GET, OPTIONS
|
|
Vary: Origin
|
|
Access-Control-Allow-Origin: http://example
|
|
Access-Control-Allow-Credentials: true
|
|
Connection: close
|
|
|
|
.. _Official Doc: https://docs.openstack.org/oslo.middleware/latest/reference/cors.html
|
|
.. _OpenStack Spec: https://specs.openstack.org/openstack/openstack-specs/specs/cors-support.html
|