Add trusted origins feature (#117)

* Add trusted origins feature

Closes #116

* Refactor Trusted Origins feature to be more like Django.

Instead of accepting []*url.URL, which can cause weird problems, now TrustedOrigins accept []string, which is the list of hosts accepted by the middleware...So the schema doesn't matter anymore and it's more friendly to use.

* Add table driven tests for the Trusted Origins feature as requested

* Fix documentation of the TrustedOrigins feature

* Add a section describing the Trusted Origins feature for Javascript applications on the README

* Add more test cases for the table driven tests for the TrustedOrigins feature

* Fix documentation of the TrustedOrigins feature so the lint error is fixed

Author: fjorgemota

README.md

@@ -199,6 +199,49 @@ try {
 }
 ```
 
+If you plan to host your JavaScript application on another domain, you can use the Trusted Origins
+feature to allow the host of your JavaScript application to make requests to your Go application. Observe the example below:
+
+
+```go
+package main
+
+import (
+    "github.com/gorilla/csrf"
+    "github.com/gorilla/mux"
+)
+
+func main() {
+    r := mux.NewRouter()
+    csrfMiddleware := csrf.Protect([]byte("32-byte-long-auth-key"), csrf.TrustedOrigin([]string{"ui.domain.com"}))
+
+    api := r.PathPrefix("/api").Subrouter()
+    api.Use(csrfMiddleware)
+    api.HandleFunc("/user/{id}", GetUser).Methods("GET")
+
+    http.ListenAndServe(":8000", r)
+}
+
+func GetUser(w http.ResponseWriter, r *http.Request) {
+    // Authenticate the request, get the id from the route params,
+    // and fetch the user from the DB, etc.
+
+    // Get the token and pass it in the CSRF header. Our JSON-speaking client
+    // or JavaScript framework can now read the header and return the token in
+    // in its own "X-CSRF-Token" request header on the subsequent POST.
+    w.Header().Set("X-CSRF-Token", csrf.Token(r))
+    b, err := json.Marshal(user)
+    if err != nil {
+        http.Error(w, err.Error(), 500)
+        return
+    }
+
+    w.Write(b)
+}
+```
+
+On the example above, you're authorizing requests from `ui.domain.com` to make valid CSRF requests to your application, so you can have your API server on another domain without problems.
+
 ### Google App Engine
 
 If you're using [Google App

csrf.go

@@ -66,12 +66,13 @@ type options struct {
 	Path   string
 	// Note that the function and field names match the case of the associated
 	// http.Cookie field instead of the "correct" HTTPOnly name that golint suggests.
-	HttpOnly      bool
-	Secure        bool
-	RequestHeader string
-	FieldName     string
-	ErrorHandler  http.Handler
-	CookieName    string
+	HttpOnly       bool
+	Secure         bool
+	RequestHeader  string
+	FieldName      string
+	ErrorHandler   http.Handler
+	CookieName     string
+	TrustedOrigins []string
 }
 
 // Protect is HTTP middleware that provides Cross-Site Request Forgery
@@ -233,7 +234,18 @@ func (cs *csrf) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 				return
 			}
 
-			if sameOrigin(r.URL, referer) == false {
+			valid := sameOrigin(r.URL, referer)
+
+			if !valid {
+				for _, trustedOrigin := range cs.opts.TrustedOrigins {
+					if referer.Host == trustedOrigin {
+						valid = true
+						break
+					}
+				}
+			}
+
+			if valid == false {
 				r = envError(r, ErrBadReferer)
 				cs.opts.ErrorHandler.ServeHTTP(w, r)
 				return

csrf_test.go

@@ -272,6 +272,70 @@ func TestBadReferer(t *testing.T) {
 	}
 }
 
+// TestTrustedReferer checks that HTTPS requests with a Referer that does not
+// match the request URL correctly but is a trusted origin pass CSRF validation.
+func TestTrustedReferer(t *testing.T) {
+
+	testTable := []struct {
+		trustedOrigin []string
+		shouldPass    bool
+	}{
+		{[]string{"golang.org"}, true},
+		{[]string{"api.example.com", "golang.org"}, true},
+		{[]string{"http://golang.org"}, false},
+		{[]string{"https://golang.org"}, false},
+		{[]string{"http://example.com"}, false},
+		{[]string{"example.com"}, false},
+	}
+
+	for _, item := range testTable {
+		s := http.NewServeMux()
+
+		p := Protect(testKey, TrustedOrigins(item.trustedOrigin))(s)
+
+		var token string
+		s.Handle("/", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			token = Token(r)
+		}))
+
+		// Obtain a CSRF cookie via a GET request.
+		r, err := http.NewRequest("GET", "https://www.gorillatoolkit.org/", nil)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		rr := httptest.NewRecorder()
+		p.ServeHTTP(rr, r)
+
+		// POST the token back in the header.
+		r, err = http.NewRequest("POST", "https://www.gorillatoolkit.org/", nil)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		setCookie(rr, r)
+		r.Header.Set("X-CSRF-Token", token)
+
+		// Set a non-matching Referer header.
+		r.Header.Set("Referer", "http://golang.org/")
+
+		rr = httptest.NewRecorder()
+		p.ServeHTTP(rr, r)
+
+		if item.shouldPass {
+			if rr.Code != http.StatusOK {
+				t.Fatalf("middleware failed to pass to the next handler: got %v want %v",
+					rr.Code, http.StatusOK)
+			}
+		} else {
+			if rr.Code != http.StatusForbidden {
+				t.Fatalf("middleware failed reject a non-matching Referer header: got %v want %v",
+					rr.Code, http.StatusForbidden)
+			}
+		}
+	}
+}
+
 // Requests with a valid Referer should pass.
 func TestWithReferer(t *testing.T) {
 	s := http.NewServeMux()

options.go

@@ -1,6 +1,8 @@
 package csrf
 
-import "net/http"
+import (
+	"net/http"
+)
 
 // Option describes a functional option for configuring the CSRF handler.
 type Option func(*csrf)
@@ -97,6 +99,17 @@ func CookieName(name string) Option {
 	}
 }
 
+// TrustedOrigins configures a set of origins (Referers) that are considered as trusted.
+// This will allow cross-domain CSRF use-cases - e.g. where the front-end is served
+// from a different domain than the API server - to correctly pass a CSRF check.
+//
+// You should only provide origins you own or have full control over.
+func TrustedOrigins(origins []string) Option {
+	return func(cs *csrf) {
+		cs.opts.TrustedOrigins = origins
+	}
+}
+
 // setStore sets the store used by the CSRF middleware.
 // Note: this is private (for now) to allow for internal API changes.
 func setStore(s store) Option {