angular-cn/public/docs/ts/latest/guide/security.jade

block includes
  include ../_util-fns
:marked
  Web application security has many aspects. This chapter describes Angular's built in
  protections against common web application vulnerabilities and attacks, such as Cross Site
  Scripting Attacks. It does not cover application level security, such as authentication (_Who is
  this user?_) or authorization (_What can this user do?_).

  The [Open Web Application Security Project (OWASP)](https://www.owasp.org/index.php/Category:OWASP_Guide_Project)
  has further information on the attacks and mitigations described below.

.l-main-section
:marked
  # Table Of Contents

  * [Reporting Vulnerabilities](#report-issues)
  * [Best Practices](#best-practices)
  * [Preventing Cross-Site Scripting (XSS)](#xss)
  * [Trusting Safe Values](#bypass-security-apis)
  * [HTTP-level Vulnerabilities](#http)
  * [Auditing Angular Applications](#code-review)

  Try the <live-example></live-example> of the code shown in this chapter.

.l-main-section
h2#report-issues Reporting Vulnerabilities
:marked
  Email us at [security@angular.io](mailto:security@angular.io) to report vulnerabilities in
  Angular itself.

  For further details on how Google handles security issues please refer to [Google's security
  philosophy](https://www.google.com/about/appsecurity/).

.l-main-section
h2#best-practices Best Practices
:marked
  * **Keep current with the latest Angular library releases.**
  We regularly update our Angular libraries and these updates may fix security defects discovered in
  previous version. Check the Angular [change
  log](https://github.com/angular/angular/blob/master/CHANGELOG.md) for security-related updates.

  * **Don't modify your copy of Angular.**
  Private, customized versions of Angular tend to fall behind the current version and may neglect
  important security fixes and enhancements. Instead, share your Angular improvements with the
  community and make a pull request.

  * **Avoid Angular APIs marked in the documentation as “[_Security Risk_](#bypass-security-apis)”.**

.l-main-section
h2#xss Preventing Cross-Site Scripting (XSS)
:marked
  [Cross-Site Scripting (XSS)](https://en.wikipedia.org/wiki/Cross-site_scripting) enables attackers
  to inject malicious code into web pages. Such code can then, for example, steal user's data (in
  particular their login data), or perform actions impersonating the user. This is one of the most
  common attacks on the web.

  To block XSS attacks, we must prevent malicious code from entering the DOM. For example, if an
  attacker can trick us into inserting a `<script>` tag in the DOM, they can run arbitrary code on
  our website. The attack is not limited to `<script>` tags - many elements and properties in the
  DOM allow code execution, for example `<img onerror="...">`, `<a href="javascript:...">`. If
  attacker controlled data enters the DOM, we have to expect security vulnerabilities.

  ### Angular’s Cross-site Scripting Security Model

  To systematically block XSS bugs, Angular treats all values as untrusted by default. When a value
  is inserted into the DOM from a template, via property, attribute, style, or class binding, or via
  interpolation, Angular will sanitize and escape untrusted values.

  **Angular templates are the same as executable code**: HTML, attributes, and binding expressions
  (but not the values bound!) in templates are trusted to be safe. That means applications must
  prevent potentially attacker controlled values from ever making it into the source code of a
  template. Never generate template source code by concatenating user input and templates! Using
  the [offline template compiler](#offline-template-compiler) is an effective way to prevent these
  vulnerabilities, also known as template injection.

  ### Sanitization and security contexts

  Sanitization inspects an untrusted value and turns it into a value that is safe to insert into
  the DOM. In many cases, values do not get changed by this at all. Sanitization depends on context:
  a value that is harmless in CSS is potentially dangerous in a URL.

  Angular defines four security contexts: HTML, style, URL, and resource URL.

  * HTML is used when interpreting a value as HTML, e.g., when binding to `innerHtml`
  * Style is used when binding CSS into the `style` property
  * URL is used for URL properties such as `<a href>`
  * Resource URLs are URLs that will be loaded and executed as code, e.g., in `<script src>`

  Angular sanitizes untrusted values for the first three items; sanitizing resource URLs is not
  possible as they contain arbitrary code. In development mode, Angular prints a console warning
  when it has to change a value during sanitization.

  ### Sanitization example

  The template below binds the value of `htmlSnippet`, once by interpolating it into an element's
  content, and once by binding it to the `innerHTML` property of an element.

+makeExample('app/inner-html-binding.component.html')

:marked
  Interpolated content is always escaped - the HTML is not interpreted, and the browser displays
  angle brackets in the elements text content.

  For the HTML to be interpreted, we must bind to an HTML property, such as `innerHTML`. But binding
  a potentially attacker controlled value into `innerHTML` would normally cause an XSS
  vulnerability. For example, code contained in a `<script>` tag would be executed.

+makeExcerpt('app/inner-html-binding.component.ts ()', 'inner-html-controller')

:marked
  Angular recognizes the value as unsafe, and automatically sanitizes it. It removes the `<script>`
  tag but keeps safe content, such as the text content of the `<script>` tag, or the `<b>` element.

figure.image-display
    img(src='/resources/images/devguide/security/binding-inner-html.png'
        alt='A screenshot showing interpolated and bound HTML values')
:marked
  ### Avoid direct use of the DOM APIs

  The built-in browser DOM APIs do not automatically protect you from security vulnerabilities.
  For example, `document`, the node available through `ElementRef`, and many third party APIs
  contain unsafe methods. Avoid directly interacting with the DOM, and instead use Angular
  templates where possible.

  ### Content Security Policy

  A [Content Security Policy (CSP)](http://www.html5rocks.com/en/tutorials/security/content-security-policy/) is a defense-in-depth
  technique to prevent XSS. To enable CSP, configure your web server to return an appropriate
  `Content-Security-Policy` HTTP header.

  <a id="offline-template-compiler"></a>
  ### Use the Offline Template Compiler

  The offline template compiler prevents a whole class of vulnerabilities called template injection,
  and also greatly improves application performance. Use the offline template compiler in production
  deployments. Do not dynamically generate templates. Angular trusts template code, so generating
  templates, in particular containing user data, circumvents Angular's built-in protections. See the
  [Dynamic Forms Cookbook](../cookbook/dynamic-form.html) on how to dynamically construct forms in a
  safe way.

  ### Server side XSS protection

  HTML constructed on the server is vulnerable to injection attacks. Injecting template code into an
  Angular application is the same as injecting executable code into the
  application; it gives the attacker full control over the application. To prevent this, make sure
  to use a templating language that automatically escapes values to prevent XSS vulnerabilities on
  the server. Do not generate Angular templates on the server side using a templating language, this
  carries a high risk of introducing template injection vulnerabilities.

.l-main-section
h2#bypass-security-apis Trusting Safe Values
:marked
  Sometimes applications genuinely need to include executable code, display an `<iframe>` from some
  URL, or construct potentially dangerous URLs. To prevent automatic sanitization in this situation,
  you can tell Angular that you inspected a value, checked how it is generated, and made sure it is
  always secure. But **be careful**! If you trust a value that can be malicious, you will likely
  introduce a security vulnerability into your application. If in doubt, find a professional
  security reviewer.

  You can mark a value as trusted by injecting `DomSanitizer`, and calling one of the
  following methods.

  * `bypassSecurityTrustHtml`
  * `bypassSecurityTrustScript`
  * `bypassSecurityTrustStyle`
  * `bypassSecurityTrustUrl`
  * `bypassSecurityTrustResourceUrl`

  Remember, whether a value is safe depends on context, so you need to choose the right context for
  your intended use of the value. Imagine the following template needs to bind a URL to a
  `javascript:alert(...)` call.

+makeExcerpt('app/bypass-security.component.html ()', 'dangerous-url')

:marked
  Normally, Angular automatically sanitizes the URL, disables the dangerous code and,
  in development mode, logs this action to the console. To prevent
  this, we can mark the URL value as a trusted URL using the `bypassSecurityTrustUrl` call:

+makeExcerpt('app/bypass-security.component.ts ()', 'trust-url')

figure.image-display
    img(src='/resources/images/devguide/security/bypass-security-component.png'
        alt='A screenshot showing an alert box created from a trusted URL')

:marked
  If we need to convert user input into a trusted value, it can be convenient to do so in a
  controller method. The template below allows users to enter a YouTube video ID, and load the
  corresponding video in an `<iframe>`. The `<iframe src>` attribute is a resource URL security
  context, because an untrusted source can, e.g., smuggle in file downloads that unsuspecting users
  would execute. So we call a method on the controller to construct a trusted video URL, which
  Angular then allows binding into `<iframe src>`.

+makeExcerpt('app/bypass-security.component.html ()', 'iframe-videoid')
+makeExcerpt('app/bypass-security.component.ts ()', 'trust-video-url')

.l-main-section
h2#http HTTP-level Vulnerabilities
:marked
  Angular has built in support to help prevent two common HTTP vulnerabilities, Cross-site Request
  Forgery (XSRF) and Cross-site Script Inclusion (XSSI). Both of these must be primarily mitigated
  on the server side, but Angular ships helpers to make integration on the client side easier.

h3#xsrf Cross-site Request Forgery (XSRF)
:marked
  In a Cross-site Request Forgery (XSRF or CSRF), an attacker tricks the user into visiting a
  _different_ page, and has them, e.g., submit a form that sends a request to your application's
  web server. If the user is logged into your application, the browser will send authentication
  cookies, and the attacker could &mdash; for example &mdash; cause a bank transfer in the user's name with
  the right request.

  To prevent this, your application must ensure that user requests originate in your own
  application, not on a different site. A common technique is that the server sends a randomly
  generated authentication token in a cookie, often with the name `XSRF-TOKEN`. Cookies can only
  be read by the website on which they are set, so only your own application can read this token. On
  each API request, the server then validates the client by checking that the token is sent back,
  usually in an HTTP header called `X-XSRF-TOKEN`.

  The Angular `http` client has built-in support for this technique. The default
  `CookieXSRFStrategy` looks for a cookie called `XSRF-TOKEN` and sets an HTTP request header named
  `X-XSRF-TOKEN` with the value of that cookie on every request. The server must set the
  `XSRF-TOKEN` cookie, and validate the response header for each state modifying request.

  XSRF tokens should be unique per user and session, have a large random value generated by a
  cryptographically secure random number generator, and expire.

  Angular applications can customize cookie and header names by binding their own
  `CookieXSRFStrategy` value, or implement an entirely custom `XSRFStrategy` by providing a custom
  binding for that type, by adding either of the following to your providers list:

code-example(language="typescript").
  { provide: XSRFStrategy, useValue: new CookieXSRFStrategy('myCookieName', 'My-Header-Name')}
  { provide: XSRFStrategy, useClass: MyXSRFStrategy}

:marked
  Learn about Cross Site Request Forgery (XSRF) at the Open Web Application Security Project (OWASP)
  [here](https://www.owasp.org/index.php/Cross-Site_Request_Forgery_%28CSRF%29) and
  [here](https://www.owasp.org/index.php/CSRF_Prevention_Cheat_Sheet). This [Stanford University
  paper](https://seclab.stanford.edu/websec/csrf/csrf.pdf) is also a rich source of detail.

h3#xssi Cross-site Script Inclusion (XSSI)
:marked
  Cross-site Script Inclusion, also known as JSON vulnerability, can allow an attacker's website to
  read data from a JSON API. The attack works on older browser by overriding native JavaScript
  object constructors, and then including an API URL using a `<script>` tag.

  This attack is only successful if the returned JSON is executable as JavaScript. Servers can
  prevent it 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
  `")]}',\n"` from all responses before further parsing.

  Learn more in the XSSI section of this [Google web security blog
  post](https://security.googleblog.com/2011/05/website-security-for-webmasters.html)

.l-main-section
h2#code-review Auditing Angular Applications
:marked
  Angular applications should follow the same security principles as regular web applications, and
  should be audited as such. Angular specific APIs that should be audited in a security review,
  such as the [_bypassSecurityTrust_](#bypass-security-apis) APIs, are marked in the documentation
  as security sensitive.