Plug.CSRFProtection
Plug.CSRFProtection
Plug to protect from cross-site request forgery.
For this plug to work, it expects a session to have been previously fetched. It will then compare the plug stored in the session with the one sent by the request to determine the validity of the request. For an invalid request the action taken is based on the :with
option.
The token may be sent by the request either via the params with key “_csrf_token” or a header with name “x-csrf-token”.
GET requests are not protected, as they should not have any side-effect or change your application state. JavaScript requests are an exception: by using a script tag, external websites can embed server-side generated JavaScript, which can leak information. For this reason, this plug also forbids any GET JavaScript request that is not XHR (or AJAX).
Token generation
This plug won’t generate tokens automatically. Instead, tokens will be generated only when required by calling Plug.CSRFProtection.get_csrf_token/0
. The token is then stored in the process dictionary to be set in the request.
One may wonder: why the process dictionary?
The CSRF token is usually generated inside forms which may be isolated from the connection. Storing them in the process dictionary allows them to be generated as a side-effect, becoming one of those rare situations where using the process dictionary is useful.
Options
-
:with
- should be one of:exception
or:clear_session
. Defaults to:exception
.-
:exception
- for invalid requests, this plug will raisePlug.CSRFProtection.InvalidCSRFTokenError
. -
:clear_session
- for invalid requests, this plug will set an empty session for only this request. Also any changes to the session during this request will be ignored.
-
Disabling
You may disable this plug by doing Plug.Conn.put_private(:plug_skip_csrf_protection, true)
. This was made available for disabling Plug.CSRFProtection
in tests and not for dynamically skipping Plug.CSRFProtection
in production code. If you want specific routes to skip Plug.CSRFProtection
, then use a different stack of plugs for that route that does not include Plug.CSRFProtection
.
Examples
plug Plug.Session, ...
plug :fetch_session
plug Plug.CSRFProtection
Summary
Functions
- call(conn, mode)
-
Callback implementation for
Plug.call/2
- delete_csrf_token()
-
Deletes the CSRF token from the process dictionary
- get_csrf_token()
-
Gets the CSRF token
- init(opts)
-
Callback implementation for
Plug.init/1
Functions
call(conn, mode)
Callback implementation for Plug.call/2
.
delete_csrf_token()
Deletes the CSRF token from the process dictionary.
This will force the token to be deleted once the response is sent.
get_csrf_token()
Gets the CSRF token.
Generates a token and stores it in the process dictionary if one does not exist.
init(opts)
Callback implementation for Plug.init/1
.
© 2013 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/plug/Plug.CSRFProtection.html