diff --git a/examples/api-backends/README.md b/examples/api-backends/README.md new file mode 100644 index 0000000..c2a8eb0 --- /dev/null +++ b/examples/api-backends/README.md @@ -0,0 +1,11 @@ +# API Backends + +Examples in this directory are intended to provide basic working backend CSRF-protected APIs, +compatible with the JavaScript frontend examples available in the +[`examples/javascript-frontends`](../javascript-frontends). + +In addition to CSRF protection, these backends provide the CORS configuration required for +communicating the CSRF cookies and headers with JavaScript client code running in the browser. + +See [`examples/javascript-frontends`](../javascript-frontends/README.md) for details on CORS and +CSRF configuration compatibility requirements. diff --git a/examples/api-backends/gorilla-mux/go.mod b/examples/api-backends/gorilla-mux/go.mod new file mode 100644 index 0000000..17e266f --- /dev/null +++ b/examples/api-backends/gorilla-mux/go.mod @@ -0,0 +1,17 @@ +// +build ignore + +module github.com/gorilla-mux/examples/api-backends/gorilla-mux + +go 1.20 + +require ( + github.com/gorilla/csrf v1.7.1 + github.com/gorilla/handlers v1.5.1 + github.com/gorilla/mux v1.8.0 +) + +require ( + github.com/felixge/httpsnoop v1.0.3 // indirect + github.com/gorilla/securecookie v1.1.1 // indirect + github.com/pkg/errors v0.9.1 // indirect +) diff --git a/examples/api-backends/gorilla-mux/go.sum b/examples/api-backends/gorilla-mux/go.sum new file mode 100644 index 0000000..8271f7f --- /dev/null +++ b/examples/api-backends/gorilla-mux/go.sum @@ -0,0 +1,13 @@ +github.com/felixge/httpsnoop v1.0.1/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U= +github.com/felixge/httpsnoop v1.0.3 h1:s/nj+GCswXYzN5v2DpNMuMQYe+0DDwt5WVCU6CWBdXk= +github.com/felixge/httpsnoop v1.0.3/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U= +github.com/gorilla/csrf v1.7.1 h1:Ir3o2c1/Uzj6FBxMlAUB6SivgVMy1ONXwYgXn+/aHPE= +github.com/gorilla/csrf v1.7.1/go.mod h1:+a/4tCmqhG6/w4oafeAZ9pEa3/NZOWYVbD9fV0FwIQA= +github.com/gorilla/handlers v1.5.1 h1:9lRY6j8DEeeBT10CvO9hGW0gmky0BprnvDI5vfhUHH4= +github.com/gorilla/handlers v1.5.1/go.mod h1:t8XrUpc4KVXb7HGyJ4/cEnwQiaxrX/hz1Zv/4g96P1Q= +github.com/gorilla/mux v1.8.0 h1:i40aqfkR1h2SlN9hojwV5ZA91wcXFOvkdNIeFDP5koI= +github.com/gorilla/mux v1.8.0/go.mod h1:DVbg23sWSpFRCP0SfiEN6jmj59UnW/n46BH5rLB71So= +github.com/gorilla/securecookie v1.1.1 h1:miw7JPhV+b/lAHSXz4qd/nN9jRiAFV5FwjeKyCS8BvQ= +github.com/gorilla/securecookie v1.1.1/go.mod h1:ra0sb63/xPlUeL+yeDciTfxMRAA+MP+HVt/4epWDjd4= +github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4= +github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0= diff --git a/examples/api-backends/gorilla-mux/main.go b/examples/api-backends/gorilla-mux/main.go new file mode 100644 index 0000000..849549a --- /dev/null +++ b/examples/api-backends/gorilla-mux/main.go @@ -0,0 +1,66 @@ +// +build ignore + +package main + +import ( + "fmt" + "log" + "net/http" + "os" + "strings" + "time" + + "github.com/gorilla/csrf" + "github.com/gorilla/handlers" + "github.com/gorilla/mux" +) + +func main() { + router := mux.NewRouter() + + loggingMiddleware := func(h http.Handler) http.Handler { + return handlers.LoggingHandler(os.Stdout, h) + } + router.Use(loggingMiddleware) + + CSRFMiddleware := csrf.Protect( + []byte("place-your-32-byte-long-key-here"), + csrf.Secure(false), // false in development only! + csrf.RequestHeader("X-CSRF-Token"), // Must be in CORS Allowed and Exposed Headers + ) + + APIRouter := router.PathPrefix("/api").Subrouter() + APIRouter.Use(CSRFMiddleware) + APIRouter.HandleFunc("", Get).Methods(http.MethodGet) + APIRouter.HandleFunc("", Post).Methods(http.MethodPost) + + CORSMiddleware := handlers.CORS( + handlers.AllowCredentials(), + handlers.AllowedOriginValidator( + func(origin string) bool { + return strings.HasPrefix(origin, "http://localhost") + }, + ), + handlers.AllowedHeaders([]string{"X-CSRF-Token"}), + handlers.ExposedHeaders([]string{"X-CSRF-Token"}), + ) + + server := &http.Server{ + Handler: CORSMiddleware(router), + Addr: "localhost:8080", + ReadTimeout: 60 * time.Second, + WriteTimeout: 60 * time.Second, + } + + fmt.Println("starting http server on localhost:8080") + log.Panic(server.ListenAndServe()) +} + +func Get(w http.ResponseWriter, r *http.Request) { + w.Header().Add("X-CSRF-Token", csrf.Token(r)) + w.WriteHeader(http.StatusOK) +} + +func Post(w http.ResponseWriter, r *http.Request) { + w.WriteHeader(http.StatusOK) +} diff --git a/examples/javascript-frontends/README.md b/examples/javascript-frontends/README.md new file mode 100644 index 0000000..02a1de4 --- /dev/null +++ b/examples/javascript-frontends/README.md @@ -0,0 +1,19 @@ +# JavaScript Frontends + +Examples in this directory are intended to provide basic working frontend JavaScript, compatible +with the API backend examples available in the [`examples/api-backends`](../api-backends). + +## CSRF and CORS compatibility + +In order to be compatible with a CSRF-protected backend, frontend clients must: + +1. Be served from a domain allowed by the backend's CORS Allowed Origins configuration. + 1. `http://localhost*` for the backend examples provided + 2. An example server to serve the HTML and JavaScript for the frontend examples from localhost is included in + [`examples/javascript-frontends/example-frontend-server`](../javascript-frontends/example-frontend-server) +3. Use the HTTP headers expected by the backend to send and receive CSRF Tokens. + The backends configure this as the Gorilla `csrf.RequestHeader`, + as well as the CORS Allowed Headers and Exposed Headers. + 1. `X-CSRF-Token` for the backend examples provided + 2. Note that some JavaScript HTTP clients automatically lowercase all received headers, + so the values must be accessed with the key `"x-csrf-token"` in the frontend code. diff --git a/examples/javascript-frontends/example-frontend-server/go.mod b/examples/javascript-frontends/example-frontend-server/go.mod new file mode 100644 index 0000000..af48442 --- /dev/null +++ b/examples/javascript-frontends/example-frontend-server/go.mod @@ -0,0 +1,10 @@ +module github.com/gorilla-mux/examples/javascript-frontends/example-frontend-server + +go 1.20 + +require ( + github.com/gorilla/handlers v1.5.1 + github.com/gorilla/mux v1.8.0 +) + +require github.com/felixge/httpsnoop v1.0.3 // indirect diff --git a/examples/javascript-frontends/example-frontend-server/go.sum b/examples/javascript-frontends/example-frontend-server/go.sum new file mode 100644 index 0000000..1e9fd4d --- /dev/null +++ b/examples/javascript-frontends/example-frontend-server/go.sum @@ -0,0 +1,7 @@ +github.com/felixge/httpsnoop v1.0.1/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U= +github.com/felixge/httpsnoop v1.0.3 h1:s/nj+GCswXYzN5v2DpNMuMQYe+0DDwt5WVCU6CWBdXk= +github.com/felixge/httpsnoop v1.0.3/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U= +github.com/gorilla/handlers v1.5.1 h1:9lRY6j8DEeeBT10CvO9hGW0gmky0BprnvDI5vfhUHH4= +github.com/gorilla/handlers v1.5.1/go.mod h1:t8XrUpc4KVXb7HGyJ4/cEnwQiaxrX/hz1Zv/4g96P1Q= +github.com/gorilla/mux v1.8.0 h1:i40aqfkR1h2SlN9hojwV5ZA91wcXFOvkdNIeFDP5koI= +github.com/gorilla/mux v1.8.0/go.mod h1:DVbg23sWSpFRCP0SfiEN6jmj59UnW/n46BH5rLB71So= diff --git a/examples/javascript-frontends/example-frontend-server/main.go b/examples/javascript-frontends/example-frontend-server/main.go new file mode 100644 index 0000000..6cac20b --- /dev/null +++ b/examples/javascript-frontends/example-frontend-server/main.go @@ -0,0 +1,42 @@ +// +build ignore + +package main + +import ( + "fmt" + "log" + "net/http" + "os" + "time" + + "github.com/gorilla/handlers" + "github.com/gorilla/mux" +) + +func main() { + router := mux.NewRouter() + + loggingMiddleware := func(h http.Handler) http.Handler { + return handlers.LoggingHandler(os.Stdout, h) + } + router.Use(loggingMiddleware) + + wd, err := os.Getwd() + if err != nil { + log.Panic(err) + } + // change this directory to point at a different Javascript frontend to serve + httpStaticAssetsDir := http.Dir(fmt.Sprintf("%s/../frontends/axios/", wd)) + + router.PathPrefix("/").Handler(http.FileServer(httpStaticAssetsDir)) + + server := &http.Server{ + Handler: router, + Addr: "localhost:8081", + ReadTimeout: 60 * time.Second, + WriteTimeout: 60 * time.Second, + } + + fmt.Println("starting http server on localhost:8081") + log.Panic(server.ListenAndServe()) +} diff --git a/examples/javascript-frontends/frontends/axios/index.html b/examples/javascript-frontends/frontends/axios/index.html new file mode 100644 index 0000000..29ac9c0 --- /dev/null +++ b/examples/javascript-frontends/frontends/axios/index.html @@ -0,0 +1,34 @@ + + + + + Gorilla CSRF + + + +
+

