How to use Access Token Authentication

Using the Access Token Authenticator

This guide assumes you have set up security and have created a user object in your application. Follow the main security guide if this is not yet the case.

1
2
3
4
5
6

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Security\AccessTokenHandler;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => AccessTokenHandler::class,
                ],
            ],
        ],
    ],
]);

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
27
28
29

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

use App\Repository\AccessTokenRepository;
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 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
        // (this is the same identifier used in Security configuration; it can be an email,
        // a UUID, a username, a database ID, etc.)
        return new UserBadge($accessToken->getUserId());
    }
}

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'

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Security\AccessTokenHandler;
use App\Security\CustomTokenExtractor;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => AccessTokenHandler::class,

                    // use a different built-in extractor
                    'token_extractors' => 'request_body',

                    // or provide the service ID of a custom extractor
                    'token_extractors' => CustomTokenExtractor::class,
                ],
            ],
        ],
    ],
]);

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'

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Security\AccessTokenHandler;
use App\Security\CustomTokenExtractor;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => AccessTokenHandler::class,
                    'token_extractors' => [
                        'header',
                        CustomTokenExtractor::class,
                    ],
                ],
            ],
        ],
    ],
]);

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Security\AccessTokenHandler;
use App\Security\Authentication\AuthenticationSuccessHandler;

return App::config([
    'security' => [
    'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => AccessTokenHandler::class,
                    'success_handler' => AuthenticationSuccessHandler::class,
                ],
            ],
        ],
    ],
]);

Publishing the Protected Resource Metadata

Clients that don't have an access token yet (e.g. MCP clients) must find out which authorization servers issue the tokens accepted by your API. RFC 9728 solves this with a JSON document that the API publishes at /.well-known/oauth-protected-resource and with a resource_metadata parameter in the WWW-Authenticate header of 401 responses, which points to that document.

Add the resource_metadata option to the access_token authenticator to publish this document and to add its URL to the 401 responses:

1
2
3
4
5
6
7
8
9
10
11
12
13

# config/packages/security.yaml
security:
    firewalls:
        api:
            access_token:
                realm: 'My API'
                token_extractors: ['header', 'query_string']
                token_handler: App\Security\AccessTokenHandler
                resource_metadata:
                    authorization_servers: ['https://accounts.example.com']
                    scopes_supported: ['profile', 'email']
                    resource_name: 'My API'
                    resource_documentation: 'https://api.example.com/docs'

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Security\AccessTokenHandler;

return App::config([
    'security' => [
        'firewalls' => [
            'api' => [
                'access_token' => [
                    'realm' => 'My API',
                    'token_extractors' => ['header', 'query_string'],
                    'token_handler' => AccessTokenHandler::class,
                    'resource_metadata' => [
                        'authorization_servers' => ['https://accounts.example.com'],
                        'scopes_supported' => ['profile', 'email'],
                        'resource_name' => 'My API',
                        'resource_documentation' => 'https://api.example.com/docs',
                    ],
                ],
            ],
        ],
    ],
]);

Symfony defines the route of this document in the security route loader. If your project uses Symfony Flex, the SecurityBundle recipe already imports it. Otherwise, import it yourself:

1
2
3
4

# config/routes/security.yaml
_security:
    resource: security.route_loader
    type: service

1
2
3
4
5
6
7
8
9

// config/routes/security.php
namespace Symfony\Component\Routing\Loader\Configurator;

return Routes::config([
    '_security' => [
        'resource' => 'security.route_loader',
        'type' => 'service',
    ],
]);

Clients must be able to get this document without a token, so don't add any access control rule that requires authentication for its path.

If your API runs at https://api.example.com, a GET /.well-known/oauth-protected-resource request now returns:

1
2
3
4
5
6
7
8

{
    "resource": "https://api.example.com",
    "authorization_servers": ["https://accounts.example.com"],
    "scopes_supported": ["profile", "email"],
    "bearer_methods_supported": ["header", "query"],
    "resource_name": "My API",
    "resource_documentation": "https://api.example.com/docs"
}

Requests without a token get a 401 response with the following header, unless another authenticator of the firewall (e.g. form_login) is its entry point:

1

WWW-Authenticate: Bearer realm="My API",resource_metadata="https://api.example.com/.well-known/oauth-protected-resource"

Requests with a token rejected by the firewall get the same URL next to the error details:

1

