Skip to content

Added the documentation for the trusted_hosts option #3876

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

Added the documentation for the trusted_hosts option #3876

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0303e91
Added the documentation for the trusted_hosts option
javiereguiluz May 26, 2014
361574a
Fixed minor formatting issues
javiereguiluz May 26, 2014
9fb6766
Added more information about the risks involved and why this
javiereguiluz Jul 5, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 67 additions & 0 deletions reference/configuration/framework.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ Configuration
* `http_method_override`_
* `ide`_
* `test`_
* `trusted_hosts`_
* `trusted_proxies`_
* `form`_
* enabled
Expand Down Expand Up @@ -114,6 +115,72 @@ services related to testing your application (e.g. ``test.client``) are loaded.
This setting should be present in your ``test`` environment (usually via
``app/config/config_test.yml``). For more information, see :doc:`/book/testing`.

trusted_hosts
~~~~~~~~~~~~~

**type**: ``array``

A lot of different attacks have been discovered relying on inconsistencies
between the handling of the ``Host`` header by various software (web servers,
reverse proxies, web frameworks, etc.). Basically, everytime the framework is
generating an absolute URL (when sending an email to reset a password for
instance), the host might have been manipulated by an attacker.

The Symfony Request::getHost() method might be vulnerable to some of these attacks
because it depends on the configuration of your web server. One simple solution
to avoid these attacks is to whitelist the hosts that your Symfony application
can respond to. That's the purpose of this ``trusted_hosts`` option:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add one more sentence at the end. Something like this:

If the incoming request's hostname doesn't match one in this list, the
application won't respond and the user will receive a 500 response:

I wasn't sure initially if maybe if your host wasn't in this list that Symfony still responded but used a different absolute URL (or something like that). This is clear that literally your app won't work at all.


.. configuration-block::

.. code-block:: yaml

framework:
trusted_hosts: ['acme.com', 'acme.org']

.. code-block:: xml

<framework:config trusted-hosts="acme.com, acme.org">
<!-- ... -->
</framework>

.. code-block:: php

$container->loadFromExtension('framework', array(
'trusted_hosts' => array('acme.com', 'acme.org'),
));

Hosts can also be configured using regular expressions, which make it easier to
respond to any subdomain:

.. configuration-block::

.. code-block:: yaml

framework:
trusted_hosts: ['.*\.?acme.com$', '.*\.?acme.org$']

.. code-block:: xml

<framework:config trusted-hosts=".*\.?acme.com$, .*\.?acme.org$">
<!-- ... -->
</framework>

.. code-block:: php

$container->loadFromExtension('framework', array(
'trusted_hosts' => array('.*\.?acme.com$', '.*\.?acme.org$'),
));

In addition, you can also set the trusted hosts in the front controller using
the ``Request::setTrustedHosts()`` method::

// web/app.php
Request::setTrustedHosts(array('.*\.?acme.com$', '.*\.?acme.org$'));

The default value for this option is an empty array, meaning that the application
can respond to any given host.

.. _reference-framework-trusted-proxies:

trusted_proxies
Expand Down