diff options
| -rw-r--r-- | README.rst | 2 | ||||
| -rw-r--r-- | doc/source/admin/cross-project-cors.rst | 195 | ||||
| -rw-r--r-- | doc/source/admin/index.rst | 13 | ||||
| -rwxr-xr-x | doc/source/conf.py | 10 | ||||
| -rw-r--r-- | doc/source/configuration/index.rst (renamed from doc/source/oslo_config.rst) | 2 | ||||
| -rw-r--r-- | doc/source/contributor/index.rst (renamed from doc/source/contributing.rst) | 2 | ||||
| -rw-r--r-- | doc/source/glossary.rst | 19 | ||||
| -rw-r--r-- | doc/source/history.rst | 1 | ||||
| -rw-r--r-- | doc/source/index.rst | 14 | ||||
| -rw-r--r-- | doc/source/install/index.rst (renamed from doc/source/installation.rst) | 0 | ||||
| -rw-r--r-- | doc/source/reference/api.rst (renamed from doc/source/api.rst) | 0 | ||||
| -rw-r--r-- | doc/source/reference/cors.rst (renamed from doc/source/cors.rst) | 0 | ||||
| -rw-r--r-- | doc/source/reference/healthcheck_plugins.rst (renamed from doc/source/healthcheck_plugins.rst) | 0 | ||||
| -rw-r--r-- | doc/source/reference/index.rst | 8 | ||||
| -rw-r--r-- | doc/source/user/history.rst | 1 | ||||
| -rw-r--r-- | oslo_middleware/opts.py | 1 | ||||
| -rw-r--r-- | releasenotes/source/conf.py | 11 | ||||
| -rw-r--r-- | test-requirements.txt | 4 |
18 files changed, 265 insertions, 18 deletions
@@ -16,6 +16,6 @@ enhanced with functionality like add/delete/modification of http headers and support for limiting size/connection etc. * Free software: Apache license -* Documentation: https://docs.openstack.org/developer/oslo.middleware +* Documentation: https://docs.openstack.org/oslo.middleware/latest * Source: https://git.openstack.org/cgit/openstack/oslo.middleware * Bugs: https://bugs.launchpad.net/oslo.middleware diff --git a/doc/source/admin/cross-project-cors.rst b/doc/source/admin/cross-project-cors.rst new file mode 100644 index 0000000..26a8c55 --- /dev/null +++ b/doc/source/admin/cross-project-cors.rst @@ -0,0 +1,195 @@ +.. _cross-project: + +============================= +Cross-origin resource sharing +============================= + +.. note:: + + This is a new feature in OpenStack Liberty. + +OpenStack supports :term:`Cross-Origin Resource Sharing (CORS)`, a W3C +specification defining a contract by which the single-origin policy of a user +agent (usually a browser) may be relaxed. It permits the javascript engine +to access an API that does not reside on the same domain, protocol, or port. + +This feature is most useful to organizations which maintain one or more +custom user interfaces for OpenStack, as it permits those interfaces to access +the services directly, rather than requiring an intermediate proxy server. It +can, however, also be misused by malicious actors; please review the +security advisory below for more information. + +Enabling CORS with configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In most cases, CORS support is built directly into the service itself. To +enable it, simply follow the configuration options exposed in the default +configuration file, or add it yourself according to the pattern below. + +.. code-block:: ini + + [cors] + allowed_origin = https://first_ui.example.com + max_age = 3600 + allow_methods = GET,POST,PUT,DELETE + allow_headers = Content-Type,Cache-Control,Content-Language,Expires,Last-Modified,Pragma,X-Custom-Header + expose_headers = Content-Type,Cache-Control,Content-Language,Expires,Last-Modified,Pragma,X-Custom-Header + +Additional origins can be explicitly added. To express this in +your configuration file, first begin with a ``[cors]`` group as above, +into which you place your default configuration values. Then, add as many +additional configuration groups as necessary, naming them +``[cors.{something}]`` (each name must be unique). The purpose of the +suffix to ``cors.`` is legibility, we recommend using a reasonable +human-readable string: + +.. code-block:: ini + + [cors.ironic_webclient] + # CORS Configuration for a hypothetical ironic webclient, which overrides + # authentication + allowed_origin = https://ironic.example.com:443 + allow_credentials = True + + [cors.horizon] + # CORS Configuration for horizon, which uses global options. + allowed_origin = https://horizon.example.com:443 + + [cors.wildcard] + # CORS Configuration for the CORS specified domain wildcard, which only + # permits HTTP GET requests. + allowed_origin = * + allow_methods = GET + +For more information about CORS configuration, +see `cross-origin resource sharing +<https://docs.openstack.org/ocata/config-reference/common-configurations/cors.html>`_ +in OpenStack Configuration Reference. + +Enabling CORS with PasteDeploy +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CORS can also be configured using PasteDeploy. First of all, ensure that +OpenStack's ``oslo_middleware`` package (version 2.4.0 or later) is +available in the Python environment that is running the service. Then, +add the following configuration block to your ``paste.ini`` file. + +.. code-block:: ini + + [filter:cors] + paste.filter_factory = oslo_middleware.cors:filter_factory + allowed_origin = https://website.example.com:443 + max_age = 3600 + allow_methods = GET,POST,PUT,DELETE + allow_headers = Content-Type,Cache-Control,Content-Language,Expires,Last-Modified,Pragma,X-Custom-Header + expose_headers = Content-Type,Cache-Control,Content-Language,Expires,Last-Modified,Pragma,X-Custom-Header + +.. note:: + To add an additional domain in oslo_middleware v2.4.0, add + another filter. In v3.0.0 and after, you may add multiple domains + in the above ``allowed_origin`` field, separated by commas. + +Security concerns +~~~~~~~~~~~~~~~~~ + +CORS specifies a wildcard character ``*``, which permits access to all user +agents, regardless of domain, protocol, or host. While there are valid use +cases for this approach, it also permits a malicious actor to create a +convincing facsimile of a user interface, and trick users into revealing +authentication credentials. Please carefully evaluate your use case and the +relevant documentation for any risk to your organization. + +.. note:: + + The CORS specification does not support using this wildcard as + a part of a URI. Setting ``allowed_origin`` to ``*`` would work, while + ``*.openstack.org`` would not. + +Troubleshooting +~~~~~~~~~~~~~~~ + +CORS is very easy to get wrong, as even one incorrect property will violate +the prescribed contract. Here are some steps you can take to troubleshoot +your configuration. + +Check the service log +--------------------- + +The CORS middleware used by OpenStack provides verbose debug logging that +should reveal most configuration problems. Here are some example log +messages, and how to resolve them. + +Problem +------- + +``CORS request from origin 'http://example.com' not permitted.`` + +Solution +-------- + +A request was received from the origin ``http://example.com``, however this +origin was not found in the permitted list. The cause may be a superfluous +port notation (ports 80 and 443 do not need to be specified). To correct, +ensure that the configuration property for this host is identical to the +host indicated in the log message. + +Problem +------- + +``Request method 'DELETE' not in permitted list: GET,PUT,POST`` + +Solution +-------- + +A user agent has requested permission to perform a DELETE request, however +the CORS configuration for the domain does not permit this. To correct, add +this method to the ``allow_methods`` configuration property. + +Problem +------- + +``Request header 'X-Custom-Header' not in permitted list: X-Other-Header`` + +Solution +-------- + +A request was received with the header ``X-Custom-Header``, which is not +permitted. Add this header to the ``allow_headers`` configuration +property. + +Open your browser's console log +------------------------------- + +Most browsers provide helpful debug output when a CORS request is rejected. +Usually this happens when a request was successful, but the return headers on +the response do not permit access to a property which the browser is trying +to access. + +Manually construct a CORS request +--------------------------------- + +By using ``curl`` or a similar tool, you can trigger a CORS response with a +properly constructed HTTP request. An example request and response might look +like this. + +Request example: + +.. code-block:: console + + $ curl -I -X OPTIONS https://api.example.com/api -H "Origin: https://ui.example.com" + +Response example: + +.. code-block:: console + + HTTP/1.1 204 No Content + Content-Length: 0 + Access-Control-Allow-Origin: https://ui.example.com + Access-Control-Allow-Methods: GET,POST,PUT,DELETE + Access-Control-Expose-Headers: origin,authorization,accept,x-total,x-limit,x-marker,x-client,content-type + Access-Control-Allow-Headers: origin,authorization,accept,x-total,x-limit,x-marker,x-client,content-type + Access-Control-Max-Age: 3600 + +If the service does not return any access control headers, check the service +log, such as ``/var/log/upstart/ironic-api.log`` for an indication on what +went wrong. diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst new file mode 100644 index 0000000..c90230c --- /dev/null +++ b/doc/source/admin/index.rst @@ -0,0 +1,13 @@ +====================== +Cross-project features +====================== + +Many features are common to all the OpenStack services and are consistent in +their configuration and deployment patterns. Unless explicitly noted, you can +safely assume that the features in this chapter are supported and configured +in a consistent manner. + +.. toctree:: + :maxdepth: 2 + + cross-project-cors.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index a5301af..fd0ddce 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -23,11 +23,19 @@ sys.path.insert(0, os.path.abspath('../..')) extensions = [ 'sphinx.ext.autodoc', #'sphinx.ext.intersphinx', - 'oslosphinx', 'oslo_config.sphinxext', + 'openstackdocstheme', 'stevedore.sphinxext', ] +# openstackdocstheme options +repository_name = 'openstack/oslo.middleware' +bug_project = 'oslo.middleware' +bug_tag = '' + +# Must set this variable to include year, month, day, hours, and minutes. +html_last_updated_fmt = '%Y-%m-%d %H:%M' + # autodoc generation is a bit aggressive and a nuisance when doing heavy # text edit cycles. # execute "export SPHINX_DEBUG=1" in your terminal to disable diff --git a/doc/source/oslo_config.rst b/doc/source/configuration/index.rst index e6134a5..6ca076e 100644 --- a/doc/source/oslo_config.rst +++ b/doc/source/configuration/index.rst @@ -53,5 +53,5 @@ This will override any configuration done via oslo.config .. note:: - healtcheck middleware does not yet use oslo.config, see :doc:`healthcheck_plugins` + healtcheck middleware does not yet use oslo.config, see :doc:`../reference/healthcheck_plugins` diff --git a/doc/source/contributing.rst b/doc/source/contributor/index.rst index 2ca75d1..ed5290b 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributor/index.rst @@ -2,4 +2,4 @@ Contributing ============== -.. include:: ../../CONTRIBUTING.rst +.. include:: ../../../CONTRIBUTING.rst diff --git a/doc/source/glossary.rst b/doc/source/glossary.rst new file mode 100644 index 0000000..72e1759 --- /dev/null +++ b/doc/source/glossary.rst @@ -0,0 +1,19 @@ +======== +Glossary +======== + +This glossary offers a list of terms and definitions to define a +vocabulary for OpenStack-related concepts. + +C +~ + +.. glossary:: + + Cross-Origin Resource Sharing (CORS) + + A mechanism that allows many resources (for example, + fonts, JavaScript) on a web page to be requested from + another domain outside the domain from which the resource + originated. In particular, JavaScript's AJAX calls can use + the XMLHttpRequest mechanism. diff --git a/doc/source/history.rst b/doc/source/history.rst deleted file mode 100644 index 69ed4fe..0000000 --- a/doc/source/history.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../ChangeLog diff --git a/doc/source/index.rst b/doc/source/index.rst index f53e5bd..5bf8ff0 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -6,12 +6,12 @@ Contents .. toctree:: :maxdepth: 2 - installation - api - healthcheck_plugins - cors - oslo_config - contributing + install/index + contributor/index + configuration/index + admin/index + reference/index + glossary Release Notes ============= @@ -19,4 +19,4 @@ Release Notes .. toctree:: :maxdepth: 1 - history + user/history diff --git a/doc/source/installation.rst b/doc/source/install/index.rst index 4fd1d47..4fd1d47 100644 --- a/doc/source/installation.rst +++ b/doc/source/install/index.rst diff --git a/doc/source/api.rst b/doc/source/reference/api.rst index 50ad06d..50ad06d 100644 --- a/doc/source/api.rst +++ b/doc/source/reference/api.rst diff --git a/doc/source/cors.rst b/doc/source/reference/cors.rst index 77bb6ed..77bb6ed 100644 --- a/doc/source/cors.rst +++ b/doc/source/reference/cors.rst diff --git a/doc/source/healthcheck_plugins.rst b/doc/source/reference/healthcheck_plugins.rst index 3ea93c5..3ea93c5 100644 --- a/doc/source/healthcheck_plugins.rst +++ b/doc/source/reference/healthcheck_plugins.rst diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst new file mode 100644 index 0000000..5a2d80a --- /dev/null +++ b/doc/source/reference/index.rst @@ -0,0 +1,8 @@ +============================== + oslo.middleware Reference +============================== + +.. toctree:: + :glob: + + * diff --git a/doc/source/user/history.rst b/doc/source/user/history.rst new file mode 100644 index 0000000..f69be70 --- /dev/null +++ b/doc/source/user/history.rst @@ -0,0 +1 @@ +.. include:: ../../../ChangeLog diff --git a/oslo_middleware/opts.py b/oslo_middleware/opts.py index 1584f9b..6cf6f4d 100644 --- a/oslo_middleware/opts.py +++ b/oslo_middleware/opts.py @@ -132,7 +132,6 @@ def list_opts_cors(): """ return [ ('cors', copy.deepcopy(cors.CORS_OPTS)), - ('cors.subdomain', copy.deepcopy(cors.CORS_OPTS)) ] diff --git a/releasenotes/source/conf.py b/releasenotes/source/conf.py index a53fc2c..c450f3a 100644 --- a/releasenotes/source/conf.py +++ b/releasenotes/source/conf.py @@ -34,10 +34,15 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'oslosphinx', 'reno.sphinxext', + 'openstackdocstheme' ] +# openstackdocstheme options +repository_name = 'openstack/oslo.middleware' +bug_project = 'oslo.middleware' +bug_tag = '' + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -109,7 +114,7 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +html_theme = 'openstackdocs' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -147,7 +152,7 @@ html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -# html_last_updated_fmt = '%b %d, %Y' +html_last_updated_fmt = '%Y-%m-%d %H:%M' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. diff --git a/test-requirements.txt b/test-requirements.txt index d51ef3c..fb4395f 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -5,9 +5,9 @@ fixtures>=3.0.0 # Apache-2.0/BSD hacking!=0.13.0,<0.14,>=0.12.0 # Apache-2.0 mock>=2.0 # BSD -oslosphinx>=4.7.0 # Apache-2.0 +openstackdocstheme>=1.11.0 # Apache-2.0 oslotest>=1.10.0 # Apache-2.0 -sphinx!=1.6.1,>=1.5.1 # BSD +sphinx>=1.6.2 # BSD testtools>=1.4.0 # MIT coverage!=4.4,>=4.0 # Apache-2.0 reno!=2.3.1,>=1.8.0 # Apache-2.0 |