Skip to content

[Security] Access Tokens #16819

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 3 commits into from
Nov 26, 2022
Merged

[Security] Access Tokens #16819

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
600bb80
Access Token Documentation
Spomky Aug 11, 2022
b65c136
Finish the docs for the new Access token authenticator
wouterj Nov 5, 2022
f3f47ad
Update docs for 6.2.0-RC1 changes to TokenHandlerInterface
Spomky Nov 25, 2022
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
9 changes: 9 additions & 0 deletions security.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1202,6 +1202,15 @@ website.

You can learn all about this authenticator in :doc:`/security/login_link`.

Access Tokens
~~~~~~~~~~~~~

Access Tokens are often used in API contexts.
The user receives a token from an authorization server
which authenticates them.

You can learn all about this authenticator in :doc:`/security/access_token`.

X.509 Client Certificates
~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down
348 changes: 348 additions & 0 deletions security/access_token.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,348 @@
.. index::
single: Security; Access Token

How to use Access Token Authentication
======================================

Access tokens or API tokens are commonly used as authentication mechanism
in API contexts. The access token is a string, obtained during authentication
(using the application or an authorization server). The access token's role
is to verify the user identity and receive consent before the token is
issued.

Access tokens can be of any kind, for instance opaque strings,
`JSON Web Tokens (JWT)`_ or `SAML2 (XML structures)`_. Please refer to the
`RFC6750`_: *The OAuth 2.0 Authorization Framework: Bearer Token Usage* for
a detailed specification.

Using the Access Token Authenticator
------------------------------------

This guide assumes you have setup security and have created a user object
in your application. Follow :doc:`the main security guide </security>` if
this is not yet the case.

1) Configure the Access Token Authenticator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To use the access token authenticator, you must configure a ``token_handler``.
The token handler receives the token from the request and returns the
correct user identifier. To get the user identifier, implementations may
need to load and validate the token (e.g. revocation, expiration time,
digital signature, etc.).

.. configuration-block::

.. code-block:: yaml

# config/packages/security.yaml
security:
firewalls:
main:
access_token:
token_handler: App\Security\AccessTokenHandler

.. code-block:: xml

<!-- config/packages/security.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
xmlns:srv="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/security
https://symfony.com/schema/dic/security/security-1.0.xsd">

<config>
<firewall name="main">
<access-token token-handler="App\Security\AccessTokenHandler"/>
</firewall>
</config>
</srv:container>

.. code-block:: php

// config/packages/security.php
use App\Security\AccessTokenHandler;
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security) {
$security->firewall('main')
->accessToken()
->tokenHandler(AccessTokenHandler::class)
;
};

This handler must implement
:class:`Symfony\\Component\\Security\\Http\\AccessToken\\AccessTokenHandlerInterface`::

// src/Security/AccessTokenHandler.php
namespace App\Security;

use App\Repository\AccessTokenRepository;
use Symfony\Component\Security\Http\AccessToken\AccessTokenHandlerInterface;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;

class AccessTokenHandler implements AccessTokenHandlerInterface
{
public function __construct(
private AccessTokenRepository $repository
) {
}

public function getUserBadgeFrom(string $accessToken): UserBadge
{
// e.g. query the "access token" database to search for this token
$accessToken = $this->repository->findOneByValue($token);
if (null === $accessToken || !$accessToken->isValid()) {
throw new BadCredentialsException('Invalid credentials.');
}

// and return a UserBadge object containing the user identifier from the found token
return new UserBadge($accessToken->getUserId());
}
}

The access token authenticator will use the returned user identifier to
load the user using the :ref:`user provider <security-user-providers>`.

.. caution::

It is important to check the token if is valid. For instance, the
example above verifies whether the token has not expired. With
self-contained access tokens such as JWT, the handler is required to
verify the digital signature and understand all claims, especially
``sub``, ``iat``, ``nbf`` and ``exp``.

2) Configure the Token Extractor (Optional)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The application is now ready to handle incoming tokens. A *token extractor*
retrieves the token from the request (e.g. a header or request body).

By default, the access token is read from the request header parameter
``Authorization`` with the scheme ``Bearer`` (e.g. ``Authorization: Bearer
the-token-value``).

Symfony provides other extractors as per the `RFC6750`_:

``header`` (default)
The token is sent through the request header. Usually ``Authorization``
with the ``Bearer`` scheme.
``query_string``
The token is part of the request query string. Usually ``access_token``.
``request_body``
The token is part of the request body during a POST request. Usually
``access_token``.

.. caution::

Because of the security weaknesses associated with the URI method,
including the high likelihood that the URL or the request body
containing the access token will be logged, methods ``query_string``
and ``request_body`` **SHOULD NOT** be used unless it is impossible to
transport the access token in the request header field.

