# CORS Middleware

This middleware provides a comprehensive, configurable implementation of the CORS (Cross Origin Resource Sharing) specification as oslo-supported python wsgi middleware.

Note

While this middleware supports the use of the * wildcard origin in the specification, this feature is not recommended for security reasons. It is provided to simplify basic use of CORS, practically meaning “I don’t care how this is used.” In an intranet setting, this could lead to leakage of data beyond the intranet and therefore should be avoided.

## Quickstart

First, include the middleware in your application:

    from oslo_middleware import cors

    app = cors.CORS(your_wsgi_application)

Secondly, add as many allowed origins as you would like:

    app.add_origin(allowed_origin=['https://website.example.com:443'],
                   allow_credentials=True,
                   max_age=3600,
                   allow_methods=['GET','PUT','POST','DELETE'],
                   allow_headers=['X-Custom-Header'],
                   expose_headers=['X-Custom-Header'])

    # ... add more origins here.

## Configuration for oslo_config

A factory method has been provided to simplify configuration of your CORS domain, using oslo_config:

    from oslo_middleware import cors
    from oslo_config import cfg

    app = cors.CORS(your_wsgi_application, cfg.CONF)

In your application’s config file, then include a configuration block something like this:

    [cors]
    allowed_origin=https://website.example.com:443,https://website2.example.com:443
    max_age=3600
    allow_methods=GET,POST,PUT,DELETE
    allow_headers=X-Custom-Header
    expose_headers=X-Custom-Header

## Configuration for pastedeploy

If your application is using pastedeploy, the following configuration block will add CORS support.:

    [filter:cors]
    use = egg:oslo.middleware#cors
    allowed_origin=https://website.example.com:443,https://website2.example.com:443
    max_age=3600
    allow_methods=GET,POST,PUT,DELETE
    allow_headers=X-Custom-Header
    expose_headers=X-Custom-Header

If your application is using pastedeploy, but would also like to use the existing configuration from oslo_config in order to simplify the points of configuration, this may be done as follows.:

    [filter:cors]
    use = egg:oslo.middleware#cors
    oslo_config_project = oslo_project_name

    # Optional field, in case the program name is different from the project:
    oslo_config_program = oslo_project_name-api

## Configuration Options

### cors

allowed_origin
  Type:

    list

  Default:

    `<None>`

  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
  Type:

    boolean

  Default:

    `True`

  Indicate that the actual request can include user credentials

expose_headers
  Type:

    list

  Default:

    `[]`

  Indicate which headers are safe to expose to the API. Defaults to HTTP Simple Headers.

max_age
  Type:

    integer

  Default:

    `3600`

  Maximum cache age of CORS preflight requests.

allow_methods
  Type:

    list

  Default:

    `['OPTIONS', 'GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'TRACE', 'PATCH']`

  Indicate which methods can be used during the actual request.

allow_headers
  Type:

    list

  Default:

    `[]`

  Indicate which header field names may be used during the actual request.

## Module Documentation

class oslo_middleware.cors.AllowedOrigin

class oslo_middleware.cors.CORS(application: WSGIApplication | None, conf: dict[str, Any] | cfg.ConfigOpts | None = None)

  CORS Middleware.

  This middleware allows a WSGI app to serve CORS headers for multiple configured domains.

  For more information, see http://www.w3.org/TR/cors/

  add_origin(allowed_origin: list[str], allow_credentials: bool = True, expose_headers: list[str] | None = None, max_age: int | None = None, allow_methods: list[str] | None = None, allow_headers: list[str] | None = None) → None

    Add another origin to this filter.

    Parameters:

      - allowed_origin – Protocol, host, and port for the allowed origin.

      - allow_credentials – Whether to permit credentials.

      - expose_headers – A list of headers to expose.

      - max_age – Maximum cache duration.

      - allow_methods – List of HTTP methods to permit.

      - allow_headers – List of HTTP headers to permit from the client.

    Returns:

  classmethod factory(global_conf: dict[str, Any] | None, **local_conf: Any) → Callable[[WSGIApplication], base.MiddlewareType]

    factory method for paste.deploy

    allowed_origin: Protocol, host, and port for the allowed origin. allow_credentials: Whether to permit credentials. expose_headers: A list of headers to expose. max_age: Maximum cache duration. allow_methods: List of HTTP methods to permit. allow_headers: List of HTTP headers to permit from the client.

  process_response(response: Response, request: Request | None = None) → Response

    Check for CORS headers, and decorate if necessary.

    Perform two checks. First, if an OPTIONS request was issued, let the application handle it, and (if necessary) decorate the response with preflight headers. In this case, if a 404 is thrown by the underlying application (i.e. if the underlying application does not handle OPTIONS requests, the response code is overridden.

    In the case of all other requests, regular request headers are applied.

exception oslo_middleware.cors.InvalidOriginError(origin: str)

  Exception raised when Origin is invalid.

oslo_middleware.cors.filter_factory(global_conf: dict[str, Any] | None, **local_conf: Any) → Callable[[WSGIApplication], base.MiddlewareType]

  factory method for paste.deploy

  allowed_origin: Protocol, host, and port for the allowed origin. allow_credentials: Whether to permit credentials. expose_headers: A list of headers to expose. max_age: Maximum cache duration. allow_methods: List of HTTP methods to permit. allow_headers: List of HTTP headers to permit from the client.

oslo_middleware.cors.set_defaults(**kwargs: Any) → None

  Override the default values for configuration options.

  This method permits a project to override the default CORS option values. For example, it may wish to offer a set of sane default headers which allow it to function with only minimal additional configuration.

  Parameters:

    - allow_credentials (bool) – Whether to permit credentials.

    - expose_headers (List of Strings) – A list of headers to expose.

    - max_age (Int) – Maximum cache duration in seconds.

    - allow_methods (List of Strings) – List of HTTP methods to permit.

    - allow_headers (List of Strings) – List of HTTP headers to permit from the client.

this page last updated: 2026-07-14 20:24:58

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug