How to use Access Token Authentication

Access tokens are commonly used in API contexts. The access token is obtained

through an authorization server (or similar) whose role is to verify the user identity

and receive consent before the token is issued.

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: opaque strings, Json Web Tokens (JWT) or SAML2 (XML structures).

Please refer to the `RFC6750`_: *The OAuth 2.0 Authorization Framework: Bearer Token Usage*.

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

To use the access token authenticator, you must configure a ``token_handler``.

The token handler retrieves the user identifier from the token.

In order to get the user identifier, implementations may need to load and validate

the token (e.g. revocation, expiration time, digital signature...).

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::

This handler shall implement the interface

:class:`Symfony\\Component\\Security\\Http\\AccessToken\\AccessTokenHandlerInterface`.

In the following example, the handler will retrieve the token from a database

using a fictive repository.

..configuration-block::

..code-block::xml

..code-block::php

This handler must implement

:class:`Symfony\\Component\\Security\\Http\\AccessToken\\AccessTokenHandlerInterface`::

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 is valid.

For instance, in theexamplewe verifythe token has not expired.

Withself-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``.

It is important to check the tokenifis valid. For instance, the

exampleabove verifies whetherthe 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``.

CustomizingtheAuthenticator

2) ConfiguretheToken Extractor (Optional)

1) Access Token Extractors

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

You can change the behavior and send the access token through different ways.

By default, the access token is read from the request header parameter

``Authorization`` with the scheme ``Bearer`` (e.g. ``Authorization: Bearer

the-token-value``).

This authenticatorprovidesservices able to extract the access tokenas per the RFC6750:

Symfonyprovidesother extractorsas per the`RFC6750`_:

- ``header`` or ``security.access_token_extractor.header``: the token is sent through the request header. Usually ``Authorization`` with the ``Bearer`` scheme.

- ``query_string`` or ``security.access_token_extractor.query_string``: the token is part of the query string. Usually ``access_token``.

- ``request_body`` or ``security.access_token_extractor.request_body``: the token is part of the request body during a POST request. Usually ``access_token``.

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

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.

Also, youcan also create a custom extractor. The classshall implement the interface

Youcan also create a custom extractor. The classmust implement

:class:`Symfony\\Component\\Security\\Http\\AccessToken\\AccessTokenExtractorInterface`.

..configuration-block::

It is possible to set multiple extractors.

In this case, **the order is important**: the first in the list is called first.

..code-block::xml

..code-block::php

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::xml

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:

Then, configure this service ID as the ``success_handler``:

..code-block::terminal

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::xml

..code-block::php

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