From e0fa7275949de42da52353bac7597b2602ee29c1 Mon Sep 17 00:00:00 2001 From: Alex Rickabaugh Date: Thu, 13 Jul 2017 16:59:46 -0700 Subject: [PATCH] fix(aio): document XSRF protection in HttpClient --- aio/content/guide/http.md | 31 +++++++++++++++++++++++++++++++ aio/content/guide/security.md | 33 ++------------------------------- 2 files changed, 33 insertions(+), 31 deletions(-) diff --git a/aio/content/guide/http.md b/aio/content/guide/http.md index 0761b3b965..08e659155c 100644 --- a/aio/content/guide/http.md +++ b/aio/content/guide/http.md @@ -525,6 +525,37 @@ http.request(req).subscribe(event => { }); ``` +## Security: XSRF Protection + +[Cross-Site Request Forgery (XSRF)](https://en.wikipedia.org/wiki/Cross-site_request_forgery) is an attack technique by which the attacker can trick an authenticated user into unknowingly executing actions on your website. `HttpClient` supports a [common mechanism](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Cookie-to-Header_Token) used to prevent XSRF attacks. When performing HTTP requests, an interceptor reads a token from a cookie, by default `XSRF-TOKEN`, and sets it as an HTTP header, `X-XSRF-TOKEN`. Since only code that runs on your domain could read the cookie, the backend can be certain that the HTTP request came from your client application and not an attacker. + +By default, an interceptor sends this cookie on all mutating requests (POST, etc.) +to relative URLs but not on GET/HEAD requests or +on requests with an absolute URL. + +To take advantage of this, your server needs to set a token in a JavaScript readable session cookie called `XSRF-TOKEN` on either the page load or the first GET request. On subsequent requests the server can verify that the cookie matches the `X-XSRF-TOKEN` HTTP header, and therefore be sure that only code running on your domain could have sent the request. The token must be unique for each user and must be verifiable by the server; this prevents the client from making up its own tokens. Set the token to a digest of your site's authentication +cookie with a salt for added security. + +In order to prevent collisions in environments where multiple Angular apps share the same domain or subdomain, give each application a unique cookie name. + +
+*Note that `HttpClient`'s support is only the client half of the XSRF protection scheme.* Your backend service must be configured to set the cookie for your page, and to verify that the header is present on all eligible requests. If not, Angular's default protection will be ineffective. +
+ +### Configuring custom cookie/header names + +If your backend service uses different names for the XSRF token cookie or header, use `HttpClientXsrfModule.withConfig()` to override the defaults. + +```javascript +imports: [ + HttpClientModule, + HttpClientXsrfModule.withConfig({ + cookieName: 'My-Xsrf-Cookie', + headerName: 'My-Xsrf-Header', + }), +] +``` + ## Testing HTTP requests Like any external dependency, the HTTP backend needs to be mocked as part of good testing practice. `@angular/common/http` provides a testing library `@angular/common/http/testing` that makes setting up such mocking straightforward. diff --git a/aio/content/guide/security.md b/aio/content/guide/security.md index 0b70b70ad1..6a2f37d33b 100644 --- a/aio/content/guide/security.md +++ b/aio/content/guide/security.md @@ -282,36 +282,7 @@ This technique is effective because all browsers implement the _same origin poli on which cookies are set can read the cookies from that site and set custom headers on requests to that site. That means only your application can read this cookie token and set the custom header. The malicious code on `evil.com` can't. -Angular's `http` has built-in support for the client-side half of this technique in its `XSRFStrategy`. -The default `CookieXSRFStrategy` is turned on automatically. -Before sending an HTTP request, the `CookieXSRFStrategy` looks for a cookie called `XSRF-TOKEN` and -sets a header named `X-XSRF-TOKEN` with the value of that cookie. - -The server must do its part by setting the -initial `XSRF-TOKEN` cookie and confirming that each subsequent state-modifying request -includes a matching `XSRF-TOKEN` cookie and `X-XSRF-TOKEN` header. - -XSRF/CSRF tokens should be unique per user and session, have a large random value generated by a -cryptographically secure random number generator, and expire in a day or two. - -Your server may use a different cookie or header name for this purpose. -An Angular application can customize cookie and header names by providing its own `CookieXSRFStrategy` values. - - - { provide: XSRFStrategy, useValue: new CookieXSRFStrategy('myCookieName', 'My-Header-Name') } - - - - -Or you can implement and provide an entirely custom `XSRFStrategy`: - - - - { provide: XSRFStrategy, useClass: MyXSRFStrategy } - - - - +Angular's `HttpClient` has built-in support for the client-side half of this technique. Read about it more in the [HttpClient guide](/guide/http). For information about CSRF at the Open Web Application Security Project (OWASP), see Cross-Site Request Forgery (CSRF) and @@ -337,7 +308,7 @@ This attack is only successful if the returned JSON is executable as JavaScript. prevent an attack by prefixing all JSON responses to make them non-executable, by convention, using the well-known string `")]}',\n"`. -Angular's `Http` library recognizes this convention and automatically strips the string +Angular's `HttpClient` library recognizes this convention and automatically strips the string `")]}',\n"` from all responses before further parsing. For more information, see the XSSI section of this [Google web security blog