Oauth2 Server Scope Manager Bundle Laravel Package

Getting Started

This bundle is a companion to Spomky-Labs/OAuth2ServerBundle — it does nothing on its own. It provides a configurable scope manager service that the main OAuth2 server bundle consumes to validate and assign scopes on token/authorize requests. If you don't already have the main OAuth2 server bundle installed and working, install that first; this bundle is only useful as the scope layer on top of it.

Minimal steps:

1. composer require spomky-labs/oauth2-server-scope-manager-bundle
2. Register the bundle in AppKernel.php after the main OAuth2 server bundle so its service definitions/compiler pass win.
3. Define your scopes and default policy under the bundle's root config key in config.yml (fixed list + a policy such as default/error/none).
4. Clear the cache and confirm the scope manager service is the one the server is using (bin/console debug:container / debug:container --show-private).

Where to look first:

• DependencyInjection/Configuration.php — the authoritative list of config keys; the bundle README is often stale.
• Resources/config/*.yml — the service IDs it registers and, crucially, which service it decorates or aliases as the server's scope manager.
• The main OAuth2 server bundle's scope documentation — this bundle just supplies the manager that documentation assumes exists.

First real use case: a small app with a fixed scope set (read, write, admin), where a token request's scope parameter must be validated against that list and, if omitted, filled from a default set. That is exactly the shape this bundle is built for.

Implementation Patterns

• In-memory, config-driven scopes. The intended pattern is a static scope list in YAML. This fits CLI/API-server style apps with a small fixed vocabulary of scopes, not per-user or per-resource dynamic scopes.
• Scope policy selection. Use the policy to decide what happens when a client requests no scope: fail the request, grant a default scope set, or grant none. Pick deliberately — the "default" policy is convenient but can silently over-grant.
• Let the bundle wire itself. The usual usage is zero code: configure the list, and the bundle's service becomes the server's ScopeManagerInterface implementation. Only override the service alias if you have another bundle also claiming that role.
• Custom logic by replacement, not extension. If scopes must be dynamic (stored per client, per tenant, per resource), implement ScopeManagerInterface yourself, register it, and alias the server's scope-manager service ID to your implementation. Treat this bundle as a reference implementation you graduate away from.
• Per-grant behavior. The scope manager is consulted across authorization-code, client-credentials, password, and refresh-token grants. When debugging a scope rejection, identify which grant path issued the request first — the same scope can behave differently depending on the grant.
• Testing. Unit-test scope validation by instantiating the manager directly with a config array. Functional-test the token endpoint with (a) valid scope, (b) unknown scope, (c) missing scope under each policy — that trio catches nearly all misconfigurations.

Gotchas and Tips

• This is legacy. It targets Symfony 2 and is part of an OAuth2 server stack that has been superseded (the Spomky-Labs server bundles gave way to oauth2-server-bundle / league/oauth2-server). Symfony 2 is EOL and this bundle is effectively unmaintained — do not start a new project on it. If you inherit it, plan a migration rather than extending it.
• Bundle registration order matters. Registering before the main OAuth2 bundle can leave the wrong scope manager injected. If scopes are mysteriously ignored, check debug:container for the actual class behind the scope-manager service ID.
• Config key confusion. Scopes live under this bundle's root key, not nested under the main oauth2_server key. Use config:dump-reference <bundle-alias> to get the real key names instead of trusting examples.
• Cache is mandatory. Scope lists are compiled into container parameters; editing YAML without clearing the cache produces stale, confusing behavior.
• Case-sensitivity and separators. Scope strings are case-sensitive and space-separated in requests. Validation failures often surface only as a generic invalid_scope — enable the underlying library's logger to see the actual comparison.
• No persistence out of the box. There is no DB-backed scope table. If you need dynamic scopes you are writing your own manager — budget for it.
• Watch for permissive fallbacks. If the scope manager isn't picked up, the server may fall back to a permissive default and accept unknown scopes. Always assert in a test that an unknown scope is actually rejected, not just that a known one succeeds.
• Extension point. The clean extension seam is the ScopeManagerInterface service alias, not subclassing bundle internals — the internal services and class names are not stable across the (few) releases.