[SDK-2141] Expand control of ttl/caching in JWKFetcher (#462)

Author: Evan Sims

src/Helpers/JWKFetcher.php

@@ -5,6 +5,7 @@
 
 use Auth0\SDK\API\Helpers\RequestBuilder;
 use Auth0\SDK\Helpers\Cache\NoCacheHandler;
+use Auth0\SDK\Exception\CoreException;
 use GuzzleHttp\Exception\ClientException;
 use GuzzleHttp\Exception\RequestException;
 use Psr\SimpleCache\CacheInterface;
@@ -17,19 +18,35 @@
 class JWKFetcher
 {
     /**
-     * How long should the cache persist? Set to 10 minutes.
+     * Default length of cache persistence. Defaults to 10 minutes.
      *
      * @see https://www.php-fig.org/psr/psr-16/#12-definitions
      */
     const CACHE_TTL = 600;
 
+    /**
+     * How long should the cache persist? Defaults to value of CACHE_TTL.
+     * We strongly encouraged you leave the default value.
+     *
+     * @see https://www.php-fig.org/psr/psr-16/#12-definitions
+     */
+    private $ttl = self::CACHE_TTL;
+
     /**
      * Cache handler or null for no caching.
      *
      * @var CacheInterface|null
      */
     private $cache;
 
+    /**
+     * Cache for unique cache ids.
+     * Key for each entry is the url to the JWK. Value is cache id.
+     *
+     * @var array
+     */
+    private $cachedEntryIds = [];
+
     /**
      * Options for the Guzzle HTTP client.
      *
@@ -42,15 +59,20 @@ class JWKFetcher
      *
      * @param CacheInterface|null $cache         Cache handler or null for no caching.
      * @param array               $guzzleOptions Guzzle HTTP options.
+     * @param options             $options       Class options to apply at initializion.
      */
-    public function __construct(CacheInterface $cache = null, array $guzzleOptions = [])
+    public function __construct(CacheInterface $cache = null, array $guzzleOptions = [], array $options = [])
     {
         if ($cache === null) {
             $cache = new NoCacheHandler();
         }
 
         $this->cache         = $cache;
         $this->guzzleOptions = $guzzleOptions;
+
+        if (!empty($options['ttl'])) {
+            $this->setTtl($options['ttl']);
+        }
     }
 
     /**
@@ -98,12 +120,13 @@ public function getKey(string $kid, string $jwksUri = null)
     public function getKeys(string $jwks_url = null, bool $use_cache = true) : array
     {
         $jwks_url = $jwks_url ?? $this->guzzleOptions['base_uri'] ?? '';
+
         if (empty( $jwks_url )) {
             return [];
         }
 
-        $cache_key    = md5($jwks_url);
-        $cached_value = $use_cache ? $this->cache->get($cache_key) : null;
+        $cached_value = $use_cache ? $this->getCacheEntry($jwks_url) : null;
+
         if (! empty($cached_value) && is_array($cached_value)) {
             return $cached_value;
         }
@@ -123,7 +146,7 @@ public function getKeys(string $jwks_url = null, bool $use_cache = true) : array
             $keys[$key['kid']] = $this->convertCertToPem( $key['x5c'][0] );
         }
 
-        $this->cache->set($cache_key, $keys, self::CACHE_TTL);
+        $this->setCacheEntry($jwks_url, $keys);
         return $keys;
     }
 
@@ -148,4 +171,111 @@ protected function requestJwks(string $jwks_url) : array
 
         return $request->call();
     }
+
+    /**
+     * Set how long to cache JWKs in seconds.
+     * We strongly encouraged you leave the default value.
+     *
+     * @param string  $ttlSeconds  Number of seconds to keep a JWK in memory.
+     *
+     * @return $this
+     *
+     * @throws CoreException  If $ttlSeconds is less than 60.
+     */
+    public function setTtl(int $ttlSeconds)
+    {
+        if ($ttlSeconds < 60) {
+            throw new CoreException('TTL cannot be less than 60 seconds.');
+        }
+
+        $this->ttl = $ttlSeconds;
+        return $this;
+    }
+
+    /**
+     * Returns how long we are caching JWKs in seconds.
+     *
+     * @return integer
+     */
+    public function getTtl()
+    {
+        return $this->ttl;
+    }
+
+    /**
+     * Generate a cache id to use for a URL.
+     *
+     * @param string  $jwks_url  Full URL to the JWKS.
+     *
+     * @return string
+     */
+    public function getCacheKey(string $jwksUri)
+    {
+        if (isset($this->cachedEntryIds[$jwksUri])) {
+            return $this->cachedEntryIds[$jwksUri];
+        }
+
+        $cacheKey = md5($jwksUri);
+
+        $this->cachedEntryIds[$jwksUri] = $cacheKey;
+        return $cacheKey;
+    }
+
+    /**
+     * Get a specific JWK from the cache by it's URL.
+     *
+     * @param string  $jwks_url  Full URL to the JWKS.
+     *
+     * @return null|array
+     */
+    public function getCacheEntry(string $jwksUri)
+    {
+        $cache_key    = $this->getCacheKey($jwksUri);
+        $cached_value = $this->cache->get($cache_key);
+
+        if (! empty($cached_value) && is_array($cached_value)) {
+            return $cached_value;
+        }
+
+        return null;
+    }
+
+   /**
+     * Add or overwrite a specific JWK from the cache.
+     *
+     * @param string  $jwks_url  Full URL to the JWKS.
+     * @param array   $keys      An array representing the JWKS.
+     *
+     * @return $this
+     */
+    public function setCacheEntry(string $jwksUri, array $keys)
+    {
+        $cache_key = $this->getCacheKey($jwksUri);
+
+        $this->cache->set($cache_key, $keys, $this->ttl);
+
+        return $this;
+    }
+
+    /**
+     * Remove a specific JWK from the cache by it's URL.
+     *
+     * @param string  $jwks_url  Full URL to the JWKS.
+     *
+     * @return boolean
+     */
+    public function removeCacheEntry(string $jwksUri)
+    {
+        return $this->cache->delete($this->getCacheKey($jwksUri));
+    }
+
+    /**
+     * Clear the JWK cache.
+     *
+     * @return boolean
+     */
+    public function clearCache()
+    {
+        return $this->cache->clear();
+    }
 }

tests/unit/Helpers/JWKFetcherTest.php

@@ -5,6 +5,7 @@
 use Cache\Adapter\PHPArray\ArrayCachePool;
 use GuzzleHttp\Psr7\Response;
 use PHPUnit\Framework\TestCase;
+use Auth0\SDK\Exception\CoreException;
 
 /**
  * Class JWKFetcherTest.
@@ -142,4 +143,77 @@ public function testThatEmptyUrlReturnsEmptyKeys() {
         $jwks_formatted_1 = (new JWKFetcher())->getKeys();
         $this->assertEquals( [], $jwks_formatted_1 );
     }
+
+    public function testThatTtlChanges() {
+        $jwks_body = '{"keys":[{"kid":"__test_kid_2__","x5c":["__test_x5c_2__"]}]}';
+        $jwks = new MockJwks(
+            // [ new Response( 200, [ 'Content-Type' => 'application/json' ], $jwks_body ) ],
+            // [ 'cache' => new ArrayCachePool() ],
+            // [ 'base_uri' => '__test_jwks_url__' ]
+        );
+
+        // Ensure TTL is assigned a recommended default value of 10 minutes.
+        $this->assertEquals(JWKFetcher::CACHE_TTL, $jwks->call()->getTtl());
+
+        // Ensure TTL is assigned correctly; 60 seconds is the minimum.
+        $jwks->call()->setTtl(60);
+        $this->assertEquals(60, $jwks->call()->getTtl());
+
+        // Ensure assigning a TTL of less than 60 seconds throws an exception.
+        $this->expectException(CoreException::class);
+        $jwks->call()->setTtl(30);
+    }
+
+    public function testThatCacheMutates() {
+        $jwks_body = '{"keys":[{"kid":"__kid_1__","x5c":["__x5c_1__"]},{"kid":"__kid_2__","x5c":["__x5c_2__"]}]}';
+        $jwks_body_modified = ['__kid_3__' => '__x5c_3__', '__kid_4__' => '__x5c_4__'];
+
+        $jwks = new MockJwks(
+            [
+                new Response( 200, [ 'Content-Type' => 'application/json' ], $jwks_body ),
+                new Response( 200, [ 'Content-Type' => 'application/json' ], $jwks_body ),
+            ],
+            [ 'cache' => new ArrayCachePool() ],
+            [ 'base_uri' => '__test_jwks_url__' ]
+        );
+
+        $jwks->call()->getKeys('__test_jwks_url__', false);
+
+        // getCacheKey MUST return an MD5 hash of provided JWKS URL.
+        $this->assertEquals(md5('__test_jwks_url__'), $jwks->call()->getCacheKey('__test_jwks_url__'));
+
+        // Requests for invalid/missing kids MUST return NULL.
+        $this->assertEquals(null, $jwks->call()->getKey('__test_missing_kid__'));
+
+        // Requesting a valid kid MUST return an ARRAY containing the x5c
+        $this->assertContains('__x5c_1__', $jwks->call()->getKey('__kid_1__'));
+
+        // Pulling directly from cache will return same results as getKeys()
+        $this->assertArrayHasKey('__kid_1__', $jwks->call()->getCacheEntry('__test_jwks_url__'));
+
+        // Overwrite an existing JWK in the cache.
+        $jwks->call()->setCacheEntry('__test_jwks_url__', $jwks_body_modified);
+
+        // Inject a new JWK into the cache.
+        $jwks->call()->setCacheEntry('__test_jwks_url_2__', $jwks_body_modified);
+
+        // Ensure the cache was updated successfully
+        $this->assertArrayHasKey('__kid_3__', $jwks->call()->getCacheEntry('__test_jwks_url__'));
+
+        // Purge the cache of keys relating to our test url
+        $jwks->call()->removeCacheEntry('__test_jwks_url__');
+
+        // Ensure cache for our test url is empty
+        $this->assertEmpty($jwks->call()->getCacheEntry('__test_jwks_url__'));
+
+        // Ensure the cache still contains content for __test_jwks_url_2__
+        $this->assertArrayHasKey('__kid_3__', $jwks->call()->getCacheEntry('__test_jwks_url_2__'));
+
+        // Purge the cache of all keys
+        $jwks->call()->clearCache();
+
+        // Ensure all JWKs are cleared from the cache.
+        $this->assertEmpty($jwks->call()->getCacheEntry('__test_jwks_url__'));
+        $this->assertEmpty($jwks->call()->getCacheEntry('__test_jwks_url_2__'));
+    }
 }