WWW-Authenticate: Bearer realm="My API",error="invalid_token",error_description="Invalid credentials.",resource_metadata="https://api.example.com/.well-known/oauth-protected-resource"

These are the options of resource_metadata. Each of them is a metadata parameter defined by RFC 9728 and it's left out of the document when it has no value:

resource

The identifier of the protected resource. It must be an HTTPS URL without a fragment, but HTTP is allowed for loopback hosts (localhost, 127.0.0.1, ::1) and hostnames reserved for testing (*.localhost, *.test). By default, it's the origin (scheme, host and port) of the request, which is correct when the firewall protects the whole application.

If the URL includes a path, that path is added after the well-known path, as defined in Section 3.1 of the RFC. For example, the metadata of https://example.com/api is served at /.well-known/oauth-protected-resource/api. This allows several firewalls of the same host to publish their own metadata, as long as each of them uses a different path.

Symfony reads this path when compiling the container, so you can't use an environment variable as the whole value. Use it inside the URL instead (e.g. https://%env(API_HOST)%/v1).

authorization_servers

The issuer identifiers of the authorization servers that issue the access tokens accepted by this firewall (e.g. https://accounts.example.com). Clients use them to know where to get a token. It defaults to the issuers option of the oidc token handler or to the issuer option of the oauth2 token handler. Set it explicitly when the oidc token handler uses OpenID Connect Discovery without defining the issuers option.

jwks_uri

The URL of the JWK Set with the keys that your API uses to sign its own responses. These are not the keys used to verify the access tokens, which belong to the authorization server.

scopes_supported

The scope values used by your API.

bearer_methods_supported

The ways clients can send the token to your API (header, body or query). If you don't set this option, Symfony computes it from the token_extractors option (header becomes header, request_body becomes body and query_string becomes query). Custom extractors are ignored, so set this option explicitly when using them.

resource_name

The human-readable name of your API, which clients can display to end users.

resource_documentation

The URL of the developer documentation of your API.

resource_policy_uri

The URL of the policy that explains how clients can use the data returned by your API.

resource_tos_uri

The URL of the terms of service of your API.

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 you to verify the identity of an end user based on the authentication performed by an authorization server.

1

$ composer require symfony/http-client

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'oidc_user_info' => 'https://www.example.com/realms/demo/protocol/openid-connect/userinfo',
                    ],
                ],
            ],
        ],
    ],
]);

1

$ composer require symfony/cache

1
2
3
4
5
6
7
8
9

# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    oidc_user_info:
                        base_uri: https://www.example.com/realms/demo/
                        discovery: true

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'oidc_user_info' => [
                            'base_uri' => 'https://www.example.com/realms/demo/',
                            'discovery' => true,
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'oidc_user_info' => [
                            'claim' => 'email',
                            'base_uri' => 'https://www.example.com/realms/demo/protocol/openid-connect/userinfo',
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'oidc_user_info' => [
                            'client' => 'oidc.client',
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

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

1

$ composer require web-token/jwt-library

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
27
28

# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    oidc:
                        # Algorithms used to sign the JWS
                        algorithms: ['ES256', 'RS256']
                        # A JSON-encoded JWK
                        keyset: '{"keys":[{"kty":"...","k":"..."}]}'
                        # Audience (`aud` claim): required for validation purpose
                        audience: 'api-example'
                        # Issuers (`iss` claim): required for validation purpose
                        # (optional when using OpenID Connect Discovery)
                        issuers: ['https://oidc.example.com']
                        # Tolerance in seconds for clock differences between the token
                        # issuer and this application, applied when validating the
                        # time-based claims (`iat`, `nbf`, `exp`)
                        allowed_time_drift: 5 # Default to 0 (no tolerance)
                        # Requires the `typ` header of the token to be
                        # `at+jwt` or `application/at+jwt` (RFC 9068)
                        enforce_at_jwt_type: true # Default to false
                        encryption:
                            enabled: true # Default to false
                            enforce: false # Default to false, requires an encrypted token when true
                            algorithms: ['ECDH-ES', 'A128GCM']
                            keyset: '{"keys": [...]}' # Encryption private keyset

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
27
28
29
30
31
32
33
34
35
36
37
38
39
40

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'oidc' => [
                            // Algorithms used to sign the JWS
                            'algorithms' => ['ES256', 'RS256'],
                            // A JSON-encoded JWK
                            'keyset' => '{"keys":[{"kty":"...","k":"..."}]}',
                            // Audience (`aud` claim): required for validation purpose
                            'audience' => 'api-example',
                            // Issuers (`iss` claim): required for validation purpose
                            // (optional when using OpenID Connect Discovery)
                            'issuers' => ['https://oidc.example.com'],
                            // Tolerance in seconds for clock differences between the tokens
                            // issuer and this application, applied when validating the
                            // time-based claims (`iat`, `nbf`, `exp`)
                            'allowed_time_drift' => 5, // Default to 0 (no tolerance)
                            // Requires the `typ` header of the token to be
                            // `at+jwt` or `application/at+jwt` (RFC 9068)
                            'enforce_at_jwt_type' => true, // Default to false
                            // Encryption:
                            'encryption' => [
                                'enabled' => true, // Default to false
                                'enforce' => false, // Default to false, requires an encrypted token when true
                                'algorithms' => ['ECDH-ES', 'A128GCM'],
                                'keyset' => '{"keys": [...]}' // Encryption private keyset
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

1

$ composer require symfony/cache

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
                        algorithms: ['ES256', 'RS256']
                        audience: 'api-example'
                        discovery:
                            base_uri: https://www.example.com/realms/demo/

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'oidc' => [
                            'claim' => 'email',
                            'algorithms' => ['ES256', 'RS256'],
                            'audience' => 'api-example',
                            'discovery' => [
                                'base_uri' => 'https://www.example.com/realms/demo/',
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

1
2
3
4
5
6
7
8
9
10

security:
    firewalls:
        main:
            access_token:
                token_handler:
                    oidc:
                        # ...
                        discovery:
                            base_uri: https://www.example.com/realms/demo/
                            enforce_key_usage_verification: false

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'oidc' => [
                            // ...
                            'discovery' => [
                                'base_uri' => 'https://www.example.com/realms/demo/',
                                'enforce_key_usage_verification' => false,
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

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
                        algorithms: ['ES256', 'RS256']
                        keyset: '{"keys":[{"kty":"...","k":"..."}]}'
                        audience: 'api-example'
                        issuers: ['https://oidc.example.com']

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'oidc' => [
                            'claim' => 'email',
                            'algorithms' => ['ES256', 'RS256'],
                            'keyset' => '{"keys":[{"kty":"...","k":"..."}]}',
                            'audience' => 'api-example',
                            'issuers' => ['https://oidc.example.com'],
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

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

1
2
3
4
5
6
7
8
9
10
11
12
13

# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    oidc:
                        algorithms: ['ES256', 'RS256']
                        audience: 'api-example'
                        discovery:
                            base_uri:
                                - https://idp1.example.com/realms/demo/
                                - https://idp2.example.com/realms/demo/

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'oidc' => [
                            'algorithms' => ['ES256', 'RS256'],
                            'audience' => 'api-example',
                            'discovery' => [
                                'base_uri' => [
                                    'https://idp1.example.com/realms/demo/',
                                    'https://idp2.example.com/realms/demo/',
                                ],
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

1
2
3
4
5
6
7
8
9
10
11
12
13

# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    oidc:
                        # ...
                        discovery:
                            base_uri: https://idp.example.com/realms/demo/
                            # a trailing slash in the base URI or in the
                            # announced issuer is ignored when comparing them
                            check_issuer: true

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'oidc' => [
                            // ...
                            'discovery' => [
                                'base_uri' => 'https://idp.example.com/realms/demo/',
                                // a trailing slash in the base URI or in the
                                // announced issuer is ignored when comparing them
                                'check_issuer' => true,
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

1
2
3
4
5
6
7
8
9
10
11
12
13

# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    oidc:
                        # ...
                        discovery:
                            base_uri: https://login.microsoftonline.com/<tenant>/
                            # ...
                            check_issuer:
                                'https://login.microsoftonline.com/<tenant>/': 'https://sts.windows.net/<tenant>/'

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'oidc' => [
                            // ...
                            'discovery' => [
                                'base_uri' => 'https://login.microsoftonline.com/<tenant>/',
                                // ...
                                'check_issuer' => [
                                    'https://login.microsoftonline.com/<tenant>/' => 'https://sts.windows.net/<tenant>/',
                                ],
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

1
2
3
4
5
6
7
8
9
10
11
12
13

# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    oidc:
                        algorithms: ['ES256', 'RS256']
                        keyset: '{"keys":[{"kty":"...","k":"..."}]}'
                        audience:
                            - 'https://api.example.com'
                            - 'https://admin.example.com'
                        issuers: ['https://oidc.example.com']

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'oidc' => [
                            'algorithms' => ['ES256', 'RS256'],
                            'keyset' => '{"keys":[{"kty":"...","k":"..."}]}',
                            'audience' => [
                                'https://api.example.com',
                                'https://admin.example.com',
                            ],
                            'issuers' => ['https://oidc.example.com'],
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    oidc:
                        algorithms: ['ES256', 'RS256']
                        keyset: '%env(OIDC_KEYSET)%'
                        # OIDC_AUDIENCES contains a JSON list of identifiers
                        audience: '%env(json:OIDC_AUDIENCES)%'
                        # for a single identifier, don't use any processor
                        # audience: '%env(OIDC_AUDIENCE)%'
                        issuers: ['https://oidc.example.com']

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'oidc' => [
                            'algorithms' => ['ES256', 'RS256'],
                            'keyset' => '%env(OIDC_KEYSET)%',
                            // OIDC_AUDIENCES contains a JSON list of identifiers
                            'audience' => '%env(json:OIDC_AUDIENCES)%',
                            // for a single identifier, don't use any processor
                            // 'audience' => '%env(OIDC_AUDIENCE)%',
                            'issuers' => ['https://oidc.example.com'],
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

Creating an OIDC token from the command line

The security:oidc:generate-token command helps you generate JWTs. It's mostly useful when developing or testing applications that use OIDC authentication:

1
2
3
4
5
6
7
8

# generate a token using the default configuration
$ php bin/console security:oidc:generate-token john.doe@example.com

# specify the firewall, algorithm, and issuer if multiple are available
$ php bin/console security:oidc:generate-token john.doe@example.com \
    --firewall="api" \
    --algorithm="HS256" \
    --issuer="https://example.com"

Using OAuth 2.0 Token Introspection

Use OAuth 2.0 Token Introspection (RFC 7662) when your application receives opaque access tokens that only the authorization server can validate. The oauth2 token handler sends each token to the introspection endpoint of that server and creates an OAuth2User from its response, so your application never reads the token itself.

This token handler 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

The URL of the introspection endpoint and the credentials your application uses to call it are configured in the HTTP client, not in the firewall. Define a scoped client whose base_uri is the introspection endpoint and whose auth_basic option holds the client ID and secret of your application:

1
2
3
4
5
6
7

# config/packages/framework.yaml
framework:
    http_client:
        scoped_clients:
            oauth2.introspection:
                base_uri: 'https://auth.example.com/introspect'
                auth_basic: '%env(OAUTH2_ID)%:%env(OAUTH2_SECRET)%'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// config/packages/framework.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'framework' => [
        'http_client' => [
            'scoped_clients' => [
                'oauth2.introspection' => [
                    'base_uri' => 'https://auth.example.com/introspect',
                    'auth_basic' => '%env(OAUTH2_ID)%:%env(OAUTH2_SECRET)%',
                ],
            ],
        ],
    ],
]);

Then, pass the service ID of that client to the http_client option of the token handler and define the values used to validate the response:

1
2
3
4
5
6
7
8
9
10
11
12

# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    oauth2:
                        http_client: 'oauth2.introspection'
                        issuer: 'https://auth.example.com/'
                        audience: 'https://api.example.com'
                        claim: 'sub'
                        allowed_time_drift: 5

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'oauth2' => [
                            'http_client' => 'oauth2.introspection',
                            'issuer' => 'https://auth.example.com/',
                            'audience' => 'https://api.example.com',
                            'claim' => 'sub',
                            'allowed_time_drift' => 5,
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

These are the available options:

http_client

The service ID of the HTTP client used to call the introspection endpoint. It defaults to the http_client service, which doesn't define the endpoint URL or the credentials, so in practice you always need to define a scoped client as shown above.

issuer

The identifier of the authorization server, compared with the iss member of the introspection response. It defaults to null, which skips this check.

audience

The identifier (as a string) or identifiers (as an array) of your application. The aud member of the response must contain at least one of them. It defaults to an empty array, which skips this check.

claim

The claim that contains the user identifier (e.g. sub, username, email). It defaults to null, which uses the sub claim and falls back to the username claim.

allowed_time_drift

The tolerance, in seconds, applied when checking the iat, nbf and exp members of the response, to account for clock differences between the servers. It defaults to 0.

cache

The configuration used to cache the introspection responses, as explained in the section about caching.

The handler rejects the token when the response reports it as inactive, when its exp, nbf or iat dates are not valid timestamps or place the token outside of its validity period, and when its iss or aud members don't match the configured issuer and audience. RFC 7662 makes all these members optional, so the handler only checks the dates included in the response. However, when you configure the issuer or audience options, the response must include the corresponding member. The token is also rejected when the authorization server can't be reached or returns an error or something other than a JSON object.

If you only need to configure the HTTP client, pass its service ID directly as the value of the oauth2 option:

1
2
3
4
5
6
7

# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    oauth2: 'oauth2.introspection'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'oauth2' => 'oauth2.introspection',
                    ],
                ],
            ],
        ],
    ],
]);

1

$ composer require web-token/jwt-library

1
2
3
4
5
6
7
8
9
10
11
12
13

# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    oauth2:
                        http_client: 'oauth2.introspection'
                        issuer: 'https://auth.example.com/'
                        audience: 'https://api.example.com'
                        response_signature:
                            enabled: true
                            keyset: '%env(AUTH_SERVER_JWKS)%'

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'oauth2' => [
                            'http_client' => 'oauth2.introspection',
                            'issuer' => 'https://auth.example.com/',
                            'audience' => 'https://api.example.com',
                            'response_signature' => [
                                'enabled' => true,
                                'keyset' => '%env(AUTH_SERVER_JWKS)%',
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

1
2
3
4
5
6
7
8
9
10
11
12
13

# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    oauth2:
                        http_client: 'oauth2.introspection'
                        issuer: 'https://auth.example.com/'
                        audience: 'https://api.example.com'
                        response_signature:
                            enabled: true
                            discovery: true

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'oauth2' => [
                            'http_client' => 'oauth2.introspection',
                            'issuer' => 'https://auth.example.com/',
                            'audience' => 'https://api.example.com',
                            'response_signature' => [
                                'enabled' => true,
                                'discovery' => true,
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

1

$ composer require symfony/cache

1
2
3
4
5
6
7
8
9
10
11
12
13

# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    oauth2:
                        http_client: 'oauth2.introspection'
                        cache:
                            # the cache pool service ID (required)
                            id: cache.app
                            # max lifetime in seconds (default: 60)
                            ttl: 60

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'oauth2' => [
                            'http_client' => 'oauth2.introspection',
                            'cache' => [
                                // the cache pool service ID (required)
                                'id' => 'cache.app',
                                // max lifetime in seconds (default: 60)
                                'ttl' => 60,
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

Binding Access Tokens to a Key (DPoP)

A bearer access token works for anyone who presents it, so a stolen token can be used until it expires. DPoP (Demonstrating Proof of Possession, defined in RFC 9449) prevents this: the authorization server binds the token to a key of the client (in the cnf claim of the token) and the client signs a proof with that key for each request. Enable the dpop option to only accept tokens bound to a key whose possession the request proves. This option requires the web-token/jwt-library package:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# config/packages/security.yaml
security:
    firewalls:
        api:
            pattern: ^/api
            stateless: true
            access_token:
                dpop: true
                token_handler:
                    oidc:
                        discovery:
                            base_uri: 'https://oidc.example.com'
                        issuers: ['https://oidc.example.com']
                        audience: 'api-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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'api' => [
                'pattern' => '^/api',
                'stateless' => true,
                'access_token' => [
                    'dpop' => true,
                    'token_handler' => [
                        'oidc' => [
                            'discovery' => [
                                'base_uri' => 'https://oidc.example.com',
                            ],
                            'issuers' => ['https://oidc.example.com'],
                            'audience' => 'api-example',
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

Clients of this firewall must send the token with the DPoP scheme instead of Bearer and the signed proof in the DPoP header:

1
2
3
4

GET /api/orders HTTP/1.1
Host: api.example.com
Authorization: DPoP eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCJ9...
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2In0...

Tokens that are not bound to a key are rejected. The WWW-Authenticate header of 401 responses uses the DPoP scheme and lists the accepted algorithms. If you publish the protected resource metadata, the document also sets dpop_bound_access_tokens_required to true.

The dpop option accepts these keys:

algorithms (default: ['ES256', 'PS256', 'RS256'])

The algorithms that clients can use to sign the proofs. To accept another algorithm, tag its service with security.access_token_handler.oidc.signature_algorithm.

cache (default: cache.security)

The service ID of the cache pool that stores the used proofs to reject replayed ones. If the proof can't be stored in the pool, the request is rejected. When your application runs on several servers, this pool must be shared by all of them (e.g. a Redis pool); otherwise, a proof can be replayed against another server.

proof_lifetime (default: 60)

The number of seconds a proof is accepted after the time defined in its iat claim (plus the allowed time drift).

allowed_time_drift (default: 5)

The number of seconds of difference allowed, in both directions, between the iat claim of a proof and the time of the server.

DPoP has these requirements and limitations:

• The htu claim of the proof is compared with the URL of the request. If your application runs behind a reverse proxy, configure the trusted proxies and hosts so Symfony generates the same URL that the client used.
• The firewall must be stateless. Otherwise, the session would authenticate the next requests without any proof.
• The token handler must give access to the claims of the token. The oidc_user_info and cas handlers don't do that, so they can't be used with DPoP. A custom token handler must pass all the claims of the token (including cnf) as the attributes of the returned UserBadge.
• Server-provided nonces (Section 8 of the RFC) are not supported.

Using CAS 2.0

Central Authentication Service (CAS) is an enterprise multilingual single sign-on solution and identity provider for the web and attempts to be a comprehensive platform for your authentication and authorization needs.

1

$ composer require symfony/http-client

1
2
3
4
5
6
7
8

# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    cas:
                        validation_url: https://www.example.com/cas/validate

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'cas' => [
                            'validation_url' => 'https://www.example.com/cas/validate',
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

1
2
3
4
5
6
7
8
9

# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    cas:
                        validation_url: https://www.example.com/cas/validate
                        http_client: cas.client

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
    'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'cas' => [
                            'validation_url' => 'https://www.example.com/cas/validate',
                            'http_client' => 'cas.client',
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

1
2
3
4
5
6
7
8
9

# config/packages/security.yaml
security:
    firewalls:
        main:
            access_token:
                token_handler:
                    cas:
                        validation_url: https://www.example.com/cas/validate
                        prefix: cas-example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'access_token' => [
                    'token_handler' => [
                        'cas' => [
                            'validation_url' => 'https://www.example.com/cas/validate',
                            'prefix' => 'cas-example',
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

Requiring OAuth 2.0 Scopes

An authorization server grants each access token a limited set of permissions, which RFC 6749 calls scopes. Requiring scopes lets you reject a valid token when it doesn't allow the requested action, even if the user behind it could perform that action.

Use the OAUTH2_SCOPE() attribute to require scopes. It lists the required scopes between parentheses, separated by spaces:

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

// src/Controller/ProfileController.php
namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Security\Http\Attribute\IsGranted;

class ProfileController
{
    #[IsGranted('OAUTH2_SCOPE(profile:read)')]
    public function show(): Response
    {
        // ...
    }

    // the token must have been granted all the scopes listed in the attribute
    #[IsGranted('OAUTH2_SCOPE(profile:read profile:write)')]
    public function edit(): Response
    {
        // ...
    }
}

The same attribute works in access control rules. When a rule lists several attributes in its roles option, any of them grants access:

1
2
3
4
5
6
7

# config/packages/security.yaml
security:
    # ...
    access_control:
        # the token must have been granted either of these scopes
        - path: ^/api/profile
          roles: ['OAUTH2_SCOPE(profile:read)', 'OAUTH2_SCOPE(admin)']

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        // ...
        'access_control' => [
            // the token must have been granted either of these scopes
            [
                'path' => '^/api/profile',
                'roles' => [
                    'OAUTH2_SCOPE(profile:read)',
                    'OAUTH2_SCOPE(admin)',
                ],
            ],
        ],
    ],
]);

The access_token authenticator reads the granted scopes from the scope claim of the token or, when it's missing, from the scp claim that some providers use. Both claims can be a space-separated string or a list. The authenticator stores the scopes in the oauth2_scope attribute of the security token, so you can read them in your own code with $token->getAttribute(AccessTokenAuthenticator::SCOPE_ATTRIBUTE).

The claims come from the third argument of the UserBadge returned by the token handler. The oidc, oidc_user_info and oauth2 token handlers pass them, so they support scopes out of the box. Your custom token handlers must pass the claims too. The cas token handler never provides scopes.

1
2

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer realm="My API",error="insufficient_scope",error_description="The request requires higher privileges than provided by the access token.",scope="profile:read"

Creating Users from Token

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.