You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
var_dump($token->validate($dataWithLeeway)); // false, because token can't be used before now() + 60, not within leeway
103
-
104
-
$dataWithLeeway->setCurrentTime($time + 51); // changing the validation time to future
105
-
106
-
var_dump($token->validate($dataWithLeeway)); // true, because current time plus leeway is between "nbf" and "exp" claims
107
-
108
-
$dataWithLeeway->setCurrentTime($time + 3610); // changing the validation time to future but within leeway
109
-
110
-
var_dump($token->validate($dataWithLeeway)); // true, because current time - 20 seconds leeway is less than exp
111
-
112
-
$dataWithLeeway->setCurrentTime($time + 4000); // changing the validation time to future outside of leeway
113
-
114
-
var_dump($token->validate($dataWithLeeway)); // false, because token is expired since current time is greater than exp
115
-
```
116
-
117
-
#### Important
118
-
119
-
- You have to configure ```ValidationData``` informing all claims you want to validate the token.
120
-
- If ```ValidationData``` contains claims that are not being used in token or token has claims that are not
121
-
configured in ```ValidationData``` they will be ignored by ```Token::validate()```.
122
-
-```exp```, ```nbf``` and ```iat``` claims are configured by default in ```ValidationData::__construct()```
123
-
with the current UNIX time (```time()```).
124
-
- The optional ```$leeway``` parameter of ```ValidationData``` will cause us to use that number of seconds of leeway
125
-
when validating the time-based claims, pretending we are further in the future for the "Issued At" (```iat```) and "Not
126
-
Before" (```nbf```) claims and pretending we are further in the past for the "Expiration Time" (```exp```) claim. This
127
-
allows for situations where the clock of the issuing server has a different time than the clock of the verifying server,
128
-
as mentioned in [section 4.1 of RFC 7519](https://tools.ietf.org/html/rfc7519#section-4.1).
129
-
130
-
## Token signature
131
-
132
-
We can use signatures to be able to verify if the token was not modified after its generation. This library implements Hmac, RSA and ECDSA signatures (using 256, 384 and 512).
133
-
134
-
### Important
135
-
136
-
Do not allow the string sent to the Parser to dictate which signature algorithm
137
-
to use, or else your application will be vulnerable to a [critical JWT security vulnerability](https://auth0.com/blog/2015/03/31/critical-vulnerabilities-in-json-web-token-libraries).
138
-
139
-
The examples below are safe because the choice in `Signer` is hard-coded and
140
-
cannot be influenced by malicious users.
141
-
142
-
### Hmac
143
-
144
-
Hmac signatures are really simple to be used:
145
-
146
-
```php
147
-
use Lcobucci\JWT\Builder;
148
-
use Lcobucci\JWT\Signer\Key;
149
-
use Lcobucci\JWT\Signer\Hmac\Sha256;
150
-
151
-
$signer = new Sha256();
152
-
$time = time();
153
-
154
-
$token = (new Builder())->issuedBy('http://example.com') // Configures the issuer (iss claim)
155
-
->permittedFor('http://example.org') // Configures the audience (aud claim)
156
-
->identifiedBy('4f1g23a12aa', true) // Configures the id (jti claim), replicating as a header item
157
-
->issuedAt($time) // Configures the time that the token was issue (iat claim)
158
-
->canOnlyBeUsedAfter($time + 60) // Configures the time that the token can be used (nbf claim)
159
-
->expiresAt($time + 3600) // Configures the expiration time of the token (exp claim)
160
-
->withClaim('uid', 1) // Configures a new claim, called "uid"
161
-
->getToken($signer, new Key('testing')); // Retrieves the generated token
162
-
163
-
164
-
var_dump($token->verify($signer, 'testing 1')); // false, because the key is different
165
-
var_dump($token->verify($signer, 'testing')); // true, because the key is the same
166
-
```
167
-
168
-
### RSA and ECDSA
169
-
170
-
RSA and ECDSA signatures are based on public and private keys so you have to generate using the private key and verify using the public key:
171
-
172
-
```php
173
-
use Lcobucci\JWT\Builder;
174
-
use Lcobucci\JWT\Signer\Key;
175
-
use Lcobucci\JWT\Signer\Rsa\Sha256; // you can use Lcobucci\JWT\Signer\Ecdsa\Sha256 if you're using ECDSA keys
176
-
177
-
$signer = new Sha256();
178
-
$privateKey = new Key('file://{path to your private key}');
179
-
$time = time();
180
-
181
-
$token = (new Builder())->issuedBy('http://example.com') // Configures the issuer (iss claim)
182
-
->permittedFor('http://example.org') // Configures the audience (aud claim)
183
-
->identifiedBy('4f1g23a12aa', true) // Configures the id (jti claim), replicating as a header item
184
-
->issuedAt($time) // Configures the time that the token was issue (iat claim)
185
-
->canOnlyBeUsedAfter($time + 60) // Configures the time that the token can be used (nbf claim)
186
-
->expiresAt($time + 3600) // Configures the expiration time of the token (exp claim)
187
-
->withClaim('uid', 1) // Configures a new claim, called "uid"
188
-
->getToken($signer, $privateKey); // Retrieves the generated token
189
-
190
-
$publicKey = new Key('file://{path to your public key}');
191
-
192
-
var_dump($token->verify($signer, $publicKey)); // true when the public key was generated by the private one =)
193
-
```
194
-
195
-
**It's important to say that if you're using RSA keys you shouldn't invoke ECDSA signers (and vice-versa), otherwise ```sign()``` and ```verify()``` will raise an exception!**
23
+
The documentation is available at <https://lcobucci-jwt.readthedocs.io/en/3.4.0/>.
$key = InMemory::file(__DIR__ . '/path-to-my-key-stored-in-a-file.pem'); // this reads the file and keeps its contents in memory
47
+
$key = LocalFileReference::file(__DIR__ . '/path-to-my-key-stored-in-a-file.pem'); // this just keeps a reference to file
48
+
```
49
+
50
+
#### For symmetric algorithms
51
+
52
+
Symmetric algorithms use the same key for both signature creation and verification.
53
+
This means that it's really important that your key **remains secret**.
54
+
55
+
!!! Tip
56
+
It is recommended that you use a key with lots of entropy, preferably generated using a cryptographically secure pseudo-random number generator (CSPRNG).
57
+
You can use the [CryptoKey](https://github.com/AndrewCarterUK/CryptoKey) tool to do this for you.
// You may also override the JOSE encoder/decoder if needed by providing extra arguments here
104
+
);
105
+
```
106
+
107
+
### Customisation
108
+
109
+
By using the setters of the `Lcobucci\JWT\Configuration` you may customise the setup of this library.
110
+
111
+
!!! Important
112
+
If you want to use a customised configuration, please make sure you call the setters before of invoking any getter.
113
+
Otherwise, the default implementations will be used.
114
+
115
+
These are the available setters:
116
+
117
+
*`Lcobucci\JWT\Configuration#setBuilderFactory()`: configures how the token builder should be created
118
+
*`Lcobucci\JWT\Configuration#setParser()`: configures a custom token parser
119
+
*`Lcobucci\JWT\Configuration#setValidator()`: configures a custom validator
120
+
*`Lcobucci\JWT\Configuration#setValidationConstraints()`: configures the default set of validation constraints
121
+
122
+
### Retrieve components
123
+
124
+
Once you've made all the necessary configuration you can pass the configuration object around your code and use the getters to retrieve the components:
125
+
126
+
These are the available getters:
127
+
128
+
*`Lcobucci\JWT\Configuration#builder()`: retrieves the token builder (always creating a new instance)
129
+
*`Lcobucci\JWT\Configuration#parser()`: retrieves the token parser
130
+
*`Lcobucci\JWT\Configuration#signer()`: retrieves the signer
131
+
*`Lcobucci\JWT\Configuration#signingKey()`: retrieves the key for signature creation
132
+
*`Lcobucci\JWT\Configuration#verificationKey()`: retrieves the key for signature verification
133
+
*`Lcobucci\JWT\Configuration#validator()`: retrieves the token validator
134
+
*`Lcobucci\JWT\Configuration#validationConstraints()`: retrieves the default set of validation constraints
This package is available on [Packagist] and you can install it using [Composer].
4
+
5
+
By running the following command you'll add `lcobucci/jwt` as a dependency to your project:
6
+
7
+
```sh
8
+
composer require lcobucci/jwt
9
+
```
10
+
11
+
## Autoloading
12
+
13
+
!!! Note
14
+
We'll be omitting the autoloader from the code samples to simplify the documentation.
15
+
16
+
In order to be able to use the classes provided by this library you're also required to include [Composer]'s autoloader in your application:
17
+
18
+
```php
19
+
require 'vendor/bin/autoload.php';
20
+
```
21
+
22
+
!!! Tip
23
+
If you're not familiar with how [composer] works, we highly recommend you to take some time to read it's documentation - especially the [autoloading section].
0 commit comments