Oauth2 Server Defuse Generator Bundle Laravel Package

Getting Started

This bundle is a thin Symfony 2 integration that plugs a Defuse-based symmetric key generator into the Spomky-Labs OAuth2 Server Bundle. In practice, its only job is to produce/register the secret material the OAuth2 server uses to encrypt things like authorization codes or refresh tokens (AES-256 through defuse/php-encryption). Treat it as glue, not a framework.

Minimal steps:

1. Pin a compatible stack. This targets Symfony 2 (EOL) and the old spomky-labs/oauth2-server/oauth2-server-bundle line. Do not composer require blindly on a modern app — check composer.json constraints and resolve defuse/php-encryption to a version the bundle's autoloading expects.
2. Register the bundle in AppKernel::$bundles, after SpomkyLabs\OAuth2ServerBundle. Bundle order matters because this extension decorates/contributes services defined by the core OAuth2 bundle.
3. Open DependencyInjection/ in vendor/spomky-labs/oauth2-server-defuse-generator-bundle/ first. This is the source of truth: confirm the exact service id, tag name, and config keys. Do not rely on README examples — they are frequently stale in this package family.
4. First use case: a one-shot console command that calls the generator service and prints a base64 key, so you can drop it into .env / parameters.yml and hand it to the OAuth2 configuration as the encryption/secret key.

// src/AppBundle/Command/GenerateOAuthKeyCommand.php
$key = $this->getContainer()
    ->get('oauth2_server.defuse.generator') // verify id in vendor/DependencyInjection
    ->generate();
$this->output->writeln(base64_encode($key));

If the generator service is private (common in newer container setups), expose it via services.yml alias or inject it into the command directly.

Implementation Patterns

Deploy-time key generation (most common). Never generate the key at request time. Run the command as a release step, store the base64 output in your secrets manager, and inject it as a parameter. The bundle's generator is a randomness source, not a stateful key store.

Rotation with a decrypt set. Defuse encryption is symmetric and unrecoverable without the key. Pattern:

• Keep current (used to encrypt) and previous[] (used to decrypt) keys in config.
• New tokens use current; decryption tries current then each previous.
• Retire a previous key only after the longest-lived token/code TTL has elapsed.

The bundle only generates keys — the multi-key decrypt logic lives in your OAuth2 server wiring, not here.

Tag-based wiring. The core OAuth2 bundle exposes an extension point (a tagged service, typically something like oauth2_server.key_generator). If the bundle registers its generator via that tag, you don't call it directly — you set the config option that makes the OAuth2 server resolve it. Confirm the tag name in Resources/config/services.xml.

Console command + CI enforcement. Wrap generation in a command and have CI assert a key exists and is the right length (32 raw bytes / 44 base64 chars) before deploying, rather than letting a missing key surface as a runtime decryption failure.

Dev/test determinism. In config_test.yml, point the OAuth2 encryption key at a fixed fixture key so encrypted tokens are reproducible; do not run the random generator in tests. Keep the generator enabled in dev only if you actually need it.

Service override for custom generators. If you need a different algorithm (e.g., migrate to libsodium), implement the same interface the bundle's generator implements and register your own service under the same id. This lets you swap the crypto without touching OAuth2 config.

# services.yml
services:
    oauth2_server.defuse.generator:
        class: AppBundle\Security\SodiumKeyGenerator
        # same public method(s) as the bundle generator

Gotchas and Tips

• Symfony 2 only. Bundle class extends Symfony\Component\HttpKernel\Bundle\Bundle and expects AppKernel. On Symfony 3+/4+ (Flex), autoloading and the Bundle registration path differ; expect manual porting and bundle config migration. Budget for this.
• defuse/php-encryption is archived/legacy. It predates libsodium being standard. For new work, generate keys with sodium_crypto_secretbox and avoid adding a new Defuse dependency. This bundle is essentially a migration shim for existing Defuse-encrypted data.
• Raw bytes vs base64. The generator likely returns binary key material. Storing it in .env without base64_encode will corrupt it (newlines, nulls, YAML escaping). Always encode at the boundary and decode on load.
• Key length matters. Defuse expects exactly 32 bytes for AES-256-CTR+HMAC. If you truncate a base64 string or reuse a password, encryption silently "works" but decryption may fail on HMAC verification — debug via the underlying Defuse exception, not the OAuth2 layer.
• Losing the key = losing all live tokens and codes. There is no recovery. Back up the key alongside the deployment artifacts, and never let the generator overwrite an existing key — make your command refuse if a key is already present unless --force.
• Bundle registration order. Register OAuth2ServerBundle before this bundle; otherwise the extension may not find the parent config keys and throws at container compile time.
• Service visibility / debug:container. Use php bin/console debug:container oauth2_server.defuse (Symfony 2: container:debug) to confirm the real id — aliases and private services are common sources of ServiceNotFoundException.
• No dependents, no maintenance. With zero dependents and no stars, treat the README as documentation-of-intent only. Pin the commit/tag, vendor the package if needed, and read the DependencyInjection/Configuration.php to know the accepted config shape.
• Don't conflate this with asymmetric key generation. This bundle handles the symmetric encryption secret. If your OAuth2 setup uses JWK/RSA/EC signing keys, that's a separate generator/config path in the core bundle — don't point the Defuse generator at it.
• Debugging decryption failures: reproduce directly with the Defuse Crypto::decrypt($ciphertext, Key::loadFromAsciiSafeString(...)) in a tinker session. If it fails there, the problem is key material or base64 handling, not the OAuth2 bundle.