Add Tokens::getSubjectIdFromToken (#22)

Add `Tokens::getSubjectIdFromToken` method for extracting the principal subject's client ID from a token

Persona tokens include a `sub` claim, which identifies the client to whom the token belongs.  This adds a method to get the client ID from an access token.

Bumps to v0.6.0

Author: junglebarry

composer.json

@@ -1,7 +1,7 @@
 {
   "name": "talis/talis-php",
   "description": "This is a php client library for talis APIs",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "keywords": [
     "persona",
     "echo",

src/Talis/Persona/Client/Tokens.php

@@ -287,6 +287,51 @@ public function listScopes(array $tokenInArray)
         throw new InvalidTokenException('decoded token has neither scopes nor scopeCount');
     }
 
+    /**
+     * Extract the client ID for the Subject (the `sub` claim) from a token.
+     * @param string $accessToken An access token (JWT)
+     * @return string The client ID
+     *
+     * @throws TokenValidationException If the token is not a string
+     * @throws InvalidTokenException If the token is valid, but contains no client ID
+     * @throws \Exception If the token is invalid in other ways
+     */
+    public function getSubjectIdFromToken($accessToken)
+    {
+        $clientId = $this->getClaimForToken($accessToken, 'sub');
+        if (empty($clientId)) {
+            throw new InvalidTokenException('Decoded token contains no client ID');
+        }
+        return $clientId;
+    }
+
+    /**
+     * Extract a named claim from a token.
+     * @param string $accessToken An access token (JWT)
+     * @param string $claim A claim identifier
+     * @return string|null The claim value from the token, or `null` if unavailable.
+     *
+     * @throws TokenValidationException If the token is not a string
+     * @throws \InvalidArgumentException If the claim identifier is not a string
+     * @throws \Exception If the token is invalid in other ways
+     */
+    public function getClaimForToken($accessToken, $claim)
+    {
+        if (!is_string($accessToken)) {
+            throw new TokenValidationException('Access token is not a string');
+        }
+        if (!is_string($claim)) {
+            throw new \InvalidArgumentException('Claim is not a string');
+        }
+
+        $decodedToken = $this->decodeToken($accessToken, $this->retrieveJWTCertificate());
+
+        if (isset($decodedToken[$claim]) && is_string($decodedToken[$claim])) {
+            return $decodedToken[$claim];
+        }
+        return null;
+    }
+
     /**
      * Checks the supplied config, verifies that all required parameters are present and
      * contain a non null value;

test/unit/Persona/TokensTest.php

@@ -1309,6 +1309,38 @@ public function testRetrieveJWTCertificateCachingSaveFailure()
         $tokens->retrieveJWTCertificate();
     }
 
+    /**
+     * @covers Tokens::getSubjectIdFromToken
+     */
+    public function testGetSubjectIdFromTokenReturnsClientIdFromToken()
+    {
+        $mockClient = $this->getMockTokensClientWithFakeCertificate();
+
+        $fakeClientId = 'this-is-a-fake-client-id';
+        $accessToken = $this->getFakeJWT([
+            'sub' => $fakeClientId,
+            'scopes' => [$fakeClientId]
+        ]);
+
+        $clientIdFromToken = $mockClient->getSubjectIdFromToken($accessToken);
+        $this->assertEquals($fakeClientId, $clientIdFromToken);
+    }
+
+    /**
+     * @covers Tokens::getSubjectIdFromToken
+     */
+    public function testGetSubjectIdFromTokenThrowsExceptionIfTokenContainsNoSubClaim()
+    {
+        $mockClient = $this->getMockTokensClientWithFakeCertificate();
+
+        $accessToken = $this->getFakeJWT([
+            'sub' => null
+        ]);
+
+        $this->setExpectedException(InvalidTokenException::class);
+        $mockClient->getSubjectIdFromToken($accessToken);
+    }
+
     /**
      * Gets the client with mocked HTTP responses.
      *
@@ -1323,4 +1355,54 @@ private function getMockHttpClient(array $responses = [])
 
         return $httpClient;
     }
+
+    /**
+     * Create a mock `Tokens` client, with the cache backend and certificate defined in instance variables
+     * for this class.
+     * @return \Talis\Persona\Client\Tokens
+     */
+    private function getMockTokensClientWithFakeCertificate()
+    {
+        /** @var \Talis\Persona\Client\Tokens|\PHPUnit_Framework_MockObject_MockObject $mockClient */
+        $mockClient = $this->getMock(
+            \Talis\Persona\Client\Tokens::class,
+            ['retrieveJWTCertificate'],
+            [
+                [
+                    'userAgent' => 'unittest',
+                    'persona_host' => 'localhost',
+                    'cacheBackend' => $this->cacheBackend,
+                ]
+            ]
+        );
+
+        $mockClient->expects($this->once())
+            ->method('retrieveJWTCertificate')
+            ->willReturn($this->publicKey);
+
+        return $mockClient;
+    }
+
+    /**
+     * Creates a fake JWT with realistic-looking claim data.
+     *
+     * @param array $claims An array of JWT claims.
+     * @return string An encoded JWT encapsulating the specified claims
+     */
+    private function getFakeJWT(array $claims = [])
+    {
+        $now = time();
+        $fakeSubjectClientId = "fake-sub-client-id-{$now}";
+        $fakeAudienceClientId = "fake-aud-client-id-{$now}";
+        $defaultClaims = [
+            'aud' => $fakeAudienceClientId,
+            'exp' => $now + 100,
+            'iat' => $now,
+            'jti' => $now,
+            'scopes' => [$fakeSubjectClientId],
+            'sub' => $fakeSubjectClientId
+        ];
+        $claimsWithDefaults = array_merge($defaultClaims, $claims);
+        return JWT::encode($claimsWithDefaults, $this->privateKey, 'RS256');
+    }
 }