hg.stevelosh.com > docs.stevelosh.com


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

    <title>Welcome to flask-csrf’s documentation! &mdash; flask-csrf 0.9.1 documentation</title>

    <link rel="stylesheet" href="_static/flasky.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />

    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '0.9.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="flask-csrf 0.9.1 documentation" href="#" />
  </head>
  <body>


  <div class=indexwrapper>


    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">

  <div class="section" id="welcome-to-flask-csrf-s-documentation">
<h1>Welcome to flask-csrf&#8217;s documentation!<a class="headerlink" href="#welcome-to-flask-csrf-s-documentation" title="Permalink to this headline">¶</a></h1>
<p>The internet is a dangerous place. One common type of attack your site&#8217;s users
can fall victim to is <a class="reference external" href="http://www.squarefree.com/securitytips/web-developers.html#CSRF">Cross-Site Request Forgery</a> attacks.</p>
<p>flask-csrf is a small extension to Flask that makes adding CSRF protection to
your <a class="reference external" href="http://flask.pocoo.org/">Flask</a> application quick and easy.  It&#8217;s based on <a class="reference external" href="http://flask.pocoo.org/snippets/3/">this snippet</a> from
the Flask snippet site.</p>
<div class="section" id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h2>
<p>Install flask-csrf with <a class="reference external" href="http://pip.openplans.org/">pip</a>:</p>
<div class="highlight-python"><pre>pip install -e 'hg+http://bitbucket.org/sjl/flask-csrf@v0.9.1#egg=flask-csrf'</pre>
</div>
<p>Prefer <a class="reference external" href="http://git-scm.com/">git</a> to <a class="reference external" href="http://hg-scm.org/">Mercurial</a>?</p>
<div class="highlight-python"><pre>pip install -e 'git+http://github.com/sjl/flask-csrf.git@v0.9.1#egg=flask-csrf'</pre>
</div>
</div>
<div class="section" id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
<p>To activate CSRF protection for your Flask application you need to do two
things. First, call the <tt class="docutils literal"><span class="pre">csrf</span></tt> function with your Flask app as a parameter:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">flaskext.csrf</span> <span class="kn">import</span> <span class="n">csrf</span>
<span class="n">csrf</span><span class="p">(</span><span class="n">app</span><span class="p">)</span>
</pre></div>
</div>
<p>Once you do that you&#8217;ll need to add a CSRF token to every form on your site
that makes an HTTP <tt class="docutils literal"><span class="pre">POST</span></tt> request:</p>
<div class="highlight-python"><pre>&lt;input type="hidden" name="_csrf_token" value="{{ csrf_token() }}"&gt;</pre>
</div>
<p>If you have certain views that need to be excluded from this protection
(perhaps they receive <tt class="docutils literal"><span class="pre">POST</span></tt> requests from a third-party site) you can use
the <tt class="docutils literal"><span class="pre">csrf_exempt</span></tt> decorator to disable protection:</p>
<div class="highlight-python"><pre>from flaskext.csrf import csrf, csrf_exempt

@csrf_exempt
@route('/foo/')
def my_receiving_view():
    # ...

csrf(app)</pre>
</div>
<p>If for some reason you want to know <em>when</em> a CSRF attack happens, you can pass
a function to the <tt class="docutils literal"><span class="pre">csrf</span></tt> call and it will be called whenever an attack is
detected:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">flaskext.csrf</span> <span class="kn">import</span> <span class="n">csrf</span>

<span class="n">attacks</span> <span class="o">=</span> <span class="mi">0</span>
<span class="k">def</span> <span class="nf">count_csrf_attacks</span><span class="p">(</span><span class="n">endpoint</span><span class="p">,</span> <span class="n">arguments</span><span class="p">):</span>
    <span class="n">attacks</span> <span class="o">+=</span> <span class="mi">1</span>

<span class="n">csrf</span><span class="p">(</span><span class="n">app</span><span class="p">,</span> <span class="n">on_csrf</span><span class="o">=</span><span class="n">count_csrf_attacks</span><span class="p">)</span>
</pre></div>
</div>
<p>This function must take two parameters:</p>
<ul class="simple">
<li><strong>endpoint</strong> - A string representing the view that would
normally handle this request.</li>
<li><strong>arguments</strong> - The arguments that would normally be passed (if
any) to that view.</li>
</ul>
<p>You can use this function to do anything you like; counting attacks is just
a simple example.</p>
</div>
<div class="section" id="contribute">
<h2>Contribute<a class="headerlink" href="#contribute" title="Permalink to this headline">¶</a></h2>
<p>flask-csrf is open source and MIT licensed.  If you want to contribute feel
free to fork the <a class="reference external" href="http://bitbucket.org/sjl/flask-csrf/">Mercurial repository</a> or <a class="reference external" href="http://github.com/sjl/flask-csrf/">git repository</a> and send a pull
request.</p>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>

    <div class="footer">Created by <a href="http://stevelosh.com/">Steve Losh</a></p>

        </div>


  </body>
</html>
author	Steve Losh <steve@stevelosh.com>
date	Wed, 21 Jun 2023 15:21:12 -0400
parents	9ae2223d1010
children	(none)