You can also create a custom extractor. The class must implement
:class:`Symfony\\Component\\Security\\Http\\AccessToken\\AccessTokenExtractorInterface`.

.. configuration-block::

.. code-block:: yaml

# config/packages/security.yaml
security:
firewalls:
main:
access_token:
token_handler: App\Security\AccessTokenHandler

# use a different built-in extractor
token_extractors: request_body

# or provide the service ID of a custom extractor
token_extractors: 'App\Security\CustomTokenExtractor'

.. code-block:: xml

<!-- config/packages/security.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
xmlns:srv="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/security
https://symfony.com/schema/dic/security/security-1.0.xsd">

<config>
<firewall name="main">
<access-token token-handler="App\Security\AccessTokenHandler">
<!-- use a different built-in extractor -->
<token-extractor>request_body</token-extractor>

<!-- or provide the service ID of a custom extractor -->
<token-extractor>App\Security\CustomTokenExtractor</token-extractor>
</access-token>
</firewall>
</config>
</srv:container>

.. code-block:: php

// config/packages/security.php
use App\Security\AccessTokenHandler;
use App\Security\CustomTokenExtractor;
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security) {
$security->firewall('main')
->accessToken()
->tokenHandler(AccessTokenHandler::class)

// use a different built-in extractor
->tokenExtractors('request_body')

# or provide the service ID of a custom extractor
->tokenExtractors(CustomTokenExtractor::class)
;
};

It is possible to set multiple extractors. In this case, **the order is
important**: the first in the list is called first.

.. configuration-block::

.. code-block:: yaml

# config/packages/security.yaml
security:
firewalls:
main:
access_token:
token_handler: App\Security\AccessTokenHandler
token_extractors:
- 'header'
- 'App\Security\CustomTokenExtractor'

.. code-block:: xml

<!-- config/packages/security.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
xmlns:srv="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/security
https://symfony.com/schema/dic/security/security-1.0.xsd">

<config>
<firewall name="main">
<access-token token-handler="App\Security\AccessTokenHandler">
<token-extractor>header</token-extractor>
<token-extractor>App\Security\CustomTokenExtractor</token-extractor>
</access-token>
</firewall>
</config>
</srv:container>

.. code-block:: php

// config/packages/security.php
use App\Security\AccessTokenHandler;
use App\Security\CustomTokenExtractor;
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security) {
$security->firewall('main')
->accessToken()
->tokenHandler(AccessTokenHandler::class)
->tokenExtractors([
'header',
CustomTokenExtractor::class,
])
;
};

3) Submit a Request
~~~~~~~~~~~~~~~~~~~

That's it! Your application can now authenticate incoming requests using an
API token.

Using the default header extractor, you can test the feature by submitting
a request like this:

.. code-block:: terminal

$ curl -H 'Authorization: Bearer an-accepted-token-value' \
https://localhost:8000/api/some-route

Customizing the Success Handler
-------------------------------

By default, the request continues (e.g. the controller for the route is
run). If you want to customize success handling, create your own success
handler by creating a class that implements
:class:`Symfony\\Component\\Security\\Http\\Authentication\\AuthenticationSuccessHandlerInterface`
and configure the service ID as the ``success_handler``:

.. configuration-block::

.. code-block:: yaml

# config/packages/security.yaml
security:
firewalls:
main:
access_token:
token_handler: App\Security\AccessTokenHandler
success_handler: App\Security\Authentication\AuthenticationSuccessHandler

.. code-block:: xml

<!-- config/packages/security.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
xmlns:srv="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/security
https://symfony.com/schema/dic/security/security-1.0.xsd">

<config>
<firewall name="main">
<access-token token-handler="App\Security\AccessTokenHandler"
success-handler="App\Security\Authentication\AuthenticationSuccessHandler"
/>
</firewall>
</config>
</srv:container>

.. code-block:: php

// config/packages/security.php
use App\Security\AccessTokenHandler;
use App\Security\Authentication\AuthenticationSuccessHandler;
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security) {
$security->firewall('main')
->accessToken()
->tokenHandler(AccessTokenHandler::class)
->successHandler(AuthenticationSuccessHandler::class)
;
};

.. tip::

If you want to customize the default failure handling, use the
``failure_handler`` option and create a class that implements
:class:`Symfony\\Component\\Security\\Http\\Authentication\\AuthenticationFailureHandlerInterface`.

.. _`Json Web Tokens (JWT)`: https://datatracker.ietf.org/doc/html/rfc7519
.. _`SAML2 (XML structures)`: https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html
.. _`RFC6750`: https://datatracker.ietf.org/doc/html/rfc6750