| Name | asgi-csrf JSON |
| Version |
0.11
JSON |
| download |
| home_page | None |
| Summary | ASGI middleware for protecting against CSRF attacks |
| upload_time | 2024-11-15 01:05:45 |
| maintainer | None |
| docs_url | None |
| author | Simon Willison |
| requires_python | >=3.9 |
| license | Apache-2.0 |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# asgi-csrf
[](https://pypi.org/project/asgi-csrf/)
[](https://github.com/simonw/asgi-csrf/releases)
[](https://codecov.io/gh/simonw/asgi-csrf)
[](https://github.com/simonw/asgi-csrf/blob/main/LICENSE)
ASGI middleware for protecting against CSRF attacks
## Installation
pip install asgi-csrf
## Background
See the [OWASP guide to Cross Site Request Forgery (CSRF)](https://owasp.org/www-community/attacks/csrf) and their [Cross-Site Request Forgery (CSRF) Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html).
This middleware implements the [Double Submit Cookie pattern](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#double-submit-cookie), where a cookie is set that is then compared to a `csrftoken` hidden form field or a `x-csrftoken` HTTP header.
## Usage
Decorate your ASGI application like this:
```python
from asgi_csrf import asgi_csrf
from .my_asgi_app import app
app = asgi_csrf(app, signing_secret="secret-goes-here")
```
The middleware will set a `csrftoken` cookie, if one is missing. The value of that token will be made available to your ASGI application through the `scope["csrftoken"]` function.
Your application code should include that value as a hidden form field in any POST forms:
```html
<form action="/login" method="POST">
...
<input type="hidden" name="csrftoken" value="{{ request.scope.csrftoken() }}">
</form>
```
Note that `request.scope["csrftoken"]()` is a function that returns a string. Calling that function also lets the middleware know that the cookie should be set by that page, if the user does not already have that cookie.
If the cookie needs to be set, the middleware will add a `Vary: Cookie` header to the response to ensure it is not incorrectly cached by any CDNs or intermediary proxies.
The middleware will return a 403 forbidden error for any POST requests that do not include the matching `csrftoken` - either in the POST data or in a `x-csrftoken` HTTP header (useful for JavaScript `fetch()` calls).
The `signing_secret` is used to sign the tokens, to protect against subdomain vulnerabilities.
If you do not pass in an explicit `signing_secret` parameter, the middleware will look for a `ASGI_CSRF_SECRET` environment variable.
If it cannot find that environment variable, it will generate a random secret which will persist for the lifetime of the server.
This means that if you do not configure a specific secret your user's `csrftoken` cookies will become invalid every time the server restarts! You should configure a secret.
## Always setting the cookie if it is not already set
By default this middleware only sets the `csrftoken` cookie if the user encounters a page that needs it - due to that page calling the `request.scope["csrftoken"]()` function, for example to populate a hidden field in a form.
If you would like the middleware to set that cookie for any incoming request that does not already provide the cookie, you can use the `always_set_cookie=True` argument:
```python
app = asgi_csrf(app, signing_secret="secret-goes-here", always_set_cookie=True)
```
## Configuring the cookie
The middleware can be configured with several options to control how the CSRF cookie is set:
```python
app = asgi_csrf(
app,
signing_secret="secret-goes-here",
cookie_name="csrftoken",
cookie_path="/",
cookie_domain=None,
cookie_secure=False,
cookie_samesite="Lax"
)
```
- `cookie_name`: The name of the cookie to set. Defaults to `"csrftoken"`.
- `cookie_path`: The path for which the cookie is valid. Defaults to `"/"`, meaning the cookie is valid for the entire domain.
- `cookie_domain`: The domain for which the cookie is valid. Defaults to `None`, which means the cookie will only be valid for the current domain.
- `cookie_secure`: If set to `True`, the cookie will only be sent over HTTPS connections. Defaults to `False`.
- `cookie_samesite`: Controls how the cookie is sent with cross-site requests. Can be set to `"Strict"`, `"Lax"`, or `"None"`. Defaults to `"Lax"`.
## Other cases that skip CSRF protection
If the request includes an `Authorization: Bearer ...` header, commonly used by OAuth and JWT authentication, the request will not be required to include a CSRF token. This is because browsers cannot send those headers in a context that can be abused.
If the request has no cookies at all it will be allowed through, since CSRF protection is only necessary for requests from authenticated users.
### always_protect
If you have paths that should always be protected even without cookies - your login form for example (to avoid [login CSRF](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#login-csrf) attacks) you can protect those paths by passing them as the ``always_protect`` parameter:
```python
app = asgi_csrf(
app,
signing_secret="secret-goes-here",
always_protect={"/login"}
)
```
### skip_if_scope
There may be situations in which you want to opt-out of CSRF protection even for authenticated POST requests - this is often the case for web APIs for example.
The `skip_if_scope=` parameter can be used to provide a callback function which is passed an ASGI scope and returns `True` if CSRF protection should be skipped for that request.
This example skips CSRF protection for any incoming request where the request path starts with `/api/`:
```python
def skip_api_paths(scope)
return scope["path"].startswith("/api/")
app = asgi_csrf(
app,
signing_secret="secret-goes-here",
skip_if_scope=skip_api_paths
)
```
## Custom errors with send_csrf_failed
By default, when a CSRF token is missing or invalid, the middleware will return a 403 Forbidden response page with a short error message.
You can customize this behavior by passing a `send_csrf_failed` function to the middleware. This function should accept the ASGI `scope` and `send` functions, and the `message_id` of the error that occurred.
The `message_id` will be an integer representing an item from the `asgi_csrf.Errors` enum.
This example shows how you could customize the error message based on that `message_id`:
```python
async def custom_csrf_failed(scope, send, message_id):
assert scope["type"] == "http"
await send(
{
"type": "http.response.start",
"status": 403,
"headers": [[b"content-type", b"text/html; charset=utf-8"]],
}
)
await send(
{
"type": "http.response.body",
"body": {
Errors.FORM_URLENCODED_MISMATCH: "custom form-urlencoded error",
Errors.MULTIPART_MISMATCH: "custom multipart error",
Errors.FILE_BEFORE_TOKEN: "custom file before token error",
Errors.UNKNOWN_CONTENT_TYPE: "custom unknown content type error",
}
.get(message_id, "")
.encode("utf-8"),
}
)
app = asgi_csrf(
app,
signing_secret="secret-goes-here",
send_csrf_failed=custom_csrf_failed
)
```
Raw data
{
"_id": null,
"home_page": null,
"name": "asgi-csrf",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Simon Willison",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/0a/59/2b54a274b9c9cbe1c0edbe5d324925ffd88a31567fb50dc2138e0160bdef/asgi_csrf-0.11.tar.gz",
"platform": null,
"description": "# asgi-csrf\n\n[](https://pypi.org/project/asgi-csrf/)\n[](https://github.com/simonw/asgi-csrf/releases)\n[](https://codecov.io/gh/simonw/asgi-csrf)\n[](https://github.com/simonw/asgi-csrf/blob/main/LICENSE)\n\nASGI middleware for protecting against CSRF attacks\n\n## Installation\n\n pip install asgi-csrf\n\n## Background\n\nSee the [OWASP guide to Cross Site Request Forgery (CSRF)](https://owasp.org/www-community/attacks/csrf) and their [Cross-Site Request Forgery (CSRF) Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html).\n\nThis middleware implements the [Double Submit Cookie pattern](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#double-submit-cookie), where a cookie is set that is then compared to a `csrftoken` hidden form field or a `x-csrftoken` HTTP header.\n\n## Usage\n\nDecorate your ASGI application like this:\n\n```python\nfrom asgi_csrf import asgi_csrf\nfrom .my_asgi_app import app\n\n\napp = asgi_csrf(app, signing_secret=\"secret-goes-here\")\n```\n\nThe middleware will set a `csrftoken` cookie, if one is missing. The value of that token will be made available to your ASGI application through the `scope[\"csrftoken\"]` function.\n\nYour application code should include that value as a hidden form field in any POST forms:\n\n```html\n<form action=\"/login\" method=\"POST\">\n ...\n <input type=\"hidden\" name=\"csrftoken\" value=\"{{ request.scope.csrftoken() }}\">\n</form>\n```\n\nNote that `request.scope[\"csrftoken\"]()` is a function that returns a string. Calling that function also lets the middleware know that the cookie should be set by that page, if the user does not already have that cookie.\n\nIf the cookie needs to be set, the middleware will add a `Vary: Cookie` header to the response to ensure it is not incorrectly cached by any CDNs or intermediary proxies.\n\nThe middleware will return a 403 forbidden error for any POST requests that do not include the matching `csrftoken` - either in the POST data or in a `x-csrftoken` HTTP header (useful for JavaScript `fetch()` calls).\n\nThe `signing_secret` is used to sign the tokens, to protect against subdomain vulnerabilities.\n\nIf you do not pass in an explicit `signing_secret` parameter, the middleware will look for a `ASGI_CSRF_SECRET` environment variable.\n\nIf it cannot find that environment variable, it will generate a random secret which will persist for the lifetime of the server.\n\nThis means that if you do not configure a specific secret your user's `csrftoken` cookies will become invalid every time the server restarts! You should configure a secret.\n\n## Always setting the cookie if it is not already set\n\nBy default this middleware only sets the `csrftoken` cookie if the user encounters a page that needs it - due to that page calling the `request.scope[\"csrftoken\"]()` function, for example to populate a hidden field in a form.\n\nIf you would like the middleware to set that cookie for any incoming request that does not already provide the cookie, you can use the `always_set_cookie=True` argument:\n\n```python\napp = asgi_csrf(app, signing_secret=\"secret-goes-here\", always_set_cookie=True)\n```\n\n## Configuring the cookie\n\nThe middleware can be configured with several options to control how the CSRF cookie is set:\n\n```python\napp = asgi_csrf(\n app,\n signing_secret=\"secret-goes-here\",\n cookie_name=\"csrftoken\",\n cookie_path=\"/\",\n cookie_domain=None,\n cookie_secure=False,\n cookie_samesite=\"Lax\"\n)\n```\n\n- `cookie_name`: The name of the cookie to set. Defaults to `\"csrftoken\"`.\n- `cookie_path`: The path for which the cookie is valid. Defaults to `\"/\"`, meaning the cookie is valid for the entire domain.\n- `cookie_domain`: The domain for which the cookie is valid. Defaults to `None`, which means the cookie will only be valid for the current domain.\n- `cookie_secure`: If set to `True`, the cookie will only be sent over HTTPS connections. Defaults to `False`.\n- `cookie_samesite`: Controls how the cookie is sent with cross-site requests. Can be set to `\"Strict\"`, `\"Lax\"`, or `\"None\"`. Defaults to `\"Lax\"`.\n\n## Other cases that skip CSRF protection\n\nIf the request includes an `Authorization: Bearer ...` header, commonly used by OAuth and JWT authentication, the request will not be required to include a CSRF token. This is because browsers cannot send those headers in a context that can be abused.\n\nIf the request has no cookies at all it will be allowed through, since CSRF protection is only necessary for requests from authenticated users.\n\n### always_protect\n\nIf you have paths that should always be protected even without cookies - your login form for example (to avoid [login CSRF](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#login-csrf) attacks) you can protect those paths by passing them as the ``always_protect`` parameter:\n\n```python\napp = asgi_csrf(\n app,\n signing_secret=\"secret-goes-here\",\n always_protect={\"/login\"}\n)\n```\n\n### skip_if_scope\n\nThere may be situations in which you want to opt-out of CSRF protection even for authenticated POST requests - this is often the case for web APIs for example.\n\nThe `skip_if_scope=` parameter can be used to provide a callback function which is passed an ASGI scope and returns `True` if CSRF protection should be skipped for that request.\n\nThis example skips CSRF protection for any incoming request where the request path starts with `/api/`:\n\n```python\ndef skip_api_paths(scope)\n return scope[\"path\"].startswith(\"/api/\")\n\napp = asgi_csrf(\n app,\n signing_secret=\"secret-goes-here\",\n skip_if_scope=skip_api_paths\n)\n```\n\n## Custom errors with send_csrf_failed\n\nBy default, when a CSRF token is missing or invalid, the middleware will return a 403 Forbidden response page with a short error message.\n\nYou can customize this behavior by passing a `send_csrf_failed` function to the middleware. This function should accept the ASGI `scope` and `send` functions, and the `message_id` of the error that occurred.\n\nThe `message_id` will be an integer representing an item from the `asgi_csrf.Errors` enum.\n\nThis example shows how you could customize the error message based on that `message_id`:\n\n```python\nasync def custom_csrf_failed(scope, send, message_id):\n assert scope[\"type\"] == \"http\"\n await send(\n {\n \"type\": \"http.response.start\",\n \"status\": 403,\n \"headers\": [[b\"content-type\", b\"text/html; charset=utf-8\"]],\n }\n )\n await send(\n {\n \"type\": \"http.response.body\",\n \"body\": {\n Errors.FORM_URLENCODED_MISMATCH: \"custom form-urlencoded error\",\n Errors.MULTIPART_MISMATCH: \"custom multipart error\",\n Errors.FILE_BEFORE_TOKEN: \"custom file before token error\",\n Errors.UNKNOWN_CONTENT_TYPE: \"custom unknown content type error\",\n }\n .get(message_id, \"\")\n .encode(\"utf-8\"),\n }\n )\n\n\napp = asgi_csrf(\n app,\n signing_secret=\"secret-goes-here\",\n send_csrf_failed=custom_csrf_failed\n)\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "ASGI middleware for protecting against CSRF attacks",
"version": "0.11",
"project_urls": {
"CI": "https://github.com/simonw/asgi-csrf/actions",
"Changelog": "https://github.com/simonw/asgi-csrf/releases",
"Homepage": "https://github.com/simonw/asgi-csrf",
"Issues": "https://github.com/simonw/asgi-csrf/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "821c5d954baaf144852a4762368b37c06202b277378ea412acc5565f69acc9e9",
"md5": "3bee110067effb149e2be9b9260acda8",
"sha256": "03ac140115f39d4295288a9adf74fdc6ae607f6ef44abee8466520458207242b"
},
"downloads": -1,
"filename": "asgi_csrf-0.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3bee110067effb149e2be9b9260acda8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 11704,
"upload_time": "2024-11-15T01:05:43",
"upload_time_iso_8601": "2024-11-15T01:05:43.483634Z",
"url": "https://files.pythonhosted.org/packages/82/1c/5d954baaf144852a4762368b37c06202b277378ea412acc5565f69acc9e9/asgi_csrf-0.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0a592b54a274b9c9cbe1c0edbe5d324925ffd88a31567fb50dc2138e0160bdef",
"md5": "6e27f2482c90aa8c360b376ca8c688f8",
"sha256": "e19a4f87d5af3feabde04c57921ee15510c3bfb0565627df9cb20bcb303282c2"
},
"downloads": -1,
"filename": "asgi_csrf-0.11.tar.gz",
"has_sig": false,
"md5_digest": "6e27f2482c90aa8c360b376ca8c688f8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 14044,
"upload_time": "2024-11-15T01:05:45",
"upload_time_iso_8601": "2024-11-15T01:05:45.198491Z",
"url": "https://files.pythonhosted.org/packages/0a/59/2b54a274b9c9cbe1c0edbe5d324925ffd88a31567fb50dc2138e0160bdef/asgi_csrf-0.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-15 01:05:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "simonw",
"github_project": "asgi-csrf",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "asgi-csrf"
}
