{{TOC}}
== Introduction ==
The Bug Genie has built-in protection for CSRF attacks which is being used throughout The Bug Genie, and is also available for use by plugin developers. The basic CSRF protection included in The Bug Genie will use an authentication token limited to a logged in users' current session. The token is re-generated when the user logs out / back in, or when the session timeout occurs.

== Basics ==
The Bug Genie uses CSRF protection in two ways. One is via CSRF-protection-enabled routes, and the other is via explicit CSRF-protection checks triggered in an action. Should the user fail a CSRF protection check, either a message is displayed to the user (if requested via JSON), or an HTTP 301-redirect is triggered (depending on the origin of the request).

== Usage ==
'''All techniques described here also applies to plugin developers'''.

=== Retrieving the current CSRF-token ===
You can retrieve the current users CSRF-token in The Bug Genie by calling the '''TBGContext::generateCSRFtoken()''' function. This function will retrieve the current users token, or generate a token if it's not already been generated.

=== CSRF-protected routes ===
When setting up routes, you have the option to specify CSRF-protection directly on the route. This will automatically include the csrf_token in the URL whenever the '''TBGContext::getRouting()->generate()''' function (in actions) or '''make_url()''' function (in templates) are called. CSRF-protected routes also automatically perform the CSRF check before the associated action is triggered, so you can be safe that the incoming request is legitimate.

==== Examples ====
''securing a route in the load_routes.inc.php'' file
<source lang="php">
// Add $csrf_enabled = true as the last parameter
$routes[] = array('issue_attach_link', '/update/attach/link/to/issue/:issue_id', 'main', 'attachLinkToIssue', array(), true);
</source>
''securing a route from a module''
<source lang="php">
// Add $csrf_enabled = true as the last parameter
$this->addRoute('publish_article_edit', '/wiki/:article_name/edit', 'editArticle', array(), true);
</source>
''generate routes and echo them in an action / controller''
<source lang="php">
echo TBGContext::getRouting()->generate('issue_attach_link', array('issue_id' => 1));
// echoes something like this:
// http://hostname/update/attach/link/to/issue/1/csrf_token/ca68daf987adf976dsa9csad879.88093209
</source>
''generate routes and echo them in a template''
<source lang="php">
echo make_url('publish_article_edit', array('article_name' => 'MyArticle'));
// echoes something like this:
// http://hostname/wiki/MyArticle/edit/csrf_token/ca68daf987adf976dsa9csad879.88093209
</source>

The CSRF-protection checks will be performed automatically when you do this, there is no need to peform additional checks in your code.

=== Manual CSRF-protection ===
Often it's not desired to display the csrf_token directly in the link, such as for form submissions and other related scenarios. In these cases, you can still use the built-in CSRF-protection.

The UI helper (which is always loaded in templates) has a '''csrf_tag()''' function that you can include in your forms. When called, this function will echo out a hidden input tag in your form with the value of the current users CSRF-token.

When the form is submitted and your action is called, call '''TBGContext::checkCSRFtoken()''' to check the validity of the submitted CSRF-token. This will then behave in the same way as the automated CSRF-protection checks.

''in the template''
<source lang="php">
<form action="<?php echo make_url('my_route'); ?>" method="post">
    <?php echo csrf_tag(); ?>
    <input type="text" name="some_input">
    <input type="submit" value="Submit!">
</form>
</source>
''in your controller / action''
<source lang="php">
public function executeMyRoute(TBGRequest $request)
{
    if (TBGContext::checkCSRFtoken())
    {
    }
}
</source>
[[Category:TheBugGenie:Development]]