Skip to main content
Warning: You are using the test version of PyPI. This is a pre-production deployment of Warehouse. Changes made here affect the production instance of TestPyPI (
Help us improve Python packaging - Donate today!

CORS support for aiohttp

Project Description

CORS support for aiohttp

aiohttp_cors library implements Cross Origin Resource Sharing (CORS) support for aiohttp asyncio-powered asynchronous HTTP server.

Jump directly to Usage part to see how to use aiohttp_cors.

Same-origin policy

Web security model is tightly connected to Same-origin policy (SOP). In short: web pages cannot Read resources which origin doesn’t match origin of requested page, but can Embed (or Execute) resources and have limited ability to Write resources.

Origin of a page is defined in the Standard as tuple (schema, host, port) (there is a notable exception with Internet Explorer: it doesn’t use port to define origin, but uses it’s own Security Zones).

Can Embed means that resource from other origin can be embedded into the page, e.g. by using <script src="...">, <img src="...">, <iframe src="...">.

Cannot Read means that resource from other origin source cannot be obtained by page (source — any information that would allow to reconstruct resource). E.g. the page can Embed image with <img src="...">, but it can’t get information about specific pixels, so page can’t reconstruct original image (though some information from the other resource may still be leaked: e.g. the page can read embedded image dimensions).

Limited ability to Write means, that the page can send POST requests to other origin with limited set of Content-Type values and headers.

Restriction to Read resource from other origin is related to authentication mechanism that is used by browsers: when browser reads (downloads) resource he automatically sends all security credentials that user previously authorized for that resource (e.g. cookies, HTTP Basic Authentication).

For example, if Read would be allowed and user is authenticated in some internet banking, malicious page would be able to embed internet banking page with iframe (since authentication is done by the browser it may be embedded as if user is directly navigated to internet banking page), then read user private information by reading source of the embedded page (which may be not only source code, but, for example, screenshot of the embedded internet banking page).

Cross-origin resource sharing

Cross-origin Resource Sharing (CORS) allows to override SOP for specific resources.

In short, CORS works in the following way.

When page request (Read) resource that have other origin, browser implicitly appends Origin: header to the HTTP request, effectively requesting server to give read permission for the resource to the page:

GET /resource HTTP/1.1

If server allows access from the page to the resource, it responds with resource with Access-Control-Allow-Origin: HTTP header (optionally allowing exposing custom server headers to the page and enabling use of the user credentials on the server resource):

Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: X-Server-Header

Browser checks, if server responded with proper Access-Control-Allow-Origin header and accordingly allows or denies access for the obtained resource to the page.

CORS specification designed in a way that servers that are not aware of CORS will not expose any additional information, except allowed by the SOP.

To request resources with custom headers or using custom HTTP methods (e.g. PUT, DELETE) that are not allowed by SOP, CORS-enabled browser first send preflight request to the resource using OPTIONS method, in which he queries access to the resource with specific method and headers:

Access-Control-Request-Method: PUT
Access-Control-Request-Headers: X-Client-Header

CORS-enabled server responds is requested method is allowed and which of the specified headers are allowed:

Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: PUT
Access-Control-Allow-Headers: X-Client-Header
Access-Control-Max-Age: 3600

Browser checks response to preflight request, and, if actual request allowed, does actual request.


You can install aiohttp_cors as a typical Python library from PyPI or from git:

$ pip install aiohttp_cors

Note that aiohttp_cors requires versions of Python >= 3.4.1 and aiohttp >= 0.18.0.


To use aiohttp_cors you need to configure the application and enable CORS on routes of resources that you want to expose:

import asyncio
from aiohttp import web
import aiohttp_cors

def handler(request):
    return web.Response(
            "X-Custom-Server-Header": "Custom data",

app = web.Application()

# `aiohttp_cors.setup` returns `aiohttp_cors.CorsConfig` instance.
# The `cors` instance will store CORS configuration for the
# application.
cors = aiohttp_cors.setup(app)

# To enable CORS processing for specific route you need to add
# that route to the CORS configuration object and specify it's
# CORS options.
    app.router.add_route("GET", "/hello", handler), {
        "": aiohttp_cors.ResourceOptions(
            allow_headers=("X-Requested-With", "Content-Type"),

Each route has it’s own CORS configuration passed in CorsConfig.add() method. CORS configuration is a mapping from origins to options for that origins.

In the example above CORS is configured for the resource under path /hello and HTTP method GET, and in the context of CORS:

  • This resource will be available using CORS only to origin.
  • Passing of credentials to this resource will be allowed.
  • The resource will expose to the client X-Custom-Server-Header server header.
  • The client will be allowed to pass X-Requested-With and Content-Type headers to the server.
  • Preflight requests will be allowed to be cached by client for 3600 seconds.

Resource will be available only to the explicitly specified origins. You can specify “all other origins” using special * origin:

cors.add(route, {

Here the resource specified by route will be available to all origins with disallowed credentials passing, and with allowed credentials passing only to

By default ResourceOptions will be constructed without any allowed CORS options. This means, that resource will be available using CORS to specified origin, but client will not be allowed to send either credentials, or send non-simple headers, or read from server non-simple headers.

To enable sending or receiving all headers you can specify special value * instead of sequence of headers:

cors.add(route, {

You can specify default CORS-enabled resource options using aiohttp_cors.setup()’s defaults argument:

cors = aiohttp_cors.setup(app, defaults={
        # Allow all to read all CORS-enabled resources from
        "": aiohttp_cors.ResourceOptions(),

# Enable CORS on resources.

# According to defaults POST and PUT will be available only to
# "".
cors.add(app.router.add_route("POST", "/hello", handler_post))
cors.add(app.router.add_route("PUT", "/hello", handler_put))

# In addition to "", GET request will be allowed
# from "" origin.
cors.add(app.router.add_route("GET", "/hello", handler), {

# CORS will be enabled only on the resources added to `CorsConfig`,
# so following resource will be NOT CORS-enabled.
app.router.add_route("GET", "/private", handler))

Here is an example of how to enable CORS for all origins with all CORS features:

cors = aiohttp_cors.setup(app, defaults={
    "*": aiohttp_cors.ResourceOptions(

# Add all resources to `CorsConfig`.
cors.add(app.router.add_route("GET", "/hello", handler_get))
cors.add(app.router.add_route("PUT", "/hello", handler_put))
cors.add(app.router.add_route("POST", "/hello", handler_put))
cors.add(app.router.add_route("DELETE", "/hello", handler_delete))


TODO: fill this



To run run Selenium tests with Firefox web driver you need to install Firefox.

To run run Selenium tests with Chromium web driver you need to:

  1. Install Chrome driver. On Ubuntu 14.04 it’s in chromium-chromedriver package.
  2. Either add chromedriver to PATH or set WEBDRIVER_CHROMEDRIVER_PATH environment variable to chromedriver, e.g. on Ubuntu 14.04 WEBDRIVER_CHROMEDRIVER_PATH=/usr/lib/chromium-browser/chromedriver.


Copyright 2015 Vladimir Rutsky <>.

Licensed under the Apache License, Version 2.0, see LICENSE file for details.


0.1.0 (2015-11-05)

  • Initial release.
Release History

Release History

This version
History Node


Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting