Oauth2 Server Bearer Access Token Bundle Laravel Package

Getting Started

This bundle is a thin Symfony 2 extension for spomky-labs/oauth2-server. It does not implement OAuth itself — it wires a "Bearer Access Token" token-type/response manager into the core SpomkyLabs\OAuth2ServerBundle service graph. Treat the core bundle's README as the primary documentation and this bundle as a service-registration add-on.

1. Install (pin versions; this is legacy)

composer require spomky-labs/oauth2-server-bearer-access-token-bundle

You will also need the core server bundle and a storage backend (the base library ships in-memory managers, which are only useful for tests):

composer require spomky-labs/oauth2-server-bundle

2. Register bundles in app/AppKernel.php — order matters. The bearer-token bundle must load after the core server bundle so its compiler pass can extend the server configuration:

$bundles = [
    // ...
    new SpomkyLabs\OAuth2ServerBundle\SpomkyLabsOAuth2ServerBundle(),
    new SpomkyLabs\OAuth2ServerBearerAccessTokenBundle\SpomkyLabsOAuth2ServerBearerAccessTokenBundle(),
];

3. First place to look: the bundle's DependencyInjection/ directory and Resources/config/*.xml. That is where the service IDs and any compiler-pass tags live. Cross-reference those IDs against the core bundle's oauth2_server.* service definitions to see what the manager is being attached to.

4. Minimal configuration in app/config/config.yml — the core bundle does the heavy lifting; this bundle mostly needs to be present and to have its manager selected as the token type for the grants you enable:

spomky_labs_o_auth2_server:
    grants:
        password: ~          # enables the grant whose response is a bearer token
    token_type_manager: oauth2_server.bearer_access_token.token_type_manager

First use case: a mobile/SPA backend that issues short-lived bearer tokens from the password or client_credentials grant, returning access_token in the JSON body of POST /token. This bundle is what makes the Bearer token type resolvable so the token endpoint can serialize a response.

Verify wiring before writing any application code:

php app/console debug:container | grep -i bearer
php app/console debug:container oauth2_server.bearer_access_token.token_type_manager

If the service exists, the bundle is loaded correctly and the remaining work is grant/storage configuration in the core bundle.

Implementation Patterns

The token endpoint is yours to write. This bundle supplies services, not routes or controllers. The standard pattern is a small controller that hands the PSR-7/Symfony request to the core server's token-endpoint handler:

public function tokenAction(Request $request)
{
    $server = $this->get('oauth2_server.server');
    $response = $server->handleTokenRequest(
        $this->get('oauth2_server.request_factory')->createFromSymfonyRequest($request)
    );

    return $this->get('oauth2_server.response_factory')->createSymfonyResponse($response);
}

Route it with methods: [POST] and no CSRF; OAuth clients authenticate with client_id/client_secret, not sessions.

Pair grant + token manager explicitly. The most reliable configuration pattern is to define each grant as a service and bind it to the bearer token type manager, rather than relying on defaults. In this generation of the bundle that means:

services:
    app.oauth2.grant.password:
        class: OAuth2\GrantType\PasswordCredentials
        arguments: ['@oauth2_server.client_manager', '@oauth2_server.access_token_manager.user']
        tags:
            - { name: oauth2_server.grant_type, alias: password }

The bearer token manager then serializes every successful grant response into token_type: Bearer, access_token, expires_in, and optionally refresh_token. Note the two distinct access-token managers: user-bound (password/authorization_code) and client-bound (client_credentials).

Combine with the refresh-token grant for any long-lived user session. The bearer token manager handles the response shape; the refresh grant handles rotation. Register both tags and let the server dispatch.

Separate the resource-server check. Do not reuse this bundle for validation on protected APIs. Use a token-introspection/resource-server bundle so your API firewall verifies the token without coupling to the issuing side. A typical split:

Testing workflow. Point the Symfony functional test client at /token and assert on the JSON body, including the exact token_type string, since that is the only thing this bundle is responsible for:

$client->request('POST', '/token', [
    'grant_type'    => 'password',
    'username'      => 'alice',
    'password'      => 'secret',
    'client_id'     => 'demo',
    'client_secret' => 'demo-secret',
]);
$this->assertSame('Bearer', json_decode($client->getResponse()->getContent(), true)['token_type']);

Configuration override via DI. If you need a custom response (custom expires_in, additional claims), subclass the bearer token manager and override the service ID in services.yml. Re-declaring the service under the bundle's ID is the documented-by-example way to customize behavior, because there is no dedicated extension point for the token payload.

Gotchas and Tips

Check the date before you commit. This package has zero dependents and no score, and sits on top of a library that was substantially restructured across major versions. Pin every spomky-labs/* dependency to an exact version in composer.json and commit composer.lock. Do not run composer update casually on this stack.

Symfony 2 only. There is no Flex recipe, no autoconfiguration, no autowiring. Service references are string IDs, and missing tags fail silently — a grant that is never tagged simply won't appear in the server's grant list and the token endpoint will return unsupported_grant_type with no error log.

In-memory storage will silently lose tokens. The default managers from the core library keep tokens in memory per request. Any real integration needs a persistent access-token manager (Doctrine or custom). If authenticated requests work once and then 401 on the next request, this is almost always the cause, not the bearer bundle.

The bearer token is only as safe as the transport. This bundle returns the token in the response body, so enforce HTTPS on the token endpoint, send Cache-Control: no-store and Pragma: no-cache, and never allow the token response to be cached by a proxy. Also handle OPTIONS explicitly if your SPA calls /token cross-origin — a 405 on preflight looks like an authentication bug.

client_credentials vs password get different token managers. Binding a user-bound manager to a client-credentials grant (or the reverse) produces tokens that validate but carry the wrong subject. If sub/user data is missing from your JWT or introspection response, check which manager the grant was wired to first.

Debugging checklist, in order: debug:container for the manager service → check the grant tag exists → check the core server's grants config is non-empty → tail the server bundle's logger channel for the underlying exception. The bundle swallows the specific OAuth error and returns a generic invalid_request when a service reference is broken, so container errors, not HTTP responses, are the place to look.

Extension points are limited to service replacement. There is no event dispatcher hook in this bundle. Customization means: subclass the manager, redeclare the service ID, or implement the core library's token-type-manager interface and tag it. Anything else (custom claims, token format changes) belongs in your grant or access-token manager implementation, not the bundle.