Configuration - fachsimpeln/EasyJWT GitHub Wiki

1. Required Configuration (for security):

EasyJWT is very easy to use, but some configuration is required.

Without making these settings, it is not advisable to use the library, as no keys do not provide security in the signing and encryption procedures.

What needs to be changed?

  1. Signature symmetric key -> $SECRET
  2. Encryption symmetric key -> $ENCRYPTION_KEY
  3. Whitelist of available algorithms -> $JWTAlgorithmWhitelist
/* To allow different keys to be used in a project, the library does not save these settings! 
   You must declare them everytime you want to use the library. */
EasyJWT\JWT::$SECRET         = 'PLEASE_CHANGE';
EasyJWT\JWT::$ENCRYPTION_KEY = 'PLEASE_CHANGE';
EasyJWT\JWT::$JWTAlgorithmWhitelist = ['HS256', 'HS512', 'HS384'];

Remember to always set the keys before using the library in your project. A configuration PHP-file that is included in every script that has access to EasyJWT is recommended.

Whitelist

It is recommended to allow in the configuration only the one algorithm you use (e.g. only HS512). You can achieve that with the array $JWTAlgorithmWhitelist

Please never allow none to be used as a algorithm as it lets users manipulate the JWT.

Example

EasyJWT\JWT::$JWTAlgorithmWhitelist = ['HS512'];

Signature Key

To sign the JWT the library needs a signature key. This key is private and must be set whenever you use the library.

Not setting this secret up will result in a SecurityException

The signature key must be at least as long as the algorithm you want to use specifies it:

Signing Algorithm Key length
HS256 256 bit
HS384 384 bit
HS512 512 bit
none 0 bit (not recommended)

The secret should be completely random, so you should use a strong cryptographic random number generator to generate the secret.

If you not change the secret, or the bit length is smaller than the required length, the library will throw a SecurityException.

Sample Secret Generation for HS512:

EasyJWT\JWT::$SECRET = bin2hex( 
                             openssl_random_pseudo_bytes( 512, $strong ) 
                       );

Encryption Key

The library uses AES-256 in GCM mode provided by openssl for encryption. The key for this encryption is specified in $ENCRYPTION_KEY.

Please choose a secure and random password, that has 256 bit. (generation like Signature Secret Generation for HS256).

2. Cookie Configuration

EasyJWT automatically handles the cookies for you. (if you use EasyJWT for browser-authentication) These settings are not mandatory to change, but you might want to change them.

EasyJWT\JWT::$JWT_COOKIE_NAME = 'EasyJWT';
EasyJWT\JWT::$SSL = false;
EasyJWT\JWT::$HTTP_ONLY = true;

Explanation

  • $JWT_COOKIE_NAME is the** name of the cookie** as a string, by default EasyJWT
  • $SSL is a boolean, which, if set to true, only allows cookie transfer via SSL , by default false
  • $HTTP_ONLY is a boolean, which, if set to true,** only allows cookie access** via the HTTP Protocol - so that JavaScript has no access to it, by default true

3. Reserved Claim Registration

To automatically validate the reserved claims, some information must be given.

Currently the reserved claims exp, nbf and iss will be automatically validated. The rest of the claim validation must be done with the actual software - not with this library.

To validate the iss claim, you must set a issuer name in the configuration, setting this up is pretty easy:

EasyJWT\JWT::$CLAIM_ISSUER = 'fachsimpeln';

That's it! Now you are set. Let's begin creating your first JWT!