Facile JOSE Verifier

A library to validate JWT tokens.

How To Use

The suggested and simply way to use it (specially for OAuth2 and OpenID tokens) is using builders.

For better performance you should install ext-gmp.

Create verifiers from Issuer and Client Metadata

Usually an OpenID provider provides an openid-configuration (/.well-known/openid-configuration).

You can fetch the configuration and use it with builders, but usually only issuer and jwks_uri are necessary.

// Fetched issuer metadata:
$issuerMetadata = [
    'issuer' => 'https://issuer-name', // The Issuer name
    'jwks_uri' => 'https://jwks_uri', // The Issuer's JWK Set URI
];

The remote jwks_uri is the remote endpoint where the issuer public keys are exposed.

You also need the Client Metadata, usually the same provided from the OpenID Dynamic Registration but you can just provide the client_id and optionally the client_secret (in case the tokens are signed with symmetric key using the client secret).

Verfiers and decrypters are automatically configured using the OpenID Dynamic Registration client metadata.

If you use encryption, you should inject your JWK Set in the configuration jwks keys.

// Client Metadata (complete configuration example)
$clientMetadata = [
    'client_id' => 'my-client-id',
    'client_secret' => 'my-client-secret',
    'id_token_signed_response_alg' => 'RS256',
    'id_token_encrypted_response_alg' => 'RSA-OAEP',
    'id_token_encrypted_response_enc' => 'A128GCM',
    'userinfo_signed_response_alg' => 'RS256',
    'userinfo_encrypted_response_alg' => 'RSA-OAEP',
    'userinfo_encrypted_response_enc' => 'A128GCM',
    'jwks' => [
        'keys' => [
            // client JWKs
        ],
    ],
];

use Facile\JoseVerifier\Builder\AccessTokenVerifierBuilder;
use Facile\JoseVerifier\Exception\InvalidTokenExceptionInterface;

$builder = AccessTokenVerifierBuilder::create($issuerMetadata, $clientMetadata);

$verifier = $builder->build();
try {
    $payload = $verifier->verify($jwt);
} catch (InvalidTokenExceptionInterface $e) {
    // your logic here
}

The verifier will decrypt and validate the token for you. The result is the token payload.

Using cache to fetch remote JWK Set

Obviously you should not fetch the remote JWK Set on every request. In order to use cache you can inject a partially configured JwksProviderBuilder.

use Facile\JoseVerifier\Builder\AccessTokenVerifierBuilder;use Facile\JoseVerifier\JWK\JwksProviderBuilder;

// Use your PSR SimpleCache implementation
$cache = $container->get(\Psr\SimpleCache\CacheInterface::class);

$jwksProviderBuilder = (new JwksProviderBuilder())
    ->withCache($cache)
    ->withCacheTtl(86400); // 86400 is the default value

$builder = AccessTokenVerifierBuilder::create($issuerMetadata, $clientMetadata)
    ->withJwksProviderBuilder($jwksProviderBuilder);

$verifier = $builder->build();
try {
    $payload = $verifier->verify($jwt);
} catch (InvalidTokenExceptionInterface $e) {
    // your logic here
}

Provided verifiers

Access Token Verifier

The AccessTokenVerifier will validate a JWT access token.

use Facile\JoseVerifier\Builder\AccessTokenVerifierBuilder;

$builder = AccessTokenVerifierBuilder::create($issuerMetadata, $clientMetadata);

$verifier = $builder->build();
try {
    $payload = $verifier->verify($jwt);
} catch (InvalidTokenExceptionInterface $e) {
    // your logic here
}

ID Token Verifier

The IdTokenVerifier will validate an OpenID id_token.

Create the verifier:

use Facile\JoseVerifier\Builder\IdTokenVerifierBuilder;

$builder = IdTokenVerifierBuilder::create($issuerMetadata, $clientMetadata);

$verifier = $builder->build();

In order to validate an id_token you must provide some other parameters to the verifier (note that all verifiers are immutable).

use Facile\JoseVerifier\IdTokenVerifierInterface;

/** @var IdTokenVerifierInterface $verifier */

// Provide the `state` used in the Code Grant Flow (this should be provided id the `id_token` contains the `s_hash` claim)
$verifier = $verifier->withState($state);

// Optionally provide these parameters to validate the correct hash values:

$verifier = $verifier
    ->withAccessToken($accessToken) // Provide the `access_token` used in the Code Grant Flow
    ->withCode($code) // Provide the `code` used in the Code Grant Flow

try {
    $payload = $verifier->verify($jwt);
} catch (InvalidTokenExceptionInterface $e) {
    // your logic here
}

UserInfo Verifier

When UserInfo returns a signed (and maybe encrypted) JWT as response content of the userinfo endpoint you can use this verifier to decrypt, verify, and obtain user info claims.

use Facile\JoseVerifier\Builder\UserInfoVerifierBuilder;

$builder = UserInfoVerifierBuilder::create($issuerMetadata, $clientMetadata);

$verifier = $builder->build();
try {
    $payload = $verifier->verify($jwt);
} catch (InvalidTokenExceptionInterface $e) {
    // your logic here
}

clemlatz/php-jose-verifier