Skip to content

[Cookbook][Security] Added doc for x509 pre authenticated listener #3913

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

Merged
merged 5 commits into from
Jun 9, 2014
Merged

[Cookbook][Security] Added doc for x509 pre authenticated listener #3913

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6c9a204
[Cookbook][Security] x509 doc for pre authenticated listeners
Jun 6, 2014
f5a6d58
Added pre_authenticated to map.rst
Jun 6, 2014
83c40e9
Corrected pre_authenticated cookbook entry
Jun 6, 2014
01d18fe
fixing last issues in pre_authenticated cookbook entry
Jun 6, 2014
57cc957
full xml config, pushed the note at the end of the entry
mdouailin Jun 8, 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
1 change: 1 addition & 0 deletions cookbook/map.rst.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,7 @@
* :doc:`/cookbook/security/securing_services`
* :doc:`/cookbook/security/custom_provider`
* :doc:`/cookbook/security/custom_authentication_provider`
* :doc:`/cookbook/security/pre_authenticated`
* :doc:`/cookbook/security/target_path`
* :doc:`/cookbook/security/csrf_in_login_form`

Expand Down
1 change: 1 addition & 0 deletions cookbook/security/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,5 +16,6 @@ Security
securing_services
custom_provider
custom_authentication_provider
pre_authenticated
Copy link
Member

Choose a reason for hiding this comment

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

This also needs to be added to /cookbook/map.rst.inc.

target_path
csrf_in_login_form
72 changes: 72 additions & 0 deletions cookbook/security/pre_authenticated.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
.. index::
single: Security; Pre authenticated providers

Using pre Authenticated Security Firewalls
==========================================

A lot of authentication modules are already provided by some webservers,
Copy link
Member

Choose a reason for hiding this comment

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

I think "web servers" is a bit more correct?

including Apache. These modules generally set some environment variables
that can be used to determine which user is accessing your application. Out of the
box, Symfony supports most authentication mechanisms.
These requests are called *pre authenticated* requests because the user is already
authenticated when reaching your application.

.. note::

An authentication provider will only inform the user provider of the username
that made the request. You will need to either use an available
:class:`Symfony\\Component\\Security\\Core\\User\\UserProviderInterface`
or implement your own:
Copy link
Member

Choose a reason for hiding this comment

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

How about:

You will need to create (or use) a "user provider" that turns that username into a User object if your choice.

Copy link
Member

Choose a reason for hiding this comment

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

Hmm, and I'm thinking that we should move this down to the end of the entry, and mix it with the conversation about SSL_CLIENT_S_DN_Email and mention the your_user_provider key specifically. I think people will jump straight down to the code block and ask: "What is this your_user_provider?". I want to tell them that your_user_provider is a user provider, here are some links, and that the SSL_CLIENT_S_DN_Email will be passed in as the username to the user provider.

And what is the use-cause for needing SSL_CLIENT_S_DN? I'm not familiar with X509. I'm asking because usually, once a user is authenticated (which is taken care of by the core 509 classes), you don't care about the Token class. And I think that the credentials on the token are even cleared after authentication (unless security.erase_credentials is set to false).

Thanks!

Copy link
Author

Choose a reason for hiding this comment

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

I don't know exactly what use-case there is for the credentials in the PreAuthenticatedToken class, but I thought it would be great to document this feature because my PR on REMOTE_USER is also based on the PreAuthenticatedAuthenticationProvider and these features are not really documented.

I think @fabpot implemented the X509 auth and might be able to answer that question.


* :doc:`/cookbook/security/entity_provider`
* :doc:`/cookbook/security/custom_provider`

X.509 Client Certificate Authentication
---------------------------------------

When using client certificates, your webserver is doing all the authentication
process itself. With Apache, for example, you would use the
``SSLVerifyClient Require`` directive.
Copy link
Member

Choose a reason for hiding this comment

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

I'd reword this a bit:

With Apache, for example, you would use the SSLVerifyClient Require directive.


Enable the x509 authentication for a particular firewall in the security configuration:

.. configuration-block::

.. code-block:: yaml

# app/config/security.yml
security:
firewalls:
secured_area:
pattern: ^/
x509:
provider: your_user_provider

.. code-block:: xml

<!-- app/config/security.xml -->
<config>
<firewall name="secured_area" pattern="^/">
<x509 provider="your_user_provider"/>
</firewall>
</config>

.. code-block:: php

// app/config/security.php
$container->loadFromExtension('security', array(
'firewalls' => array(
'secured_area' => array(
'pattern' => '^/'
'x509' => array(
'provider' => 'your_user_provider',
),
),
),
));

By default, the firewall provides the ``SSL_CLIENT_S_DN_Email`` variable to
the user provider, and sets the ``SSL_CLIENT_S_DN`` as credentials in the
:class:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\PreAuthenticatedToken`.
You can override these by setting the ``user`` and the ``credentials`` keys
in the x509 firewall configuration respectively.