New in Symfony 6.2: Access Token Authenticator

Contributed by
Florent Morselli
in #46428.

Access tokens, also called bearer tokens, are defined in RFC6750 and are popular when working with APIs. Any party in possession of an access token can use it to get access to the associated resources. That's why these tokens need to be protected from disclosure in storage and in transport.

In Symfony 6.2 we're adding a new authenticator which is able to fetch access tokens and retrieve the associated user identifier. The new authenticator can extract tokens from the request header (RFC6750 Section 2.1), the request body (RFC6750 Section 2.2) and the query string (RFC6750 Section 2.3).

To use this authenticator, define a firewall in your application and add the access_token option to it:

1
2
3
4
5
6
7
8

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

The token_handler option is the only mandatory option and defines the service that will handle the token (e.g. validate it) to retrieve the user associated to it. This service must implement AccessTokenHandlerInterface. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

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

use App\Repository\SomeTokenRepository
use Symfony\Component\Security\Core\Exception\BadCredentialsException;;
use Symfony\Component\Security\Http\AccessToken\AccessTokenHandlerInterface;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;

class AccessTokenHandler implements AccessTokenHandlerInterface
{
    public function __construct(
        private readonly SomeTokenRepository $repository,
    ) {
    }

    public function getUserBadgeFrom(string $token): UserBadge
    {
        $accessToken = $this->repository->findOneByValue($token);
        if (null === $accessToken || !$accessToken->isValid()) {
            throw new BadCredentialsException('Invalid credentials.');
        }

        return new UserBadge($accessToken->getUserId());
    }
}

Inside your token handler you must validate the given token. For example, if you use opaque tokens such as random strings stored in a database, check if they exist in the database; if you use self-contained tokens such as JWT, SAML2, etc. validate those according to their specs.

The new authenticator defines many config options which are explained in the Symfony Documentation, such as restricting where to look for tokens in the request, customizing the response for successful and failing authentication, etc.