2017-02-22 13:09:39 -05:00
@title
Security
@intro
Developing for content security in Angular applications
@description
2017-03-06 05:43:33 -05:00
This page describes Angular's built-in
protections against common web-application vulnerabilities and attacks such as cross-site
scripting attacks. It doesn't cover application-level security, such as authentication (_Who is
this user?_) and authorization (_What can this user do?_).
2017-02-22 13:09:39 -05:00
For more information about the attacks and mitigations described below, see [OWASP Guide Project ](https://www.owasp.org/index.php/Category:OWASP_Guide_Project ).
2017-03-06 05:43:33 -05:00
You can run the < live-example > < / live-example > in Plunker and download the code from there.
2017-02-22 13:09:39 -05:00
< h2 id = 'report-issues' >
Reporting vulnerabilities
< / h2 >
2017-03-06 05:43:33 -05:00
To report vulnerabilities in Angular itself, email us at [security@angular.io ](mailto:security@angular.io ).
2017-02-22 13:09:39 -05:00
For more information about how Google handles security issues, see [Google's security
philosophy](https://www.google.com/about/appsecurity/).
< h2 id = 'best-practices' >
Best practices
< / h2 >
* **Keep current with the latest Angular library releases.**
2017-03-06 05:43:33 -05:00
We regularly update the Angular libraries, and these updates may fix security defects discovered in
2017-02-22 13:09:39 -05:00
previous versions. 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 not include
important security fixes and enhancements. Instead, share your Angular improvements with the
community and make a pull request.
2017-03-06 05:43:33 -05:00
* **Avoid Angular APIs marked in the documentation as “_Security Risk_.”**
For more information, see the [Trusting safe values ](#bypass-security-apis ) section of this page.
2017-02-22 13:09:39 -05:00
< h2 id = 'xss' >
Preventing cross-site scripting (XSS)
< / h2 >
[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 data (in
2017-03-06 05:43:33 -05:00
particular, login data) or perform actions to impersonate the user. This is one of the most
2017-02-22 13:09:39 -05:00
common attacks on the web.
2017-03-06 05:43:33 -05:00
To block XSS attacks, you must prevent malicious code from entering the DOM (Document Object Model). For example, if
attackers can trick you into inserting a `<script>` tag in the DOM, they can run arbitrary code on
your website. The attack isn't limited to `<script>` tags— many elements and properties in the
2017-02-22 13:09:39 -05:00
DOM allow code execution, for example, `<img onerror="...">` and `<a href="javascript:...">` . If
attacker-controlled data enters the DOM, 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
2017-03-06 05:43:33 -05:00
is inserted into the DOM from a template, via property, attribute, style, class binding, or interpolation,
Angular sanitizes and escapes untrusted values.
2017-02-22 13:09:39 -05:00
_Angular templates are the same as executable code_: HTML, attributes, and binding expressions
2017-03-06 05:43:33 -05:00
(but not the values bound) in templates are trusted to be safe. This means that applications must
2017-02-22 13:09:39 -05:00
prevent values that an attacker can control from ever making it into the source code of a
2017-03-06 05:43:33 -05:00
template. Never generate template source code by concatenating user input and templates.
To prevent these vulnerabilities, use
the [offline template compiler ](#offline-template-compiler ), also known as _template injection_ .
2017-02-22 13:09:39 -05:00
### Sanitization and security contexts
2017-03-06 05:43:33 -05:00
_Sanitization_ is the inspection of an untrusted value, turning it into a value that's safe to insert into
the DOM. In many cases, sanitization doesn't change a value at all. Sanitization depends on context:
a value that's harmless in CSS is potentially dangerous in a URL.
2017-02-22 13:09:39 -05:00
2017-03-06 05:43:33 -05:00
Angular defines the following security contexts:
2017-02-22 13:09:39 -05:00
2017-03-06 05:43:33 -05:00
* **HTML** is used when interpreting a value as HTML, for example, 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 URL** is a URL that will be loaded and executed as code, for example, in `<script src>` .
2017-02-22 13:09:39 -05:00
2017-03-06 05:43:33 -05:00
Angular sanitizes untrusted values for HTML, styles, and URLs; sanitizing resource URLs isn't
2017-02-22 13:09:39 -05:00
possible because they contain arbitrary code. In development mode, Angular prints a console warning
when it has to change a value during sanitization.
### Sanitization example
2017-03-06 05:43:33 -05:00
The following template binds the value of `htmlSnippet` , once by interpolating it into an element's
2017-02-22 13:09:39 -05:00
content, and once by binding it to the `innerHTML` property of an element:
{@example 'security/ts/src/app/inner-html-binding.component.html'}
2017-03-06 05:43:33 -05:00
Interpolated content is always escaped— the HTML isn't interpreted and the browser displays
2017-02-22 13:09:39 -05:00
angle brackets in the element's text content.
2017-03-06 05:43:33 -05:00
For the HTML to be interpreted, bind it to an HTML property such as `innerHTML` . But binding
2017-02-22 13:09:39 -05:00
a value that an attacker might control into `innerHTML` normally causes an XSS
vulnerability. For example, code contained in a `<script>` tag is executed:
### Avoid direct use of the DOM APIs
2017-03-06 05:43:33 -05:00
The built-in browser DOM APIs don't automatically protect you from security vulnerabilities.
2017-02-22 13:09:39 -05:00
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
2017-03-06 05:43:33 -05:00
Content Security Policy (CSP) is a defense-in-depth
2017-02-22 13:09:39 -05:00
technique to prevent XSS. To enable CSP, configure your web server to return an appropriate
2017-03-06 05:43:33 -05:00
`Content-Security-Policy` HTTP header. Read more about content security policy at
[An Introduction to Content Security Policy ](http://www.html5rocks.com/en/tutorials/security/content-security-policy/ )
on the HTML5Rocks website.
2017-02-22 13:09:39 -05:00
< a id = "offline-template-compiler" > < / a >
### Use the offline template compiler
The offline template compiler prevents a whole class of vulnerabilities called template injection,
2017-03-06 05:43:33 -05:00
and greatly improves application performance. Use the offline template compiler in production
deployments; don't dynamically generate templates. Angular trusts template code, so generating
templates, in particular templates containing user data, circumvents Angular's built-in protections.
For information about dynamically constructing forms in a safe way, see the
[Dynamic Forms ](../cookbook/dynamic-form.html ) cookbook page.
2017-02-22 13:09:39 -05:00
### 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,
use a templating language that automatically escapes values to prevent XSS vulnerabilities on
2017-03-06 05:43:33 -05:00
the server. Don't generate Angular templates on the server side using a templating language; doing this
2017-02-22 13:09:39 -05:00
carries a high risk of introducing template-injection vulnerabilities.
< h2 id = 'code-review' >
2017-03-06 05:43:33 -05:00
Auditing Angular applications
2017-02-22 13:09:39 -05:00
< / h2 >
Angular applications must follow the same security principles as regular web applications, and
must be audited as such. Angular-specific APIs that should be audited in a security review,
such as the [_bypassSecurityTrust_ ](#bypass-security-apis ) methods, are marked in the documentation
as security sensitive.