CSRF protection

Cross-Site Request Forgery ( CSRF ) allows an attacker to perform actions on behalf of another user without their knowledge or permission.

AdonisJs protects your application from CSRF attacks by denying unidentified requests. HTTP requests with POST, PUT and DELETE methods are checked to make sure that these requests are invoked by right people from right place.

Setup

Make sure to install the shield provider and register the appropriate middleware.

adonis install @adonisjs/shield

Next, register the provider inside start/app.js file.

const providers = [
  '@adonisjs/shield/providers/ShieldProvider'
]

And, finally register the global middleware inside start/kernel.js file.

Shield middleware relies on sessions, so make sure they are setup correctly.
const globalMiddleware = [
  'Adonis/Middleware/Shield'
]

Config

The configuration for CSRF is saved inside config/shield.js file.

csrf: {
  enable: true,
  methods: ['POST', 'PUT', 'DELETE'],
  filterUris: ['/user/:id'],
  cookieOptions: {}
}
Key Value Description

enable

Boolean

A boolean to turn on/off CSRF for the entire application.

methods

Array

HTTP verbs to be protected by CSRF. Consider adding all verbs which allow the end user to add or modify data.

filterUris

Array

A list of URLs/Routes to ignore. You can pass actual routes definition or a regular expression to match.

cookieOptions

Object

An object of cookie options

How It Works?

  1. AdonisJs creates a CSRF secret for each user visiting your website.

  2. A corresponding token for the secret is generated for each request and passed to all views as csrfToken and csrfField() globals.

  3. Also, the same token is set to a cookie with key XSRF-TOKEN. Frontend Frameworks like AngularJs automatically reads this cookie and send it along with each Ajax request.

  4. Whenever a POST, PUT or DELETE requests comes, the middleware verifies the token with the secret to make sure it is valid.

If you are using the XSRF-TOKEN cookie value, then do make sure the header key is X-XSRT-TOKEN

View Helpers

You can access the CSRF token using one of the following view helpers and make sure to set them inside your forms.

To send the token along with each request, you need access to it. There are a few ways to get access to the CSRF token.

csrfField

{{ csrfField() }}
Output
<input type="hidden" name="_csrf" value="xxxxxx">

csrfToken

The csrfToken helper returns the raw value of the token.

{{ csrfToken }}

Handling exception

On validation failure, an exception is thrown with EBADCSRFTOKEN code. Make sure to listen for the exception and return an appropriate response.

app/Exceptions/Handler.js
class ExceptionHandler {
  async handle (error, { response }) {
    if (error.code === 'EBADCSRFTOKEN') {
      response.forbidden('Cannot process your request.')
      return
    }
  }
}