pyramid.csrf

class LegacySessionCSRFStoragePolicy

A CSRF storage policy that defers control of CSRF storage to the session.

This policy maintains compatibility with legacy ISession implementations that know how to manage CSRF tokens themselves via ISession.new_csrf_token and ISession.get_csrf_token.

Note that using this CSRF implementation requires that a session factory is configured.

New in version 1.9.

check_csrf_token(request, supplied_token)

Returns True if the supplied_token is valid.

get_csrf_token(request)

Returns the currently active CSRF token from the session, generating a new one if needed.

new_csrf_token(request)

Sets a new CSRF token into the session and returns it.

class SessionCSRFStoragePolicy(key='_csrft_')

A CSRF storage policy that persists the CSRF token in the session.

Note that using this CSRF implementation requires that a session factory is configured.

key

The session key where the CSRF token will be stored. Default: _csrft_.

New in version 1.9.

check_csrf_token(request, supplied_token)

Returns True if the supplied_token is valid.

get_csrf_token(request)

Returns the currently active CSRF token from the session, generating a new one if needed.

new_csrf_token(request)

Sets a new CSRF token into the session and returns it.

class CookieCSRFStoragePolicy(cookie_name='csrf_token', secure=False, httponly=False, domain=None, max_age=None, path='/', samesite='Lax')

An alternative CSRF implementation that stores its information in unauthenticated cookies, known as the 'Double Submit Cookie' method in the OWASP CSRF guidelines. This gives some additional flexibility with regards to scaling as the tokens can be generated and verified by a front-end server.

New in version 1.9.

check_csrf_token(request, supplied_token)

Returns True if the supplied_token is valid.

get_csrf_token(request)

Returns the currently active CSRF token by checking the cookies sent with the current request.

new_csrf_token(request)

Sets a new CSRF token into the request and returns it.

get_csrf_token(request)

Get the currently active CSRF token for the request passed, generating a new one using new_csrf_token(request) if one does not exist. This calls the equivalent method in the chosen CSRF protection implementation.

New in version 1.9.

new_csrf_token(request)

Generate a new CSRF token for the request passed and persist it in an implementation defined manner. This calls the equivalent method in the chosen CSRF protection implementation.

New in version 1.9.

check_csrf_origin(request, *, trusted_origins=None, allow_no_origin=False, raises=True)

Check the Origin of the request to see if it is a cross site request or not.

If the value supplied by the Origin or Referer header isn't one of the trusted origins and raises is True, this function will raise a pyramid.exceptions.BadCSRFOrigin exception, but if raises is False, this function will return False instead. If the CSRF origin checks are successful this function will return True unconditionally.

Additional trusted origins may be added by passing a list of domain (and ports if non-standard like ['example.com', 'dev.example.com:8080']) in with the trusted_origins parameter. If trusted_origins is None (the default) this list of additional domains will be pulled from the pyramid.csrf_trusted_origins setting.

allow_no_origin determines whether to return True when the origin cannot be determined via either the Referer or Origin header. The default is False which will reject the check.

Note that this function will do nothing if request.scheme is not https.

New in version 1.7.

Changed in version 1.9: Moved from pyramid.session to pyramid.csrf

Changed in version 2.0: Added the allow_no_origin option.

check_csrf_token(request, token='csrf_token', header='X-CSRF-Token', raises=True)

Check the CSRF token returned by the pyramid.interfaces.ICSRFStoragePolicy implementation against the value in request.POST.get(token) (if a POST request) or request.headers.get(header). If a token keyword is not supplied to this function, the string csrf_token will be used to look up the token in request.POST. If a header keyword is not supplied to this function, the string X-CSRF-Token will be used to look up the token in request.headers.

If the value supplied by post or by header cannot be verified by the pyramid.interfaces.ICSRFStoragePolicy, and raises is True, this function will raise an pyramid.exceptions.BadCSRFToken exception. If the values differ and raises is False, this function will return False. If the CSRF check is successful, this function will return True unconditionally.

See Checking CSRF Tokens Automatically for information about how to secure your application automatically against CSRF attacks.

New in version 1.4a2.

Changed in version 1.7a1: A CSRF token passed in the query string of the request is no longer considered valid. It must be passed in either the request body or a header.

Changed in version 1.9: Moved from pyramid.session to pyramid.csrf and updated to use the configured pyramid.interfaces.ICSRFStoragePolicy to verify the CSRF token.