Improve this Doc  View Source

$sce

  1. - $sceProvider
  2. - service in module ng

Overview

$sce is a service that provides Strict Contextual Escaping services to AngularJS.

Strict Contextual Escaping

Strict Contextual Escaping (SCE) is a mode in which AngularJS constrains bindings to only render trusted values. Its goal is to assist in writing code in a way that (a) is secure by default, and (b) makes auditing for security vulnerabilities such as XSS, clickjacking, etc. a lot easier.

Overview

To systematically block XSS security bugs, AngularJS treats all values as untrusted by default in HTML or sensitive URL bindings. When binding untrusted values, AngularJS will automatically run security checks on them (sanitizations, whitelists, depending on context), or throw when it cannot guarantee the security of the result. That behavior depends strongly on contexts: HTML can be sanitized, but template URLs cannot, for instance.

To illustrate this, consider the ng-bind-html directive. It renders its value directly as HTML: we call that the context. When given an untrusted input, AngularJS will attempt to sanitize it before rendering if a sanitizer is available, and throw otherwise. To bypass sanitization and render the input as-is, you will need to mark it as trusted for that context before attempting to bind it.

As of version 1.2, AngularJS ships with SCE enabled by default.

In practice

Here's an example of a binding in a privileged context:

<input ng-model="userHtml" aria-label="User input">
<div ng-bind-html="userHtml"></div>

Notice that ng-bind-html is bound to userHtml controlled by the user. With SCE disabled, this application allows the user to render arbitrary HTML into the DIV, which would be an XSS security bug. In a more realistic example, one may be rendering user comments, blog articles, etc. via bindings. (HTML is just one example of a context where rendering user controlled input creates security vulnerabilities.)

For the case of HTML, you might use a library, either on the client side, or on the server side, to sanitize unsafe HTML before binding to the value and rendering it in the document.

How would you ensure that every place that used these types of bindings was bound to a value that was sanitized by your library (or returned as safe for rendering by your server?) How can you ensure that you didn't accidentally delete the line that sanitized the value, or renamed some properties/fields and forgot to update the binding to the sanitized value?

To be secure by default, AngularJS makes sure bindings go through that sanitization, or any similar validation process, unless there's a good reason to trust the given value in this context. That trust is formalized with a function call. This means that as a developer, you can assume all untrusted bindings are safe. Then, to audit your code for binding security issues, you just need to ensure the values you mark as trusted indeed are safe - because they were received from your server, sanitized by your library, etc. You can organize your codebase to help with this - perhaps allowing only the files in a specific directory to do this. Ensuring that the internal API exposed by that code doesn't markup arbitrary values as safe then becomes a more manageable task.

In the case of AngularJS' SCE service, one uses $sce.trustAs (and shorthand methods such as $sce.trustAsHtml, etc.) to build the trusted versions of your values.

How does it work?

In privileged contexts, directives and code will bind to the result of $sce.getTrusted(context, value) rather than to the value directly. Think of this function as a way to enforce the required security context in your data sink. Directives use $sce.parseAs rather than $parse to watch attribute bindings, which performs the $sce.getTrusted behind the scenes on non-constant literals. Also, when binding without directives, AngularJS will understand the context of your bindings automatically.

As an example, ngBindHtml uses $sce.parseAsHtml(binding expression). Here's the actual code (slightly simplified):

var ngBindHtmlDirective = ['$sce', function($sce) {
  return function(scope, element, attr) {
    scope.$watch($sce.parseAsHtml(attr.ngBindHtml), function(value) {
      element.html(value || '');
    });
  };
}];

Impact on loading templates

This applies both to the ng-include directive as well as templateUrl's specified by directives.

By default, AngularJS only loads templates from the same domain and protocol as the application document. This is done by calling $sce.getTrustedResourceUrl on the template URL. To load templates from other domains and/or protocols, you may either whitelist them or wrap it into a trusted value.

Please note: The browser's Same Origin Policy and Cross-Origin Resource Sharing (CORS) policy apply in addition to this and may further restrict whether the template is successfully loaded. This means that without the right CORS policy, loading templates from a different domain won't work on all browsers. Also, loading templates from file:// URL does not work on some browsers.

This feels like too much overhead

It's important to remember that SCE only applies to interpolation expressions.

If your expressions are constant literals, they're automatically trusted and you don't need to call $sce.trustAs on them (e.g. <div ng-bind-html="'<b>implicitly trusted</b>'"></div>) just works (remember to include the ngSanitize module). The $sceDelegate will also use the $sanitize service if it is available when binding untrusted values to $sce.HTML context. AngularJS provides an implementation in angular-sanitize.js, and if you wish to use it, you will also need to depend on the ngSanitize module in your application.

The included $sceDelegate comes with sane defaults to allow you to load templates in ng-include from your application's domain without having to even know about SCE. It blocks loading templates from other domains or loading templates over http from an https served document. You can change these by setting your own custom whitelists and blacklists for matching such URLs.

This significantly reduces the overhead. It is far easier to pay the small overhead and have an application that's secure and can be audited to verify that with much more ease than bolting security onto an application later.

What trusted context types are supported?

