MIGRATE-v5-TO-v7.md

Migration Guide for v5 to v7

The v7 major release adds some new features, removes a number of deprecated methods and classes, and changes how some applications need to be configured. Please read through this guide to make sure your application is up to date before upgrading to v7.

Only potentially breaking changes are covered in this guide. For a list of all changes for this major, see the 7.0.0 milestone on GitHub.

PHP version increase

The v7 release requires PHP 7.1 or later to enable a number of helpful features like type hinting and null coalescing.

Auth0 class configuration changes

A number of breaking changes were made to the Auth0 class configuration passed in at initialization.

The main breaking change is only for applications that accept HS256 ID tokens. If your application is set to accept ID tokens signed using the HS256 algorithm, we recommend changing that to RS256 in the Auth0 Application > Settings tab > Advanced settings > OAuth tab > JsonWebToken Signature Algorithm field before upgrading and leaving the id_token_alg configuration key unset. If your application cannot be changed for some reason, set the id_token_alg configuration key to HS256, like so:

$auth0 = new Auth0([
	'domain' => 'your-tenant.auth0.com',
	'client_id' => 'application_client_id',
	'client_secret' => 'application_client_secret',
	'redirect_uri' => 'https://yourapplication.com/auth/callback',
	'id_token_alg' => 'HS256'
]);

The id_token_aud and id_token_iss configuration keys have been removed and their values will now be ignored.

The state_handler configuration key has been removed and the transient_store configuration key has been added. See the State and nonce handling section below for more information about the changes with state handling.

The ability to pass false in the store configuration key has been removed. Set store to an instance of EmptyStore or set all persist_* configuration keys to false to skip all persistence.

The cache_handler configuration key must now be an instance of Psr\SimpleCache\CacheInterface. See the Cache handling section below for more information.

The default secret_base64_encoded value is now false and is no longer stored in a property.

The client_secret configuration key is no longer required for class initialization (but will throw an exception in certain methods when required). If secret_base64_encoded is set to true then then the clientSecret property will now contain the decoded secret. If your Application is using an encoded secret, this encoding can be turned off tby rotating the client secret in the Auth0 Application settings.

The session_cookie_expires configuration key has been removed. The session cookie expiration should be managed in the application. If you were using this setting before, see the PHP core function session_set_cookie_params() to set this value after upgrading.

The session_base_name configuration key has been removed. Instead, pass an instance of StoreInterface in the store configuration key with the modified name.

The skip_userinfo configuration key now defaults to true. This means that the persisted user identity will now come from the ID token rather than a call to the userinfo endpoint. This can be set to false to return to the behavior in v5.

The ENV variables AUTH0_DOMAIN, AUTH0_CLIENT_ID, and AUTH0_REDIRECT_URI will now be used automatically for the domain, client_id, and redirect_uri configuration keys, respectively.

The debug configuration key was removed.

Cache handling

Cache handling has been changed in v7 to conform to the PSR-16 standard (see the discussion here). Objects passed to the cache_handler configuration key in Auth0 and the first parameter of the JWKFetcher class should be instances of Psr\SimpleCache\CacheInterface.

State and nonce handling

The handling for transient authentication data, such as state and nonce, has been changed.

In an effort to enforce security standards set forth in the OAuth and OpenID Connect specifications, state checking on the callback route and nonce checking for all received ID tokens is now mandatory. Applications that require IdP-initiated sign-on should add a login route that uses Auth0->getLoginUrl() to redirect through Auth0 with valid state and nonce values. The URL to this route should be saved to the Application Login URI field in your Auth0 Application to assist with this scenario.

The handling for these values was changed from PHP session-stored values to cookies using the new CookieStore class. This was done so PHP session usage was not required and to assist with applications using a form_post reponse mode. This change may require server-level whitelisting of cookie names (auth0__nonce and auth0__state by default) on some managed hosts. The transient_store configuration key in the Auth0 class can be used to switch back to PHP sessions or provide another method.

The default state key was changed from auth0__webauth_state to auth0__state.

Classes and Interfaces removed

The following classes were removed in v7:

• Class Firebase\JWT\JWT provided by the firebase/php-jwt package was replaced with classes from the lcobucci/jwt package
• Class JWTVerifier was removed, see the Auth0->decodeIdToken() method for how to use the replacement classes
• Class StateHandler was removed, see the State and nonce handling section above for more information
• Class SessionStateHandler was removed, see the State and nonce handling section above for more information
• Class DummyStateHandler was removed, see the State and nonce handling section above for more information
• Interface CacheHandler was removed, see the Cache handling section above for more information
• Class FileSystemCacheHandler was removed, see the Cache handling section above for more information
• Class TokenGenerator was removed, no replacement provided
• Class Oauth2Client was removed, no replacement provided
• Class Auth0Api was removed, no replacement provided
• Class Auth0AuthApi was removed, no replacement provided
• Class Auth0JWT was removed, no replacement provided

