Upgrade Guide

7.x.x → 8.x.x

Version 8.x.x requires PHP 7.1.0 or higher. This is a major release so contains some breaking changes from version 7.x.x. Please read the following notes carefully when upgrading your system.

Public Key Code Exchange (PKCE)

The enableCodeExchangeProof flag has been removed from the AuthCodeGrant. This flag was used to determine whether PKCE checks should be enabled on the server. The server will now initiate PKCE checks whenever a client sends a code challenge.

The AuthCodeGrant has a new flag, requireCodeChallengeForPublicClients. The flag defaults to true and requires all public clients to provide a PKCE code challenge when requesting an access token. If you want to disable this, you can call the function disableRequireCodeChallengeForPublicClients() which will set the flag to false. For security, we recommend you keep this flag set to true.

Client Entity Interface

To identify a client as public or confidential, version 8 of the server calls the new isConfidential() function. You will need to update your client entity implementation to include this new function.

Invalid User for Password Grant

If a user cannot be validated when using the Password Grant, the server will return an invalid_grant error. Previously the server returned an invalid_credentials error. You should notify or update any clients that might expect to receive an invalid_credentials error in this scenario.

Crypt Trait

The encrypt() and decrypt() functions now throw exceptions if no encryption key is set when running these functions.

Access Tokens

Access tokens no longer have the function convertToJwt(). This has been replaced with the magic method __toString().

DateTimeImmutable

Most instances of DateTime have been replaced with DateTimeImmutable instances. You should change your code to use DateTimeImmutable where the library has made these changes. The affected interfaces and their functions are as follows:

RefreshTokenEntityInterface

• getExpiryDateTime()
• setExpiryDateTime()

TokenInterface

• getExpiryDateTime()
• setExpiryDateTime()

Please note that any traits that implement these interfaces have also been updated.

JWT Headers

We no longer set the JTI claim in the header of an issued JWT. The JTI claim is now only present in the payload of the JWT. If any of your code retrieved the JTI from the header, you must update it to retrieve this claim from the payload.

6.x.x → 7.x.x

Version 7.x.x requires PHP 7.0.0 or higher. This version is not backwards compatible with version 6.x.x of the library.

The interface for getClientEntity() in the clientRepositoryInterface has changed. The $grantType argument must now default to null.

  public function getClientEntity(
      $clientIdentifier,
-     $grantType,
+     $grantType = null,
      $clientSecret = null,
      $mustValidateSecret = true
  );

Please see the changelog for a complete list of all changes.

5.1.x → 6.x.x

Version 6.x.x is not backwards compatible with version 5.1.x but only requires you to make one line of code change:

  $server = new AuthorizationServer(
      $clientRepository,
      $accessTokenRepository,
      $scopeRepository,
      $privateKeyPath,
+     'lxZFUEsBCJ2Yb14IF2ygAHI5N4+ZAUXXaSeeJm6+twsUmIen'
-      $publicKeyPath
  );

All you need to do is replace the public key that was being passed into the constructor of AuthorizationServer with a 32 bit encryption key.

To generate an encryption key for the AuthorizationServer run the following command in the terminal:

php -r 'echo base64_encode(random_bytes(32)), PHP_EOL;'