github.com/gofiber/fiber/v2@v2.47.0/docs/api/middleware/csrf.md (about)

     1  ---
     2  id: csrf
     3  title: CSRF
     4  ---
     5  
     6  CSRF middleware for [Fiber](https://github.com/gofiber/fiber) that provides [Cross-site request forgery](https://en.wikipedia.org/wiki/Cross-site_request_forgery) protection by passing a csrf token via cookies. This cookie value will be used to compare against the client csrf token on requests, other than those defined as "safe" by RFC7231 \(GET, HEAD, OPTIONS, or TRACE\). When the csrf token is invalid, this middleware will return the `fiber.ErrForbidden` error. 
     7  
     8  CSRF Tokens are generated on GET requests. You can retrieve the CSRF token with `c.Locals(contextKey)`, where `contextKey` is the string you set in the config (see Custom Config below).
     9  
    10  When no `csrf_` cookie is set, or the token has expired, a new token will be generated and `csrf_` cookie set.
    11  
    12  :::note
    13  This middleware uses our [Storage](https://github.com/gofiber/storage) package to support various databases through a single interface. The default configuration for this middleware saves data to memory, see the examples below for other databases.
    14  :::
    15  
    16  ## Signatures
    17  
    18  ```go
    19  func New(config ...Config) fiber.Handler
    20  ```
    21  
    22  ## Examples
    23  
    24  Import the middleware package that is part of the Fiber web framework
    25  
    26  ```go
    27  import (
    28      "github.com/gofiber/fiber/v2"
    29      "github.com/gofiber/fiber/v2/middleware/csrf"
    30  )
    31  ```
    32  
    33  After you initiate your Fiber app, you can use the following possibilities:
    34  
    35  ```go
    36  // Initialize default config
    37  app.Use(csrf.New())
    38  
    39  // Or extend your config for customization
    40  app.Use(csrf.New(csrf.Config{
    41      KeyLookup:      "header:X-Csrf-Token",
    42      CookieName:     "csrf_",
    43  	CookieSameSite: "Lax",
    44      Expiration:     1 * time.Hour,
    45      KeyGenerator:   utils.UUID,
    46      Extractor:      func(c *fiber.Ctx) (string, error) { ... },
    47  }))
    48  ```
    49  
    50  :::note
    51  KeyLookup will be ignored if Extractor is explicitly set.
    52  :::
    53  
    54  ## Config
    55  
    56  ```go
    57  // Config defines the config for middleware.
    58  type Config struct {
    59      // Next defines a function to skip this middleware when returned true.
    60      //
    61      // Optional. Default: nil
    62      Next func(c *fiber.Ctx) bool
    63  
    64      // KeyLookup is a string in the form of "<source>:<key>" that is used
    65      // to create an Extractor that extracts the token from the request.
    66      // Possible values:
    67      // - "header:<name>"
    68      // - "query:<name>"
    69      // - "param:<name>"
    70      // - "form:<name>"
    71      // - "cookie:<name>"
    72      //
    73      // Ignored if an Extractor is explicitly set.
    74      //
    75      // Optional. Default: "header:X-CSRF-Token"
    76      KeyLookup string
    77  
    78      // Name of the session cookie. This cookie will store session key.
    79  	// Optional. Default value "csrf_".
    80      CookieName string
    81  
    82      // Domain of the CSRF cookie.
    83      // Optional. Default value "".
    84      CookieDomain string
    85  
    86      // Path of the CSRF cookie.
    87      // Optional. Default value "".
    88      CookiePath string
    89  
    90      // Indicates if CSRF cookie is secure.
    91      // Optional. Default value false.
    92      CookieSecure bool
    93  
    94      // Indicates if CSRF cookie is HTTP only.
    95      // Optional. Default value false.
    96      CookieHTTPOnly bool
    97  
    98      // Indicates if CSRF cookie is requested by SameSite.
    99      // Optional. Default value "Lax".
   100      CookieSameSite string
   101  
   102      // Decides whether cookie should last for only the browser sesison.
   103      // Ignores Expiration if set to true
   104      CookieSessionOnly bool
   105  
   106      // Expiration is the duration before csrf token will expire
   107      //
   108      // Optional. Default: 1 * time.Hour
   109      Expiration time.Duration
   110  
   111      // Store is used to store the state of the middleware
   112      //
   113      // Optional. Default: memory.New()
   114      Storage fiber.Storage
   115  
   116      // Context key to store generated CSRF token into context.
   117      // If left empty, token will not be stored in context.
   118      //
   119      // Optional. Default: ""
   120      ContextKey string
   121  
   122      // KeyGenerator creates a new CSRF token
   123      //
   124      // Optional. Default: utils.UUID
   125      KeyGenerator func() string
   126  
   127      // Extractor returns the csrf token
   128      //
   129      // If set this will be used in place of an Extractor based on KeyLookup.
   130      //
   131      // Optional. Default will create an Extractor based on KeyLookup.
   132      Extractor func(c *fiber.Ctx) (string, error)
   133  }
   134  ```
   135  
   136  ## Default Config
   137  
   138  ```go
   139  var ConfigDefault = Config{
   140  	KeyLookup:      "header:" + HeaderName,
   141  	CookieName:     "csrf_",
   142  	CookieSameSite: "Lax",
   143  	Expiration:     1 * time.Hour,
   144  	KeyGenerator:   utils.UUID,
   145  	ErrorHandler:   defaultErrorHandler,
   146  	Extractor:      CsrfFromHeader(HeaderName),
   147  }
   148  ```
   149  
   150  ## Constants
   151  
   152  ```go
   153  const (
   154      HeaderName = "X-Csrf-Token"
   155  )
   156  ```
   157  
   158  ### Custom Storage/Database
   159  
   160  You can use any storage from our [storage](https://github.com/gofiber/storage/) package.
   161  
   162  ```go
   163  storage := sqlite3.New() // From github.com/gofiber/storage/sqlite3
   164  app.Use(csrf.New(csrf.Config{
   165  	Storage: storage,
   166  }))
   167  ```