Classes changes

The following class constructors were changed in v7:

• Class Authentication now requires a client_id parameter
• Class NoCacheHandler now implements Psr\SimpleCache\CacheInterface
• Class JWKFetcher now requires an instance of Psr\SimpleCache\CacheInterface as the first construct parameter
• Class constant SessionStore::COOKIE_EXPIRES was removed
• Class SessionStore no longer accepts a 2nd constructor argument to adjust the session cookie expiration; see the PHP core function session_set_cookie_params() to set this value in v7
• Class Auth0\SDK\API\Header\Authorization\AuthorizationBearer was changed to Auth0\SDK\API\Header\AuthorizationBearer

Methods changed

The following methods were changed in a breaking way in v7:

• Public method RequestBuilder->withHeader() now only accepts a Header instance as an argument.
• Public method Authentication->code_exchange() now throws an ApiException if class-level client_secret is empty
• Public method Authentication->client_credentials() now throws an ApiException if audience is empty
• Public method Authentication->get_authorize_link() now adds class-level scope and audience if none are passed in

Methods removed

The following methods were removed in v7:

• Public magic method ApiClient->__call() was removed, use ApiClient->method() to indicate an HTTP verb to use
• Public magic method RequestBuilder->__call() was removed, use RequestBuilder->addPath() to add paths
• Public method RequestBuilder->addPathVariable() was removed, use RequestBuilder->addPath() to add paths
• Public method RequestBuilder->dump() was removed, no replacement provided
• Public method RequestBuilder->withParams() was removed, use RequestBuilder->withDictParams() to add params
• Public method InformationHeaders->setEnvironment() was removed, no replacement provided
• Public method InformationHeaders->setDependency() was removed, no replacement provided
• Public method InformationHeaders->setDependencyData() was removed, no replacement provided
• Public method ClientGrants->get() was removed, no replacement provided
• Public method Users->search() was removed, use Users->getAll() instead
• Public method Users->unlinkDevice() was removed, no replacement provided
• Public method JWKFetcher->requestJwkX5c() was removed, use JWKFetcher->getKeys() instead
• Public method JWKFetcher->findJwk() was removed, use JWKFetcher->getKeys() instead
• Public method JWKFetcher->subArrayHasEmptyFirstItem() was removed, no replacement provided
• Public method JWKFetcher->fetchKeys() was removed, use JWKFetcher->getKeys() instead
• Public method Authentication->authorize_with_ro() was removed, no replacement provided
• Public method Authentication->authorize_with_accesstoken() was removed, no replacement provided
• Public method Authentication->impersonate() was removed, no replacement provided
• Public method Authentication->email_code_passwordless_verify() was removed, no replacement provided
• Public method Authentication->sms_code_passwordless_verify() was removed, no replacement provided
• Public method Auth0->setDebugger() was removed, no replacement provided
• Protected method Authentication->setApiClient() was removed, no replacement provided
• Protected method Management->setApiClient() was removed, no replacement provided

Class properties removed

The following properties were removed in v7:

• Public property Management->blacklists was made private, replaced by Management->blacklists()
• Public property Management->clients was made private, replaced by Management->clients()
• Public property Management->client_grants was made private, replaced by Management->clientGrants()
• Public property Management->connections was made private, replaced by Management-> connections()
• Public property Management->deviceCredentials was made private, replaced by Management->deviceCredentials()
• Public property Management->emails was made private, replaced by Management->emails()
• Public property Management->emailTemplates was made private, replaced by Management->emailTemplates()
• Public property Management->grants was made private, replaced by Management->grants()
• Public property Management->jobs was made private, replaced by Management->jobs()
• Public property Management->logs was made private, replaced by Management->logs()
• Public property Management->roles was made private, replaced by Management->roles()
• Public property Management->rules was made private, replaced by Management->rules()
• Public property Management->resource_servers was made private, replaced by Management->resourceServers()
• Public property Management->stats was made private, replaced by Management->stats()
• Public property Management->tenants was made private, replaced by Management->tenants()
• Public property Management->tickets was made private, replaced by Management->tickets()
• Public property Management->userBlocks was made private, replaced by Management->userBlocks()
• Public property Management->users was made private, replaced by Management->users()
• Public property Management->usersByEmail was made private, replaced by Management->usersByEmail()
• Public static property Auth0::$URL_MAP was removed
• Protected property Auth0->stateHandler was removed
• Protected property Auth0->clientSecretEncoded was removed
• Protected property Auth0->debugMode was removed
• Protected property Auth0->debugger was removed
• Protected property SessionStore->session_cookie_expires was removed