For the complete documentation index, see llms.txt. This page is also available as Markdown.

Cross Site Request Forgery

This feature set is provided by the cbcsrf module.

Since version 2.4.x we have added the cbcsrf module as a dependency of cbSecurity. Below is how you can use it:

To verify tokens on only some routes, use the VerifyCsrf@cbsecurity route middleware instead of the auto verifier.

Settings

cbcsrf is a module of its own with its own settings, so you can configure CSRF in either place. Set them in the csrf key of your cbsecurity settings, or in the cbcsrf module settings. If you set the same setting in both, the value in cbsecurity.csrf wins.

moduleSettings = {
    cbsecurity : {
        csrf : {
            // Verify every non GET request
            enableAutoVerifier     : false,
            // Events to skip, regular expressions allowed
            verifyExcludes         : [],
            // Minutes before a token expires, 0 for never
            rotationTimeout        : 30,
            // Enable the /cbcsrf/generate endpoint
            enableEndpoint         : false,
            // The WireBox ID of the cache storage
            cacheStorage           : "CacheStorage@cbstorages",
            // Rotate tokens when a user logs in or out
            enableAuthTokenRotator : true
        }
    }
};

Which Settings Win

For each setting, the first of these that applies is used:

  1. A value you set explicitly in cbsecurity.csrf.

  2. The value of the cbcsrf module, from moduleSettings.cbcsrf, config/modules/cbcsrf.cfc or its defaults.

Only the keys you set in cbsecurity.csrf are applied. The cbsecurity defaults never overwrite a cbcsrf setting. It works one setting at a time, so you can mix them:

After startup, cbsecurity.csrf shows the values that are in effect.

Before cbsecurity 3.9.0, cbsecurity.csrf always overwrote the cbcsrf settings, even for settings you never set in it, so a cbcsrf setting you did not repeat in cbsecurity.csrf was lost.

enableAutoVerifier

Off by default. When on, every non-GET request must carry a valid CSRF token, in the csrf request key or the x-csrf-token header. See Automatic Token Verifier.

verifyExcludes

Regular expressions matched against the incoming event. A match skips the auto verifier for that event.

rotationTimeout

Tokens live for 30 minutes by default. Change it in minutes, or use 0 for tokens that never expire.

enableEndpoint

Enables GET /cbcsrf/generate so AJAX and UI-only applications can fetch tokens for secured users. See the /cbcsrf/generate Endpoint section below.

cacheStorage

The WireBox ID that stores tokens. The default is CacheStorage@cbstorages. Use any cbstorages storage that matches its API, for example SessionStorage@cbstorages.

enableAuthTokenRotator

On by default. Rotates a user's tokens when they log in or out through any authentication service registered with cbsecurity.

Mixins

This module will add the following UDF mixins to handlers, interceptors, layouts and views:

  • csrfToken() : To generate a token, using the default or a custom key

  • csrfVerify() : Verify a valid token or not

  • csrf() : To generate a hidden field (csrf) with the token

  • csrfField() : Generate a random token in a hidden form element and javascript that will refresh the page automatically when the token expires

  • csrfRotate() : To wipe and rotate the tokens for the user

Here are the method signatures:

Mappings

The module also registers the following mapping in WireBox: @cbcsrf so you can call our service model directly.

Automatic Token Expiration

By default, the module is configured to rotate all user csrf tokens every 30 minutes. This means that every token that gets created has a maximum life-span of {rotationTimeout} minutes. If you do NOT want the tokens to EVER expire during the user's logged in session, then use the value of 0 zero.

It is recommended to rotate your keys often, in case your token get's compromised.

Token Rotation

We have provided several methods to rotate or clear out all of a user's tokens. If you are using cbAuth as your module of choice for authentication, then we will listen to logins and logouts and rotate the keys for you if you have enabled the enableAuthTokenRotator setting.

If you are NOT using cbAuth then we recommend you leverage the csrfRotate() mixin or the cbcsrf.rotate() method on the @cbsrf model and do the manual rotation yourself.

Simple Example

Below is a simple example of manually verifying tokens in your handlers:

Automatic Token Verifier

We have included an interceptor that if loaded will verify all incoming requests to make sure the token has been passed or it will throw an exception.

The settings for this feature are:

You can also register an array of regular expressions that will be tested against the incoming event and if matched, it will allow the request through with no verification.

The verification process is as follows:

  • If we are doing an integration test, then skip verification

  • If the incoming HTTP Method is a get,options or head skip verification

  • If the incoming event matches any of the verifyExcludes setting, then skip verification

  • If the action is marked with a skipCsrf annotation, then skip verification

  • If no rc.csrf exists and no x-csrf-token header exists, throw a

    TokenNotFoundException exception

  • If the token is invalid then throw a TokenMismatchException exception

Please note that this verifier will check the following locations for the token:

  1. The request collection (rc) via the cbcsrf key

  2. The request HTTP header (x-csrf-token) key

skipCsrf Annotation

You can also annotate your event handler actions with a skipCsrf annotation and the verifier will also skip the verification process for those actions.

/cbcsrf/generate Endpoint

This module also allows you to turn on the generation HTTP endpoint via the enableEndpoint boolean setting. When turned on the module will register the following route: GET /cbcsrf/generate/:key?. You can use this endpoint to generate tokens for your users via AJAX or UI only applications. Please note that you can pass an optional /:key URL parameter that will generate the token for that specific key.

This endpoint should be secured, so we have annotated it with a secured annotation so if you are using cbSecurity or cbGuard this endpoint will only be available to logged in users.

Last updated

Was this helpful?