Configuring HTTP
****************

.[perex]
Overview of configuration options for the Nette HTTP.


HTTP Headers
============

```neon
http:
	# headers that are sent with each request
	headers:
		X-Powered-By: MyCMS
		X-Content-Type-Options: nosniff
		X-XSS-Protection: '1; mode=block'

	# affects header X-Frame-Options
	frames: ...      # (string|bool) defaults to 'SAMEORIGIN'
```

For security reasons, the framework sends a header `X-Frame-Options: SAMEORIGIN`, which says that a page can be displayed inside another page (in element `<iframe>`) only if it is on the same domain. This can be unwanted in certain situations (for example, if you are developing a Facebook application), so the behavior can be changed by setting `frames: http://allowed-host.com` or `frames: true`.


Content Security Policy
-----------------------

Headers `Content-Security-Policy` (hereinafter referred to as CSP) can be easily assembled, their description can be found in [CSP description |https://content-security-policy.com]. CSP directives (such as `script-src`) can be written either as strings according to specification or as arrays of values ​​for better readability. Then there is no need to write quotation marks around keywords such as `'self'`. Nette will also automatically generate a value of `nonce`, so `'nonce-y4PopTLM=='` will be send in the header.

```neon
http:
	# Content Security Policy (since nette/http 2.4.10)
	csp:
		# string according to CSP specification
		default-src: "'self' https://example.com"

		# array of values
		script-src:
			- nonce
			- strict-dynamic
			- self
			- https://example.com

		# bool in the case of switches
		upgrade-insecure-requests: true
		block-all-mixed-content: false
```

Use `<script n:nonce>...</script>` in the templates and the nonce value will be filled in automatically. Making secure websites in Nette is really easy.

Similarly, headers `Content-Security-Policy-Report-Only` (which can be used in parallel with CSP) and [Feature Policy |https://developers.google.com/web/updates/2018/06/feature-policy] can be added:

```neon
http:
	# Content Security Policy Report-Only
	cspReportOnly:
		default-src: self
		report-uri: 'https://my-report-uri-endpoint'

	# Feature Policy
	featurePolicy:
		unsized-media: none
		geolocation:
			- self
			- https://example.com
```


HTTP Cookie
-----------

You can change the default value of the `$secure` parameter inn the [Nette\Http\Response::setCookie() |response#setCookie] method.

```neon
http:
	# to send cookies only via HTTPS?
	cookieSecure: ...      # (bool|auto) defaults to false
```

The value `auto` means that if the website is running on HTTPS, cookies will be sent with the flag `Secure` and will therefore be available only via HTTPS.


HTTP Proxy
----------

If the site is running behind an HTTP proxy, enter its IP address in order to correctly detect the IP address of the client [Nette\Http\Response::getRemoteAddress()|request#getRemoteAddress] and encrypted connection [isSecured()|request#isSecured].

```neon
http:
	# IP address, range (ie. 127.0.0.1/8) or array of these values
	proxy: 127.0.0.1       # (string|string[]) defaults to none
```


Session
=======

Basic [sessions] settings:

```neon
session:
	# shows session panel in Tracy Bar?
	debugger: ...        # (bool) defaults to false

	# inactivity time after which the session expires
	expiration: 14 days  # (string) defaults to '3 hours'

	# to start a session automatically after creating a container?
	# 'smart' starts a session if it is already created
	autoStart: ...       # (bool|smart) defaults to 'smart'

	# handler, service that implements the SessionHandlerInterface interface
	handler: @handlerService
```

You can also set all PHP [session directives |https://www.php.net/manual/en/session.configuration.php] (in camelCase format):

```neon
session:
	# 'session.name' written as 'name'
	name: MYID

	# 'session.save_path' written as 'savePath'
	savePath: "%tempDir%/sessions"
```


Session Cookie
--------------

The session cookie is sent with the same parameters as [other cookie|#HTTP cookie], but you can change these for it:

```neon
session:
	# which hosts are allowed to receive the cookie
	cookieDomain: 'example.com'  # (string|domain) defaults to unset

	# require that a cookie shouldn't be sent with cross-origin requests?
	cookieSamesite: Lax          # (Strict|Lax|None) defaults to unset
```

The `cookieDomain` option determines which domains (origins) can accept cookies. If not specified, the cookie is accepted by the same (sub)domain as is set by it, *excluding* their subdomains. If `cookieDomain` is specified, then subdomains are also included. Therefore, specifying `cookieDomain` is less restrictive than omitting.

For example, if `cookieDomain: nette.org` is set, cookie is also available on all subdomains like `doc.nette.org`. This can also be achieved with the special value `domain`, ie `cookieDomain: domain`.

.{data-version:v2.4.10}
The `cookieSamesite` option affects whether the cookie is sent with cross-origin requests, which provides some protection against [Cross-Site Request Forgery|nette:glossary#cross-site-request-forgery-csrf] attecks.