How to use Access Token Authentication

Warning: You are browsing the documentation for Symfony 6.3, which is no longer maintained.

Read the updated version of this page for Symfony 7.2 (the current stable version).

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 the main security guide 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.).

1
2
3
4
5
6
# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler: App\Security\AccessTokenHandler

This handler must implement AccessTokenHandlerInterface:

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
26
// 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($accessToken);
        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 user provider.

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 AccessTokenExtractorInterface.

1
2
3
4
5
6
7
8
9
10
11
12
# 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'

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

1
2
3
4
5
6
7
8
9
# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler: App\Security\AccessTokenHandler
                token_extractors:
                    - 'header'
                    - 'App\Security\CustomTokenExtractor'

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:

1
2
$ 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 AuthenticationSuccessHandlerInterface and configure the service ID as the success_handler:

1
2
3
4
5
6
7
# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler: App\Security\AccessTokenHandler
                success_handler: App\Security\Authentication\AuthenticationSuccessHandler

Tip

If you want to customize the default failure handling, use the failure_handler option and create a class that implements AuthenticationFailureHandlerInterface.

Using OpenID Connect (OIDC)

OpenID Connect (OIDC) is the third generation of OpenID technology and it's a RESTful HTTP API that uses JSON as its data format. OpenID Connect is an authentication layer on top of the OAuth 2.0 authorization framework. It allows to verify the identity of an end user based on the authentication performed by an authorization server.

Caution

This feature is experimental and could change or be removed at any time without prior notice.

1) Configure the OidcUserInfoTokenHandler

6.3

The OidcUserInfoTokenHandler class was introduced in Symfony 6.3.

The OidcUserInfoTokenHandler requires the symfony/http-client package to make the needed HTTP requests. If you haven't installed it yet, run this command:

1
$ composer require symfony/http-client

Symfony provides a generic OidcUserInfoTokenHandler to call your OIDC server and retrieve the user info:

1
2
3
4
5
6
7
# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    oidc_user_info: https://www.example.com/realms/demo/protocol/openid-connect/userinfo

Following the OpenID Connect Specification, the sub claim is used as user identifier by default. To use another claim, specify it on the configuration:

1
2
3
4
5
6
7
8
9
# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    oidc_user_info:
                        claim: email
                        base_uri: https://www.example.com/realms/demo/protocol/openid-connect/userinfo

The oidc_user_info token handler automatically creates an HTTP client with the specified base_uri. If you prefer using your own client, you can specify the service name via the client option:

1
2
3
4
5
6
7
8
# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    oidc_user_info:
                        client: oidc.client

By default, the OidcUserInfoTokenHandler creates an OidcUser with the claims. To create your own user object from the claims, you must create your own UserProvider:

1
2
3
4
5
6
7
8
9
10
// src/Security/Core/User/OidcUserProvider.php
use Symfony\Component\Security\Core\User\AttributesBasedUserProviderInterface;

class OidcUserProvider implements AttributesBasedUserProviderInterface
{
    public function loadUserByIdentifier(string $identifier, array $attributes = []): UserInterface
    {
        // implement your own logic to load and return the user object
    }
}

2) Configure the OidcTokenHandler

6.3

The OidcTokenHandler class was introduced in Symfony 6.3.

The OidcTokenHandler requires web-token/jwt-signature, web-token/jwt-checker and web-token/jwt-signature-algorithm-ecdsa packages. If you haven't installed them yet, run these commands:

1
2
3
$ composer require web-token/jwt-signature
$ composer require web-token/jwt-checker
$ composer require web-token/jwt-signature-algorithm-ecdsa

Symfony provides a generic OidcTokenHandler to decode your token, validate it and retrieve the user info from it:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    oidc:
                        # Algorithm used to sign the JWS
                        algorithm: 'ES256'
                        # A JSON-encoded JWK
                        key: '{"kty":"...","k":"..."}'
                        # Audience (`aud` claim): required for validation purpose
                        audience: 'api-example'
                        # Issuers (`iss` claim): required for validation purpose
                        issuers: ['https://oidc.example.com']

Following the OpenID Connect Specification, the sub claim is used by default as user identifier. To use another claim, specify it on the configuration:

1
2
3
4
5
6
7
8
9
10
11
12
# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    oidc:
                        claim: email
                        algorithm: 'ES256'
                        key: '{"kty":"...","k":"..."}'
                        audience: 'api-example'
                        issuers: ['https://oidc.example.com']

By default, the OidcTokenHandler creates an OidcUser with the claims. To create your own User from the claims, you must create your own UserProvider:

1
2
3
4
5
6
7
8
9
10
// src/Security/Core/User/OidcUserProvider.php
use Symfony\Component\Security\Core\User\AttributesBasedUserProviderInterface;

class OidcUserProvider implements AttributesBasedUserProviderInterface
{
    public function loadUserByIdentifier(string $identifier, array $attributes = []): UserInterface
    {
        // implement your own logic to load and return the user object
    }
}

Creating Users from Token

6.3

The possibility to omit the user provider in case of stateless firewalls was introduced in Symfony 6.3.

Some types of tokens (for instance OIDC) contain all information required to create a user entity (e.g. username and roles). In this case, you don't need a user provider to create a user from the database:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// src/Security/AccessTokenHandler.php
namespace App\Security;

// ...
class AccessTokenHandler implements AccessTokenHandlerInterface
{
    // ...

    public function getUserBadgeFrom(string $accessToken): UserBadge
    {
        // get the data from the token
        $payload = ...;

        return new UserBadge(
            $payload->getUserId(),
            fn (string $userIdentifier) => new User($userIdentifier, $payload->getRoles())
        );
    }
}

When using this strategy, you can omit the user_provider configuration for stateless firewalls.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version