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 29, 2023
1 parent ef149de commit 21f4582
Showing 1 changed file with 36 additions and 6 deletions.
42 changes: 36 additions & 6 deletions aio/content/guide/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,18 +162,48 @@ 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)\). |
You have to tell Angular what the **randomly-generated** nonce from the header is so that it can be used when inserting component styles into the page.
There are two ways to provide the nonce:

1. Set the `ngCspNonce` attribute on the root application element as `<app ngCspNonce="randomNonceGoesHere"></app>`. This approach is useful 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. This can be useful 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">

It's important that the nonce you provide to Angular is <strong>unique</strong> and that it can't be guessed.
If an attacker is able to predict what the nonce will be, they will be able to get around the protections offered by CSP.

</div>

If providing the nonce is problematic in your project, you can allow inline styles by adding `'unsafe-inline'` to the `style-src` section of the CSP header instead, but note that this can compromise the application's security.

| 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 ones inserted by Angular with the `nonce-randomNonceGoesHere`. |
| `script-src 'self' 'nonce-randomNonceGoesHere';` | Allows the page to load JavaScript from the same origin \(`'self'`\) and ones 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 21f4582

Please sign in to comment.