Gorilla CSRF: Axios JS Frontend

+

See Console and Network tabs of your browser's Developer Tools for further details

+
+ +
+

Get Request:

+

Full Response:

+ +

CSRF Token:

+ +
+ + +
+

Post Request:

+

Full Response:

+

+ Note that the X-CSRF-Token value is in the Axios config.headers; + it is not a response header set by the server. +

+ +
+ + + \ No newline at end of file diff --git a/examples/javascript-frontends/frontends/axios/index.js b/examples/javascript-frontends/frontends/axios/index.js new file mode 100644 index 0000000..d931c58 --- /dev/null +++ b/examples/javascript-frontends/frontends/axios/index.js @@ -0,0 +1,50 @@ +// make GET request to backend on page load in order to obtain +// a CSRF Token and load it into the Axios instance's headers +// https://github.com/axios/axios#creating-an-instance +const initializeAxiosInstance = async (url) => { + try { + let resp = await axios.get(url, {withCredentials: true}); + console.log(resp); + document.getElementById("get-request-full-response").innerHTML = JSON.stringify(resp); + + let csrfToken = parseCSRFToken(resp); + console.log(csrfToken); + document.getElementById("get-response-csrf-token").innerHTML = csrfToken; + + return axios.create({ + // withCredentials must be true to in order for the browser + // to send cookies, which are necessary for CSRF verification + withCredentials: true, + headers: {"X-CSRF-Token": csrfToken} + }); + } catch (err) { + console.log(err); + } +}; + +const post = async (axiosInstance, url) => { + try { + let resp = await axiosInstance.post(url); + console.log(resp); + document.getElementById("post-request-full-response").innerHTML = JSON.stringify(resp); + } catch (err) { + console.log(err); + } +}; + +// general-purpose func to deal with clients like Axios, +// which lowercase all headers received from the server response +const parseCSRFToken = (resp) => { + let csrfToken = resp.headers[csrfTokenHeader]; + if (!csrfToken) { + csrfToken = resp.headers[csrfTokenHeader.toLowerCase()]; + } + return csrfToken +} + +const url = "http://localhost:8080/api"; +const csrfTokenHeader = "X-CSRF-Token"; +initializeAxiosInstance(url) + .then(axiosInstance => { + post(axiosInstance, url); + });