Add upgrade guide for version 8

This commit is contained in:
Andrew Millington 2019-07-13 18:41:57 +01:00
parent d9e18e4cbb
commit 52d8861926
No known key found for this signature in database
GPG Key ID: 077754CA23023F4F

View File

@ -6,6 +6,56 @@ permalink: /upgrade-guide/
# 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.
@ -14,10 +64,10 @@ The interface for `getClientEntity()` in the `clientRepositoryInterface` has cha
```patch
public function getClientEntity(
$clientIdentifier,
$clientIdentifier,
- $grantType,
+ $grantType = null,
$clientSecret = null,
$clientSecret = null,
$mustValidateSecret = true
);
```
@ -44,4 +94,4 @@ To generate an encryption key for the `AuthorizationServer` run the following co
~~~ shell
php -r 'echo base64_encode(random_bytes(32)), PHP_EOL;'
~~~
~~~