zaqar/doc/source/CORS.rst

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.

enabled

Enables CORS functions for Zaqar. The default value is "False" at this moment. It will be turn to "True" in the future once it's stable enough.

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

To use CORS, you should make sure that the feature is enabled:

[cors]
enabled = true
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'sCORS 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