10000 JSON authentication listener docs · symfony/symfony-docs@68bd9a5 · GitHub
[go: up one dir, main page]
Skip to content

Commit 68bd9a5

Browse files
dunglasdunglas
committed
JSON authentication listener docs
1 parent 152aecc commit 68bd9a5

File tree

1 file changed

+168
-0
lines changed

1 file changed

+168
-0
lines changed

‎security/json_login_setup.rst

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
How to Build a JSON Authentication Endpoint
2+
===========================================
3+
4+
.. tip::
5+
6+
If you are storing users in some sort of a database, then you should consider
7+
using `FOSUserBundle`_, which helps you build your ``User`` object and gives
8+
you many routes and controllers for common tasks like login, registration and
9+
forgot password.
10+
11+
In this entry, you'll build a JSON endpoint to log in your users. Of course, when the
12+
user logs in, you can load your users from anywhere - like the database.
13+
See :ref:`security-user-providers` for details.
14+
15+
First, enable form login under your firewall:
16+
17+
.. configuration-block::
18+
19+
.. code-block:: yaml
20+
21+
# app/config/security.yml
22+
security:
23+
# ...
24+
25+
firewalls:
26+
main:
27+
anonymous: ~
28+
json_login:
29+
check_path: login
30+
username_path: user.login
31+
password_path: user.password
32+
33+
.. code-block:: xml
34+
35+
<!-- app/config/security.xml -->
36+
<?xml version="1.0" encoding="UTF-8"?>
37+
<srv:container xmlns="http://symfony.com/schema/dic/security"
38+
xmlns:srv="http://symfony.com/schema/dic/services"
39+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
40+
xsi:schemaLocation="http://symfony.com/schema/dic/services
41+
http://symfony.com/schema/dic/services/services-1.0.xsd">
42+
43+
<config>
44+
<firewall name="main">
45+
<anonymous />
46+
<json-login check-path="login" username-path="user.login" password-path="user.password" />
47+
</firewall>
48+
</config>
49+
</srv:container>
50+
51+
.. code-block:: php
52+
53+
// app/config/security.php
54+
$container->loadFromExtension('security', array(
55+
'firewalls' => array(
56+
'main' => array(
57+
'anonymous' => null,
58+
'json_login' => array(
59+
'check_path' => 'login',
60+
'username_path' => 'user.login',
61+
'password_path' => 'user.password',
62+
),
63+
),
64+
),
65+
));
66+
67+
.. tip::
68+
69+
The ``check_path`` can also be route names (but cannot have mandatory wildcards - e.g.
70+
``/login/{foo}`` where ``foo`` has no default value).
71+
72+
Create a new ``SecurityController`` inside a bundle::
73+
74+
// src/AppBundle/Controller/SecurityController.php
75+
namespace AppBundle\Controller;
76+
77+
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
78+
79+
class SecurityController extends Controller
80+
{
81+
}
82+
83+
Next, configure the route that you earlier used under your ``json_login``
84+
configuration (``login``):
85+
86+
.. configuration-block::
87+
88+
.. code-block:: php-annotations
89+
90+
// src/AppBundle/Controller/SecurityController.php
91+
92+
// ...
93+
use Symfony\Component\HttpFoundation\Request;
94+
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
95+
96+
class SecurityController extends Controller
97+
{
98+
/**
99+
* @Route("/login", name="login")
100+
*/
101+
public function loginAction(Request $request)
102+
{
103+
}
104+
}
105+
106+
.. code-block:: yaml
107+
108+
# app/config/routing.yml
109+
login:
110+
path: /login
111+
defaults: { _controller: AppBundle:Security:login }
112+
113+
.. code-block:: xml
114+
115+
<!-- app/config/routing.xml -->
116+
<?xml version="1.0" encoding="UTF-8" ?>
117+
<routes xmlns="http://symfony.com/schema/routing"
118+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
119+
xsi:schemaLocation="http://symfony.com/schema/routing
120+
http://symfony.com/schema/routing/routing-1.0.xsd">
121+
122+
<route id="login" path="/login">
123+
<default key="_controller">AppBundle:Security:login</default>
124+
</route>
125+
</routes>
126+
127+
.. code-block:: php
128+
129+
// app/config/routing.php
130+
use Symfony\Component\Routing\RouteCollection;
131+
use Symfony\Component\Routing\Route;
132+
133+
$collection = new RouteCollection();
134+
$collection->add('login', new Route('/login', array(
135+
'_controller' => 'AppBundle:Security:login',
136+
)));
137+
138+
return $collection;
139+
140+
Great!
141+
142+
Don't let this controller confuse you. As you'll see in a moment, when the
143+
user submits the form, the security system automatically handles the form
144+
submission for you. If the user submits an invalid username or password,
145+
this controller reads the form submission error from the security system,
146+
so that it can be displayed back to the user.
147+
148+
In other words the security system itself takes care of checking the submitted
149+
username and password and authenticating the user.
150+
151+
And that's it! When you submit a ``POST`` request to the ``/login`` URL with
152+
the following JSON document as body, the security system will automatically
153+
check the user's credentials and either authenticate the user or throw an error::
154+
155+
.. code-block:: json
156+
157+
{
158+
"user": {
159+
"login": "dunglas",
160+
"password": "MyPassword"
161+
}
162+
}
163+
164+
You can specify the path to access to the user and password in the JSON document
165+
using the ``username_path`` and the ``password_path`` keys. They default respectively
166+
to ``username`` and ``password``.
167+
168+
.. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle

0 commit comments

Comments
 (0)
0