Skip to content

Commit

Permalink
docs: update security guide to mention new CSP functionality
Browse files Browse the repository at this point in the history
Updates the security guide to reflect the recently-added CSP APIs.
  • Loading branch information
crisbeto committed Mar 30, 2023
1 parent f2ba192 commit 4723829
Showing 1 changed file with 37 additions and 6 deletions.
43 changes: 37 additions & 6 deletions aio/content/guide/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,18 +162,49 @@ Content Security Policy \(CSP\) 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.
Read more about content security policy at the [Web Fundamentals guide](https://developers.google.com/web/fundamentals/security/csp) on the Google Developers website.

The minimal policy required for brand-new Angular is:
The minimal policy required for a brand-new Angular application is:

<code-example format="none" language="none">

default-src 'self'; style-src 'self' 'unsafe-inline';
default-src 'self'; style-src 'self' 'nonce-randomNonceGoesHere'; script-src 'self' 'nonce-randomNonceGoesHere';

</code-example>

| Sections | Details |
|:--- |:--- |
| `default-src 'self';` | Allows the page to load all its required resources from the same origin. |
| `style-src 'self' 'unsafe-inline';` | Allows the page to load global styles from the same origin \(`'self'`\) and enables components to load their styles \(`'unsafe-inline'` - see [`angular/angular#6361`](https://github.com/angular/angular/issues/6361)\). |
When serving your Angular application, the server should include a randomly-generated nonce in the HTTP header for each request.
You must provide this nonce to Angular so that the framework can render `<style>` elements.
You can set the nonce for Angular in one of two ways:

1. Set the `ngCspNonce` attribute on the root application element as `<app ngCspNonce="randomNonceGoesHere"></app>`. Use this approach if you have access to server-side templating that can add the nonce both to the header and the `index.html` when constructing the response.
2. Provide the nonce using the `CSP_NONCE` injection token. Use this approach if you have access to the nonce at runtime and you want to be able to cache the `index.html`.

<code-example format="typescript" language="typescript">

import {bootstrapApplication, CSP_NONCE} from '&commat;angular/core';
import {AppComponent} from './app/app.component';

bootstrapApplication(AppComponent, {
providers: [{
provide: CSP_NONCE,
useValue: globalThis.myRandomNonceValue
}]
});

</code-example>

<div class="callout is-helpful">

Always ensure that the nonces you provide are <strong>unique per request</strong> and that they are not predictable or guessable.
If an attacker can predict future nonces, they can circumvent the protections offered by CSP.

</div>

If you cannot generate nones in your project, you can allow inline styles by adding `'unsafe-inline'` to the `style-src` section of the CSP header.

| Sections | Details |
|:--- |:--- |
| `default-src 'self';` | Allows the page to load all its required resources from the same origin. |
| `style-src 'self' 'nonce-randomNonceGoesHere';` | Allows the page to load global styles from the same origin \(`'self'`\) and styles inserted by Angular with the `nonce-randomNonceGoesHere`. |
| `script-src 'self' 'nonce-randomNonceGoesHere';` | Allows the page to load JavaScript from the same origin \(`'self'`\) and scripts inserted by the Angular CLI with the `nonce-randomNonceGoesHere`. This is only required if you're using critical CSS inlining. |

Angular itself requires only these settings to function correctly.
As your project grows, you may need to expand your CSP settings to accommodate extra features specific to your application.
Expand Down

0 comments on commit 4723829

Please sign in to comment.