Oauth2 Server Token Endpoint Bundle Laravel Package

Getting Started

This bundle is a thin Symfony 2 integration layer that exposes the token endpoint (the /token route) from spomky-labs/oauth2-server. It does not stand alone — it is one of several sibling bundles (authorization endpoint, resource server, JWT, console) that share the same core. Treat its star count and dependent count as a warning: it is effectively legacy/abandoned for the modern stack.

Minimal setup:

1. Require the matching major of spomky-labs/oauth2-server (the bundle pins it), plus a storage layer (Doctrine ORM/ODM bridge or your own ClientInterface/AccessTokenInterface repositories).
2. Register OAuth2ServerBundle and OAuth2ServerTokenEndpointBundle in AppKernel, and import the routing:

# app/config/routing.yml
oauth2_token:
    resource: "@OAuth2ServerTokenEndpointBundle/Resources/config/routing.xml"
    prefix:   /oauth2

3. Configure the server: clients, scopes, grant types, and token TTLs under oauth2_server:.
4. Exclude the token route from the interactive firewall (it authenticates clients itself, not users):

security:
    firewalls:
        oauth_token:
            pattern: ^/oauth2/token
            security: false

First use case: implement the password or client_credentials grant end‑to‑end against a single seeded client, then verify with:

curl -X POST https://app.local/oauth2/token \
  -d grant_type=password \
  -d client_id=my-client \
  -d client_secret=secret \
  -d username=alice -d password=... \
  -d scope=read

Where to look first: the bundle's DependencyInjection/Configuration.php (the authoritative list of options and defaults), then the controller it registers. The bundle's job is almost entirely configuration + routing; the real logic lives in spomky-labs/oauth2-server.

Implementation Patterns

Grant type wiring. Each grant is a service tagged/registered by the core library. The bundle lets you enable a subset per client:

oauth2_server:
    grants:
        client_credentials: ~
        password: ~
        refresh_token: ~
        authorization_code: ~

Only enable grants you need; every disabled grant is one less attack surface on the token endpoint.

Confidential vs public clients. Model them as distinct client classes (the core ships both). Public clients (SPA/mobile) must use PKCE with authorization_code; confidential clients can use client_secret_basic or client_secret_post. Enforce per-client token_endpoint_auth_method rather than accepting both methods globally.

Storage adapters. The bundle integrates with Doctrine, but you can swap in Redis or custom repositories by redefining the ClientRepositoryInterface / AccessTokenRepositoryInterface service aliases. Choose one and keep token + refresh + auth-code storage consistent — mixing stores is the most common source of "token issued but rejected" bugs.

Response customization. Listen to the token endpoint events (pre/post token request) to inject custom claims, audit logging, or rate limiting. This is the intended extension point rather than decorating the controller.

Testing pattern. Use Symfony\Bundle\FrameworkBundle\Test\WebTestCase and POST directly to the token URI; assert on access_token, token_type, expires_in, and error codes (invalid_client, invalid_grant, unsupported_grant_type). Add negative tests for expired authorization codes, reused refresh tokens, and wrong client secrets.

Integration tips. Put a reverse proxy in front for TLS termination and enforce https on the token route. Route all token traffic through the same host as the auth endpoint to avoid client misconfiguration. For SPA/mobile backends, pair this with CORS headers scoped to the token route only.

Gotchas and Tips

• It's Symfony 2-era and unmaintained. Do not adopt this for new projects. For new work, use league/oauth2-server with the oauth2-server-bundle, or the newer oauth2-server package. If you inherit it, plan a migration — the service IDs and event names differ between majors.
• Version coupling is brittle. The bundle pins a specific spomky-labs/oauth2-server major. Bumping one without the other breaks token serialization or client authentication silently.
• Silent client authentication failures usually trace to secret hashing: the stored secret must be the hashed value, and the client must send the plaintext via the configured method. Mixing client_secret_basic and client_secret_post on the same client confuses the library.
• Firewall misconfiguration — leaving the token route inside the session firewall produces invalid_client or a redirect to login. Verify with debug:router that the route is anonymous.
• TTL and clock skew — expires_in is computed from the server clock. If the token issuer and the resource server are separate hosts, allow small skew or you get sporadic invalid_token errors.
• Refresh token rotation — enable rotation and detect reuse; the library supports it but it must be explicitly configured, otherwise old refresh tokens remain valid indefinitely.
• Debugging — enable the core library's logger and dump the raw token request/response. Since the bundle delegates almost everything, framework logs rarely show the reason a grant failed; the core exception messages do.
• Extension points to prefer — event listeners, custom TokenResponseType, and custom grants (implement the grant interface and register as a service) rather than overriding the controller.
• Error responses are part of the contract — they must be JSON with error and error_description. Don't let Symfony's exception handler return HTML on the token endpoint; scope a dedicated error_controller for that path.
• CORS preflight — browsers will OPTIONS the token endpoint; if the bundle's routing only registers POST, add an explicit OPTIONS handler or the preflight fails before any auth happens.