diff --git a/docs/issuing-tokens.md b/docs/issuing-tokens.md index ac242b5c..2ffdb6dd 100644 --- a/docs/issuing-tokens.md +++ b/docs/issuing-tokens.md @@ -1,59 +1,82 @@ # Issuing tokens -!!! Note - The examples here fetch the configuration object from a hypothetical dependency injection container. - You can create it in the same script or require it from a different file. It basically depends on how your system is bootstrapped. - -To issue new tokens you must create a new token a builder (easier when using the [configuration object](configuration.md)), customise it, and ask it to build the token: +To issue new tokens you must create a new token a builder, customise it, and ask it to build the token: ```php -use Lcobucci\JWT\Configuration; +get(Configuration::class); -assert($config instanceof Configuration); +require 'vendor/autoload.php'; + +$tokenBuilder = (new Builder(new JoseEncoder(), ChainedFormatter::default())); +$algorithm = new Sha256(); +$signingKey = InMemory::plainText(random_bytes(32)); $now = new DateTimeImmutable(); -$token = $config->builder() - // Configures the issuer (iss claim) - ->issuedBy('http://example.com') - // Configures the audience (aud claim) - ->permittedFor('http://example.org') - // Configures the id (jti claim) - ->identifiedBy('4f1g23a12aa') - // Configures the time that the token was issue (iat claim) - ->issuedAt($now) - // Configures the time that the token can be used (nbf claim) - ->canOnlyBeUsedAfter($now->modify('+1 minute')) - // Configures the expiration time of the token (exp claim) - ->expiresAt($now->modify('+1 hour')) - // Configures a new claim, called "uid" - ->withClaim('uid', 1) - // Configures a new header, called "foo" - ->withHeader('foo', 'bar') - // Builds a new token - ->getToken($config->signer(), $config->signingKey()); +$token = $tokenBuilder + // Configures the issuer (iss claim) + ->issuedBy('http://example.com') + // Configures the audience (aud claim) + ->permittedFor('http://example.org') + // Configures the id (jti claim) + ->identifiedBy('4f1g23a12aa') + // Configures the time that the token was issue (iat claim) + ->issuedAt($now) + // Configures the time that the token can be used (nbf claim) + ->canOnlyBeUsedAfter($now->modify('+1 minute')) + // Configures the expiration time of the token (exp claim) + ->expiresAt($now->modify('+1 hour')) + // Configures a new claim, called "uid" + ->withClaim('uid', 1) + // Configures a new header, called "foo" + ->withHeader('foo', 'bar') + // Builds a new token + ->getToken($algorithm, $signingKey); + +echo $token->toString(); ``` Once you've created a token, you're able to retrieve its data and convert it to its string representation: ```php -use Lcobucci\JWT\Configuration; +get(Configuration::class); -assert($config instanceof Configuration); +use Lcobucci\JWT\Encoding\ChainedFormatter; +use Lcobucci\JWT\Encoding\JoseEncoder; +use Lcobucci\JWT\Signer\Key\InMemory; +use Lcobucci\JWT\Signer\Hmac\Sha256; +use Lcobucci\JWT\Token\Builder; -$token = $config->builder() - ->issuedBy('http://example.com') - ->withClaim('uid', 1) - ->withHeader('foo', 'bar') - ->getToken($config->signer(), $config->signingKey()); +require 'vendor/autoload.php'; + +$tokenBuilder = (new Builder(new JoseEncoder(), ChainedFormatter::default())); +$algorithm = new Sha256(); +$signingKey = InMemory::plainText(random_bytes(32)); + +$token = $tokenBuilder + ->issuedBy('http://example.com') + ->withClaim('uid', 1) + ->withHeader('foo', 'bar') + ->getToken($algorithm, $signingKey); $token->headers(); // Retrieves the token headers $token->claims(); // Retrieves the token claims -echo $token->headers()->get('foo'); // will print "bar" -echo $token->claims()->get('iss'); // will print "http://example.com" -echo $token->claims()->get('uid'); // will print "1" +echo $token->headers()->get('foo'), PHP_EOL; // will print "bar" +echo $token->claims()->get('iss'), PHP_EOL; // will print "http://example.com" +echo $token->claims()->get('uid'), PHP_EOL; // will print "1" + +echo $token->toString(), PHP_EOL; // The string representation of the object is a JWT string -echo $token->toString(); // The string representation of the object is a JWT string ``` + +!!! Note + Some systems make use of components to handle dependency injection. + If your application follows that practice, using a [configuration object](configuration.md) might simplify the wiring of this library. diff --git a/docs/parsing-tokens.md b/docs/parsing-tokens.md index 0388d461..b154cb0d 100644 --- a/docs/parsing-tokens.md +++ b/docs/parsing-tokens.md @@ -1,29 +1,37 @@ # Parsing tokens -!!! Note - The examples here fetch the configuration object from a hypothetical dependency injection container. - You can create it in the same script or require it from a different file. It basically depends on how your system is bootstrapped. - -To parse a token you must create a new parser (easier when using the [configuration object](configuration.md)) and ask it to parse a string: +To parse a token you must create a new parser and ask it to parse a string: ```php -use Lcobucci\JWT\Configuration; +get(Configuration::class); -assert($config instanceof Configuration); +require 'vendor/autoload.php'; -$token = $config->parser()->parse( - 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.' - . 'eyJzdWIiOiIxMjM0NTY3ODkwIn0.' - . '2gSBz9EOsQRN9I-3iSxJoFt7NtgV6Rm0IL6a8CAwl3Q' -); +$parser = new Parser(new JoseEncoder()); +try { + $token = $parser->parse( + 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.' + . 'eyJzdWIiOiIxMjM0NTY3ODkwIn0.' + . '2gSBz9EOsQRN9I-3iSxJoFt7NtgV6Rm0IL6a8CAwl3Q' + ); +} catch (CannotDecodeContent | InvalidTokenStructure | UnsupportedHeaderFound $e) { + echo 'Oh no, an error: ' . $e->getMessage(); +} assert($token instanceof UnencryptedToken); -$token->headers(); // Retrieves the token headers -$token->claims(); // Retrieves the token claims +echo $token->claims()->get('sub'), PHP_EOL; // will print "1234567890" + ``` -!!! Important - In case of parsing errors the Parser will throw an exception of type `InvalidArgumentException`. +!!! Note + Some systems make use of components to handle dependency injection. + If your application follows that practice, using a [configuration object](configuration.md) might simplify the wiring of this library. diff --git a/docs/validating-tokens.md b/docs/validating-tokens.md index 807f46c7..7111a310 100644 --- a/docs/validating-tokens.md +++ b/docs/validating-tokens.md @@ -1,36 +1,36 @@ # Validating tokens -!!! Note - The examples here fetch the configuration object from a hypothetical dependency injection container. - You can create it in the same script or require it from a different file. It basically depends on how your system is bootstrapped. - -To validate a token you must create a new validator (easier when using the [configuration object](configuration.md)) and assert or validate a token. +To validate a token you must create a new validator and assert or validate a token. ## Using `Lcobucci\JWT\Validator#assert()` -!!! Warning - You **MUST** provide at least one constraint, otherwise `\Lcobucci\JWT\Validation\NoConstraintsGiven` exception will be thrown. - This method goes through every single constraint in the set, groups all the violations, and throws an exception with the grouped violations: ```php -use Lcobucci\JWT\Configuration; -use Lcobucci\JWT\UnencryptedToken; +get(Configuration::class); -assert($config instanceof Configuration); +$parser = new Parser(new JoseEncoder()); -$token = $config->parser()->parse('...'); -assert($token instanceof UnencryptedToken); +$token = $parser->parse( + 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.' + . 'eyJzdWIiOiIxMjM0NTY3ODkwIn0.' + . '2gSBz9EOsQRN9I-3iSxJoFt7NtgV6Rm0IL6a8CAwl3Q' +); -// validation constraints can be set in the configuration with -// the setValidationConstraints() setter -// see the Customisation part of the Configuration documentation -$constraints = $config->validationConstraints(); +$validator = new Validator(); try { - $config->validator()->assert($token, ...$constraints); + $validator->assert($token, new RelatedTo('1234567891')); // doesn't throw na exception + $validator->assert($token, new RelatedTo('1234567890')); } catch (RequiredConstraintsViolated $e) { // list of constraints violation exceptions: var_dump($e->violations()); @@ -39,31 +39,43 @@ try { ## Using `Lcobucci\JWT\Validator#validate()` -!!! Warning - You **MUST** provide at least one constraint, otherwise `\Lcobucci\JWT\Validation\NoConstraintsGiven` exception will be thrown. - The difference here is that we'll always get a `boolean` result and stop in the very first violation: ```php -use Lcobucci\JWT\Configuration; -use Lcobucci\JWT\UnencryptedToken; +get(Configuration::class); -assert($config instanceof Configuration); +$token = $parser->parse( + 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.' + . 'eyJzdWIiOiIxMjM0NTY3ODkwIn0.' + . '2gSBz9EOsQRN9I-3iSxJoFt7NtgV6Rm0IL6a8CAwl3Q' +); -$token = $config->parser()->parse('...'); -assert($token instanceof UnencryptedToken); +$validator = new Validator(); -// validation constraints can be set in the configuration with -// the setValidationConstraints() setter -// see the Customisation part of the Configuration documentation -$constraints = $config->validationConstraints(); +if (! $validator->validate($token, new RelatedTo('1234567891'))) { + echo 'Invalid token (1)!', PHP_EOL; // will print this +} -if (! $config->validator()->validate($token, ...$constraints)) { - throw new RuntimeException('No way!'); +if (! $validator->validate($token, new RelatedTo('1234567890'))) { + echo 'Invalid token (2)!', PHP_EOL; // will not print this } ``` +!!! Note + Some systems make use of components to handle dependency injection. + If your application follows that practice, using a [configuration object](configuration.md) might simplify the wiring of this library. + + ## Available constraints This library provides the following constraints: @@ -75,14 +87,6 @@ This library provides the following constraints: * `Lcobucci\JWT\Validation\Constraint\SignedWith`: verifies if the token was signed with the expected signer and key * `Lcobucci\JWT\Validation\Constraint\StrictValidAt`: verifies presence and validity of the claims `iat`, `nbf`, and `exp` (supports leeway configuration) * `Lcobucci\JWT\Validation\Constraint\LooseValidAt`: verifies the claims `iat`, `nbf`, and `exp`, when present (supports leeway configuration) -* `Lcobucci\JWT\Validation\Constraint\HasClaimWithValue`: verifies that a custom claim has the expected value (not recommended when comparing cryptographic hashes) - -Example code for adding a constraint to the configuration object: - -```php -use Lcobucci\JWT\Validation\Constraint\PermittedFor; - -$config->setValidationConstraints(new PermittedFor('your-aud-claim')); -``` +* `Lcobucci\JWT\Validation\Constraint\HasClaimWithValue`: verifies that a **custom claim** has the expected value (not recommended when comparing cryptographic hashes) You may also create your [own validation constraints](extending-the-library.md#validation-constraints). diff --git a/mkdocs.yml b/mkdocs.yml index 16018566..8dbba334 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,10 +8,10 @@ nav: - 'quick-start.md' - 'supported-algorithms.md' - Usage: - - 'configuration.md' - 'issuing-tokens.md' - 'parsing-tokens.md' - 'validating-tokens.md' + - 'configuration.md' - Guides: - 'extending-the-library.md' - 'upgrading.md'