simonw / asgi-cors

ASGI middleware for applying CORS headers to an ASGI application

asgi-cors

ASGI middleware for applying CORS headers to an ASGI application.

Installation

pip install asgi-cors

Some background on CORS

CORS stands for Cross-Origin Resource Sharing. It is a web standard that allows applications to opt-in to allowing JavaScript running on other domains to make fetch() calls that can retrieve data from the application.

See MDN's CORS article for more background.

The easiest way to allow scripts running on other domains to access data from an application is to add the following HTTP header:

Access-Control-Allow-Origin: *

This will allow scripts running on ANY domain to make fetch() calls against the application. For public data this is often fine, but there are situations where this may not be what you want to do: one example might be code that runs behind a VPN and needs to allow specific, trusted hosts to load data without opening itself up to every site on the internet.

For these cases, the server needs to inspect the Origin header from the client and return that Origin in the above header. For example, an incoming request from http://localhost:8000 might be judged as trusted - in which case the application server needs to reply like so:

Access-Control-Allow-Origin: http://localhost:8000

Note that the Access-Control-Allow-Origin header can only return a single value. This means that if you want to allow requests from multiple origins you need to dynamically allowlist those origins and return a different header value depending on the incoming request.

Additionally if specific HTTP methods should be allowed an application should add:

Access-Control-Allow-Methods: GET, OPTIONS

Here GET and OPTIONS are allowed.

Similarly specific headers can be allowed:

Access-Control-Allow-Headers: content-type, Authorization

In this case content-type and Authorization headers are allowed to be sent to the server in a CORS request.

Verbs other than GET (such as POST) will trigger a preflight request. This is an OPTIONS request that the browser sends to the server to ask if the server will accept the request.

The access-control-max-age header can be used to specify how long the results of a preflight request can be cached. This can reduce the number of requests made to the server.

How to use this middleware

We will assume you have an existing ASGI app, in a variable called app.

First, import the asgi_cors function:

from asgi_cors import asgi_cors

To enable CORS headers for everywhere (by adding the Access-Control-Allow-Origin: * header to every request), do this:

app = asgi_cors(app, allow_all=True)

If you wish to only allow it from a specific host, use the following:

app = asgi_cors(app, hosts=[
    "https://www.example.com"
])

Now JavaScript executing on https://www.example.com will be able to call your API. You can test this out by opening up example.com in your browser, opening your browser's devtools console and pasting in the following JavaScript:

fetch("https://your-api.com/").then(r => r.json()).then(d => console.log(d))

You can include multiple hosts in the list.

If you want to open your application up to requests from a wildcard-defined selection of hosts, use the following:

app = asgi_cors(app, host_wildcards=[
    "http://localhost:800*",
    "http://*.example.com"
])

This will enable access from any JavaScript running on a local host server on ports 8000 through 8009 - or from any subdomain of example.com.

If you need to do something more complicated that cannot be expressed using the hosts= or host_wildcards= parameters, you can use callback= to specify a custom function. For example:

def validate_origin(origin):
    return origin.startswith("https://")

app = asgi_cors(app, callback=validate_origin)

Your callback function will be passed the Origin header that was passed in by the browser. Both regular and async functions are supported.

To add specific allowed headers or methods you can specify them with the headers= and methods= parameters:

app = asgi_cors(app, methods=[
    "GET", "OPTIONS"
], headers=[
    "Authorization","content-type"
])

To set a access-control-max-age header, use the max_age= parameter:

app = asgi_cors(app, host_wildcards=["*"], max_age=3600)

Using the middleware as a decorator

If you are defining your ASGI application directly as a function, you can use the asgi_cors_decorator function decorator like so:

from asgi_cors import asgi_cors_decorator


@asgi_cors_decorator(allow_all=True)
async def my_asgi_app(scope, receive, send):
    # Your app goes here

asgi-cors's Issues

Tests for headers= and methods=

This looks good to me. I'll merge it and add tests.

Originally posted by @simonw in #7 (comment)

Switch tests to use httpx

httpx is a very nice way to test ASGI apps.

Support access-control-max-age header

This header allows the client to remember the CORS result so it doesn't have to perform a pre-flight OPTIONS request before every POST etc.

access-control-max-age: 7200

How to setup ASGI CORS in Django?

I was unable to setup CORS in asgi application . I saw all the instructions but unable to understand where to place them . It didn't work in the base.py .

Breaks if underlying app sets its own `access-control-allow-origin` header

Had a weird bug where because this middleware wrapped something that already set access-control-allow-origin: * the resulting page had the HTTP header twice, which caused Firefox to not allow CORS at all.

Allow callback= to be an awaitable function

If callback= could be provided an awaitable, users could construct functions that e.g. make an async call to a database as part of deciding if a host should be allowed.

I tried implementing this with a asyncio.isawaitable() test against the callable but for some reason it didn't detect my await function as being awaitable. Here's the unit test I added which I failed to get passing:

@pytest.mark.asyncio
async def test_callback_async():
    was_called = False

    async def callback_true(origin):
        return True

    async def callback_false(origin):
        return False

    assert EXAMPLE_HOST == await get_cors_header(asgi_cors(hello_world_app, callback=callback_true), EXAMPLE_HOST)
    assert None == await get_cors_header(asgi_cors(hello_world_app, callback=callback_false), EXAMPLE_HOST)

Handling graphql requests

Hello! I was working with strawberry-graphql[channels], a graphql server based on django channels.
In the meantime, I needed a cors library that supports asgi, so I used asgi_cors.
If the client requests a query to the server to get a response,
Is there any way other than directly modifying asgi_cors.py?

# asgi_cors.py
...
if access_control_allow_origin is not None:
    status = 200 if scope["method"] == "OPTIONS" else event["status"]  ####################
    event = {
        "type": "http.response.start",
        "status": status,
        "headers": [ p for p in original_headers if p[0] != b"access-control-allow-origin"]
        + [
            [ b"access-control-allow-origin", access_control_allow_origin],
            [ b"access-control-allow-headers", b"Content-Type"]  ####################
        ],
    }
await send(event)

added lines

• add for preflight method OPTIONS, if i don't add then event["status"] is 405
• add access-control-allow-headers, if i don't add then get error because in request, gql is sent

I met each and every problem about cors in my situation and managed to solve it.
But I'm not sure if this is the right solution and I'm asking to see if there is a better way.
Actually, I don't know if I can post this on Issues.
If it's a problem, I'll delete it.
Thanks for reading the long article.

How to use with Django Channels

Hello,

I've tried to use this library with django channels and daphne. Unfortunately, I was not able to get it working. Could you add some documentation?

Best wishes