Context Notes
$sce.HTML For HTML that's safe to source into the application. The ngBindHtml directive uses this context for bindings. If an unsafe value is encountered and the $sanitize module is present this will sanitize the value instead of throwing an error.
$sce.CSS For CSS that's safe to source into the application. Currently unused. Feel free to use it in your own directives.
$sce.MEDIA_URL For URLs that are safe to render as media. Is automatically converted from string by sanitizing when needed.
$sce.URL For URLs that are safe to follow as links. Is automatically converted from string by sanitizing when needed. Note that $sce.URL makes a stronger statement about the URL than $sce.MEDIA_URL does and therefore contexts requiring values trusted for $sce.URL can be used anywhere that values trusted for $sce.MEDIA_URL are required.
$sce.RESOURCE_URL For URLs that are not only safe to follow as links, but whose contents are also safe to include in your application. Examples include ng-include, src / ngSrc bindings for tags other than IMG (e.g. IFRAME, OBJECT, etc.)

Note that $sce.RESOURCE_URL makes a stronger statement about the URL than $sce.URL or $sce.MEDIA_URL do and therefore contexts requiring values trusted for $sce.RESOURCE_URL can be used anywhere that values trusted for $sce.URL or $sce.MEDIA_URL are required.

The $sceDelegateProvider#resourceUrlWhitelist() and $sceDelegateProvider#resourceUrlBlacklist() can be used to restrict trusted origins for RESOURCE_URL
$sce.JS For JavaScript that is safe to execute in your application's context. Currently unused. Feel free to use it in your own directives.
Be aware that, before AngularJS 1.7.0, a[href] and img[src] used to sanitize their interpolated values directly rather than rely upon $sce.getTrusted. As of 1.7.0, this is no longer the case. Now such interpolations are marked as requiring $sce.URL (for a[href]) or $sce.MEDIA_URL (for img[src]), so that the sanitization happens (via $sce.getTrusted...) when the $interpolate service evaluates the expressions.

There are no CSS or JS context bindings in AngularJS currently, so their corresponding $sce.trustAs functions aren't useful yet. This might evolve.

Format of items in resourceUrlWhitelist/Blacklist

Each element in these arrays must be one of the following:

Refer $sceDelegateProvider for an example.

Show me an example using SCE.

<div ng-controller="AppController as myCtrl">
  <i ng-bind-html="myCtrl.explicitlyTrustedHtml" id="explicitlyTrustedHtml"></i><br><br>
  <b>User comments</b><br>
  By default, HTML that isn't explicitly trusted (e.g. Alice's comment) is sanitized when
  $sanitize is available.  If $sanitize isn't available, this results in an error instead of an
  exploit.
  <div class="well">
    <div ng-repeat="userComment in myCtrl.userComments">
      <b>{{userComment.name}}</b>:
      <span ng-bind-html="userComment.htmlComment" class="htmlComment"></span>
      <br>
    </div>
  </div>
</div>
angular.module('mySceApp', ['ngSanitize'])
.controller('AppController', ['$http', '$templateCache', '$sce',
  function AppController($http, $templateCache, $sce) {
    var self = this;
    $http.get('test_data.json', {cache: $templateCache}).then(function(response) {
      self.userComments = response.data;
    });
    self.explicitlyTrustedHtml = $sce.trustAsHtml(
        '<span onmouseover="this.textContent=&quot;Explicitly trusted HTML bypasses ' +
        'sanitization.&quot;">Hover over this text.</span>');
  }]);
[
  { "name": "Alice",
    "htmlComment":
        "<span onmouseover='this.textContent=\"PWN3D!\"'>Is <i>anyone</i> reading this?</span>"
  },
  { "name": "Bob",
    "htmlComment": "<i>Yes!</i>  Am I the only other one?"
  }
]
describe('SCE doc demo', function() {
  it('should sanitize untrusted values', function() {
    expect(element.all(by.css('.htmlComment')).first().getAttribute('innerHTML'))
        .toBe('<span>Is <i>anyone</i> reading this?</span>');
  });

  it('should NOT sanitize explicitly trusted values', function() {
    expect(element(by.id('explicitlyTrustedHtml')).getAttribute('innerHTML')).toBe(
        '<span onmouseover="this.textContent=&quot;Explicitly trusted HTML bypasses ' +
        'sanitization.&quot;">Hover over this text.</span>');
  });
});

Can I disable SCE completely?

Yes, you can. However, this is strongly discouraged. SCE gives you a lot of security benefits for little coding overhead. It will be much harder to take an SCE disabled application and either secure it on your own or enable SCE at a later stage. It might make sense to disable SCE for cases where you have a lot of existing code that was written before SCE was introduced and you're migrating them a module at a time. Also do note that this is an app-wide setting, so if you are writing a library, you will cause security bugs applications using it.

That said, here's how you can completely disable SCE:

angular.module('myAppWithSceDisabledmyApp', []).config(function($sceProvider) {
  // Completely disable SCE.  For demonstration purposes only!
  // Do not use in new projects or libraries.
  $sceProvider.enabled(false);
});

Usage

$sce();

Methods