Rework and clean up the bundle config

* Document all options and add examples
* Make the config key names less ambiguous
* Make the local validation leeway configurable (default to 120 seconds still)

CHANGELOG.md

 # ????-??-??
+
+* Rework bundle config
+  * Make the config option naming less ambiguous
+  * Add an option to specify the local validation time leeway
\ No newline at end of file

README.md

 # DBP API-Keycloak-Bundle
 
 [GitLab](https://packagist.org/packages/dbp/api-keycloak-bundle) | [Packagist](https://packagist.org/packages/dbp/api-keycloak-bundle)
+
+## Bundle Configuration
+
+```yaml
+# Default configuration for "DbpRelayKeycloakBundle"
+dbp_relay_keycloak:
+
+    # The Keycloak server URL
+    server_url:           ~ # Example: 'https://keycloak.example.com/auth'
+
+    # The Keycloak Realm
+    realm:                ~ # Example: myrealm
+
+    # The ID for the keycloak client (authorization code flow) used for API docs or similar
+    frontend_client_id:   ~ # Example: client-docs
+
+    # If remote validation should be used. If set to false the token signature will
+    # be only checked locally and not send to the keycloak server
+    remote_validation:    false
+
+    # The ID of the client (client credentials flow) used for remote token validation
+    # (optional)
+    remote_validation_client_id: ~ # Example: client-token-check
+
+    # The client secret for the client referenced by client_id (optional)
+    remote_validation_client_secret: ~ # Example: mysecret
+
+    # If set only tokens which contain this audience are accepted (optional)
+    required_audience:    ~ # Example: my-api
+
+    # How much the system time of the API server and the Keycloak server
+    # can be out of sync (in seconds). Used for local token validation.
+    local_validation_leeway: 120
+```
\ No newline at end of file

src/DependencyInjection/Configuration.php

@@ -14,13 +14,43 @@ class Configuration implements ConfigurationInterface
         $treeBuilder = new TreeBuilder('dbp_relay_keycloak');
         $treeBuilder->getRootNode()
             ->children()
-                ->scalarNode('server_url')->end()
-                ->scalarNode('realm')->end()
-                ->scalarNode('client_id')->end()
-                ->scalarNode('client_secret')->end()
-                ->scalarNode('audience')->end()
-                ->booleanNode('local_validation')->defaultTrue()->end()
-                ->scalarNode('frontend_client_id')->end()
+                ->scalarNode('server_url')
+                    ->info('The Keycloak server URL')
+                    ->example('https://keycloak.example.com/auth')
+                ->end()
+                ->scalarNode('realm')
+                    ->info('The Keycloak Realm')
+                    ->example('myrealm')
+                ->end()
+                // API docs
+                ->scalarNode('frontend_client_id')
+                    ->info('The ID for the keycloak client (authorization code flow) used for API docs or similar')
+                    ->example('client-docs')
+                ->end()
+                // Remote validation
+                ->booleanNode('remote_validation')
+                    ->info("If remote validation should be used. If set to false the token signature will\nbe only checked locally and not send to the keycloak server")
+                    ->example(false)
+                    ->defaultFalse()
+                ->end()
+                ->scalarNode('remote_validation_client_id')
+                    ->info("The ID of the client (client credentials flow) used for remote token validation\n(optional)")
+                    ->example('client-token-check')
+                ->end()
+                ->scalarNode('remote_validation_client_secret')
+                    ->info('The client secret for the client referenced by client_id (optional)')
+                    ->example('mysecret')
+                ->end()
+                // Settings for token validation
+                ->scalarNode('required_audience')
+                    ->info('If set only tokens which contain this audience are accepted (optional)')
+                    ->example('my-api')
+                ->end()
+                ->integerNode('local_validation_leeway')
+                    ->defaultValue(120)
+                    ->min(0)
+                    ->info("How much the system time of the API server and the Keycloak server\ncan be out of sync (in seconds). Used for local token validation.")
+                ->end()
             ->end();
 
         return $treeBuilder;

src/Keycloak/KeycloakBearerUserProvider.php

@@ -40,10 +40,11 @@ class KeycloakBearerUserProvider implements KeycloakBearerUserProviderInterface,
         $config = $this->config;
         $keycloak = new Keycloak(
             $config['server_url'], $config['realm'],
-            $config['client_id'], $config['client_secret']);
+            $config['remote_validation_client_id'], $config['remote_validation_client_secret']);
 
-        if ($config['local_validation']) {
-            $validator = new KeycloakLocalTokenValidator($keycloak, $this->certCachePool);
+        if (!$config['remote_validation']) {
+            $leeway = $config['local_validation_leeway'];
+            $validator = new KeycloakLocalTokenValidator($keycloak, $this->certCachePool, $leeway);
         } else {
             $validator = new KeycloakRemoteTokenValidator($keycloak);
         }
@@ -51,8 +52,8 @@ class KeycloakBearerUserProvider implements KeycloakBearerUserProviderInterface,
 
         $jwt = $validator->validate($accessToken);
 
-        if (($config['audience'] ?? '') !== '') {
-            $validator::checkAudience($jwt, $config['audience']);
+        if (($config['required_audience'] ?? '') !== '') {
+            $validator::checkAudience($jwt, $config['required_audience']);
         }
 
         return $this->loadUserByValidatedToken($jwt);

src/Keycloak/KeycloakLocalTokenValidator.php

@@ -20,17 +20,16 @@ class KeycloakLocalTokenValidator extends KeycloakTokenValidatorBase
     private $keycloak;
     private $cachePool;
     private $clientHandler;
+    private $leewaySeconds;
 
     /* The duration the public keycloak cert is cached */
     private const CERT_CACHE_TTL_SECONDS = 3600;
 
-    /* The leeway given for time based checks for token validation, in case the clocks of the server are out of sync */
-    private const LOCAL_LEEWAY_SECONDS = 120;
-
-    public function __construct(Keycloak $keycloak, ?CacheItemPoolInterface $cachePool)
+    public function __construct(Keycloak $keycloak, ?CacheItemPoolInterface $cachePool, int $leewaySeconds)
     {
         $this->keycloak = $keycloak;
         $this->cachePool = $cachePool;
+        $this->leewaySeconds = $leewaySeconds;
         $this->clientHandler = null;
     }
 
@@ -116,9 +115,9 @@ class KeycloakLocalTokenValidator extends KeycloakTokenValidatorBase
             $validate = $validate
                 ->algs(['RS256', 'RS512'])
                 ->keyset($keySet)
-                ->exp(self::LOCAL_LEEWAY_SECONDS)
-                ->iat(self::LOCAL_LEEWAY_SECONDS)
-                ->nbf(self::LOCAL_LEEWAY_SECONDS)
+                ->exp($this->leewaySeconds)
+                ->iat($this->leewaySeconds)
+                ->nbf($this->leewaySeconds)
                 ->iss($issuer);
             assert($validate instanceof Validate);
             $jwtResult = $validate->run();

tests/Keycloak/KeycloakLocalTokenValidatorTest.php

@@ -30,7 +30,7 @@ class KeycloakLocalTokenValidatorTest extends TestCase
         $this->keycloak = $keycloak;
         $cache = new ArrayAdapter();
 
-        $this->tokenValidator = new KeycloakLocalTokenValidator($keycloak, $cache);
+        $this->tokenValidator = new KeycloakLocalTokenValidator($keycloak, $cache, 0);
         $this->mockResponses([]);
     }