README

Verify JWT's from AWS Cognito

Usage

Juhwit ships with a handful of interfaces and their default implementations.

The main service provided by Juhwit is the JwtDecoder which is composed with the complimentary CognitoClaimVerifier.

<?php use TeamGantt\Juhwit\JwtDecoder; use TeamGantt\Juhwit\Models\UserPool; use TeamGantt\Juhwit\CognitoClaimVerifier; // Create a UserPool to pass to the CognitoClaimVerifier $poolId = 'some pool id from cognito'; $clientIds = ['some client id from cognito']; $region = 'us-east-2'; // we need some public keys in the form of a jwk (accessible via cognito) $jwk = json_decode(file_get_contents('path/to/jwk.json'), true); $pool = new UserPool($poolId, $clientIds, $region, $jwk); $verifier = new CognitoClaimVerifier($pool); $decoder = new JwtDecoder($verifier); // If all is valid we will get a token back - otherwise a TokenException is thrown $token = $decoder->decode($someTokenFromARequest);

Requiring extra claims

A token may be required to have certain claims.

If you want to require claims, such as custom:foo or custom:user, you can require those by providing a second argument to the decode method.

<?php use TeamGantt\Juhwit\JwtDecoder; $decoder = new JwtDecoder($verifier); $token = $decoder->decode($someTokenFromARequest, ['custom:foo', 'custom:user']);

It is also possible to require claim values to be a specific value.

use TeamGantt\Juhwit\JwtDecoder; $decoder = new JwtDecoder($verifier); $token = $decoder->decode($someTokenFromARequest, ['custom:user', 'token_use' => 'id']);

Keep in mind that instances of Token will perform their own checks against required claims. See TeamGantt\Juhwit\Models\Token::getClaimsErrors() for more information.

Customizing token creation

Juhwit provides a default implementations for id tokens and access tokens. After a jwt is verified against a public key, the claims and user provided $requiredClaims are passed to the create method of a TokenFactoryInterface.

The default CognitoTokenFactory will return an IdToken or AccessToken depending on the token type provided. When constructing the JwtDecoder a custom TokenFactoryInterface can be passed to the constructor.

This factory can be used to create custom tokens - the only requirement is that the create method returns a TokenInterface. Any TokenExceptions thrown by the factory will be caught and the token will be considered invalid.

Leveraging docker

Juhwit is tested and developed against PHP 7.4.11. This project uses a combination of docker and direnv to keep a consistent environment. To leverage direnv, cd into the juhwit project directory and run the following:

$ docker build -t juhwit:dev . $ direnv allow 

This will put your current terminal into an environment that uses the dockerized php and composer binaries. You can use them like you normally would i.e:

$ php -v $ composer list 

Running Tests

$ composer test