Skip to content

Latest commit

 

History

History
709 lines (557 loc) · 45.8 KB

UPGRADE.md

File metadata and controls

709 lines (557 loc) · 45.8 KB
Raw

Migration Guide

Upgrading from v7.x → v8.0

Our version 8 release includes many significant improvements:

  • Adoption of modern PHP language features including typed properties, null coalescing assignment operators, and array spreading.
  • Support for custom PSR-18 and PSR-17 factories for customizing network requests. PSR-7 responses are also now returned throughout the SDK.
  • PSR-4 event hooks are now supported throughout the SDK.
  • Fluent interface throughout the SDK, offering simplified usage.
  • Optional auto-pagination of Management API endpoints that support pagination.
  • PKCE is now enabled by default.
  • Improved JWT processing and fewer dependencies.

As is to be expected with a major release, there are breaking changes in this update. Please ensure you read this guide thoroughly and prepare your app before upgrading to SDK v8.

New minimum PHP version: 7.4 (8.0 preferred)

  • SDK v8.0 requires PHP 7.4 or higher. PHP 8.0 is supported, and its use with this library is preferred and strongly encouraged.
  • 7.4 will be the final release in PHP's 7.x branch. This SDK will only support PHP 8.0+ after 7.4 leaves supported status in November 2022.
  • We strongly encourage you to make use of PHP 8.0's new named arguments language feature. Once 7.4 support ends, we will no longer consider method argument order changes to be a breaking change.

Session Storage Chan ges Require User Reauthentication

The new default session storage medium in 8.0 are encrypted cookies. Upgrading to 8.0 from 7.x will require your application's users to re-authenticate.

Class and Method Changes

Potentially Breaking Changes

These classes were updated in SDK 8.0:

  • Class Auth0\SDK\Auth0 updated:

    • __construct updated:
      • configuration added as a required instance of either an SdkConfiguration class, or an array of configuration options. See the 8.0 configuration and 8.0 configuration options guides for usage information.
      • All other arguments have been removed.
    • Public method authentication() added. It returns a pre-configured singleton of the Auth0\SDK\API\Authentication class.
    • Public method management() added. It returns a pre-configured singleton of the Auth0\SDK\API\Management class.
    • Public method login() updated:
      • Method now accepts an argument, params: an array of parameters to pass with the API request.
      • Arguments state, connection, and additionalParameters have been removed. Use the new params argument for these uses.
      • Method now returns an intended login URL as a string. Method no longer sends redirect headers itself to better integrate with application frameworks. Developers should redirect users to the returned URL using a method appropriate for the application type/framework. For example, the redirect() method in Laravel or Symfony, Header("Location: $url") with plain PHP, etc.
    • Public method signup() added as a convenience. This method will pass the ?screen_hint=signup param, supported by the New Universal Login Experience.
    • Public method getLoginUrl() moved to Auth0\SDK\API\Authentication\getLoginLink(), and:
      • Argument params is now a nullable array.
    • Public method renewTokens() renamed to renew(), and:
      • Argument options renamed to params and is now a nullable array.
    • Public method decodeIdToken() renamed to decode(), and:
      • Argument idToken renamed to token.
      • Argument verifierOptions removed.
      • Arguments tokenAudience and tokenOrganization added as optional, nullable arrays.
      • Argument tokenNonce added as an optional string.
      • Arguments tokenMaxAge, tokenLeeway, and tokenNow were added as optional, nullable integers.
      • Now returns an instance of Auth0\SDK\Token instead of an array.
    • Public methods getAuthorizationCode() and getState() were removed; please use getRequestParameter() method.
    • Public method deleteAllPersistentData() renamed to clear().
    • Public methods getNonce() and urlSafeBase64Decode() were removed.
    • Public methods getAccessTokenExpiration() and setAccessTokenExpiration() were added for retrieving for storing an access token expiration timestamp in session storage, respectively.
    • Public methods getUser(), getAccessToken(), getIdToken() and getRefreshToken() no longer implicitly invoke exchange() as was previously the case, and instead return only what is already available in an available session. This change was made to avoid unintentionally invoking the token exchange at inappropriate times, and to allow developers to more easily check for an available session without accidentally executing unwanted code. Developers will need to call Auth0::exchange() themselves when a code exchange is desired to establish a session and store user data, which will then be available for return from the beforementioned methods.
    • Public method getCredentials() added as a convenience. This method returns the Id Token, Access Token, Refresh Token, Access Token expiration timestamp, and user data from an available session without invoking an authorization flow, exchange, or raising an error if a session is not available.

  • Class Auth0\SDK\API\Authentication updated:

    • __construct updated:
      • configuration added as a required instance of either an SdkConfiguration class, or an array of configuration options. See the 8.0 configuration and 8.0 configuration options guides for usage information.
      • All other arguments have been removed.
    • Public method 'getHttpClient()' added.
    • Public method get_authorize_link() renamed to getLoginLink(), and:
      • Method now accepts an argument, params: an array of parameters to pass with the request. Please see the API endpoint documentation for available options. Note also the previously optional state argument is now required.
    • Public method get_samlp_link() renamed to getSamlpLink(), and:
      • Argument client_id renamed to clientId.
    • Public method get_samlp_metadata_link() renamed to getSamlpMetadataLink(), and:
      • Argument client_id renamed to clientId.
    • Public method get_wsfed_link() renamed to getWsfedLink(), and:
      • Argument client_id renamed to clientId.
    • Public method get_wsfed_metadata_link() renamed to getWsfedMetadataLink().
    • Public method get_logout_link() renamed to getLogoutLink(), and:
      • Argument returnTo renamed to returnUri.
      • Arguments client_id and federated were removed.
      • Method now accepts an argument, params: an array of parameters to pass with the request. Please see the API endpoint documentation for available options.
    • Public method passwordlessStart() added.
    • Public method email_passwordless_start() renamed to emailPasswordlessStart(), and:
      • Argument authParams updated to be nullable and defaults to null.
      • Argument headers added to specify additional headers to pass with the request.
      • Argument forwarded_for removed. Use the new headers argument with an 'AUTH0_FORWARDED_FOR' key-value pair for this behavior.
      • Now returns a PSR-7 ResponseInterface, instead of an array.
    • Public method sms_passwordless_start() renamed to smsPasswordlessStart(), and:
      • Argument phone_number renamed to phoneNumber.
      • Argument headers added to specify additional headers to pass with the request.
      • Argument forwarded_for removed. Use the new headers argument with an 'AUTH0_FORWARDED_FOR' key-value pair for this behavior.
      • Now returns a PSR-7 ResponseInterface, instead of an array.
    • Public method userinfo() renamed to userInfo(), and:
      • Argument access_token renamed to accessToken.
      • Now returns a PSR-7 ResponseInterface, instead of an array.
    • Public method oauth_token() renamed to oauthToken(), and:
      • Argument grantType added. It requires a string.
      • Arguments headers and params were added as optional, nullable arrays.
      • Argument options removed. Use the new headers and params arguments for these functions.
      • Now returns a PSR-7 ResponseInterface, instead of an array.
    • Public method code_exchange() renamed to codeExchange(), and:
      • Argument redirect_uri renamed to returnUri.
      • Argument code_verifier renamed to codeVerifier.
      • Now returns a PSR-7 ResponseInterface, instead of an array.
    • Public method login() updated:
      • Arguments username, password, and realm added as required strings.
      • Arguments headers and params were added as optional, nullable arrays.
      • Argument ip_address removed. Use the new headers argument with an 'AUTH0_FORWARDED_FOR' key-value pair for this behavior.
      • Argument options removed. Use the new headers and params arguments for these functions.
      • Now returns a PSR-7 ResponseInterface, instead of an array.
    • Public method login_with_default_directory() renamed to loginWithDefaultDirectory(), and:
      • Arguments username and password added as required strings.
      • Arguments headers and params were added as optional, nullable arrays.
      • Argument ip_address removed. Use the new headers argument with an 'AUTH0_FORWARDED_FOR' key-value pair for this behavior.
      • Argument options removed. Use the new headers and params arguments for these functions.
      • Now returns a PSR-7 ResponseInterface, instead of an array.
    • Public method client_credentials() renamed to clientCredentials(), and:
      • Arguments headers and params were added as optional, nullable arrays.
      • Argument options removed. Use the new headers and params arguments for these functions.
      • Now returns a PSR-7 ResponseInterface, instead of an array.
    • Public method refresh_token() renamed to refreshToken(), and:
      • Argument refresh_token renamed to refreshToken.
      • Arguments headers and params were added as optional, nullable arrays.
      • Argument options removed. Use the new headers and params arguments for these functions.
      • Now returns a PSR-7 ResponseInterface, instead of an array.
    • Public method dbconnections_signup() renamed to dbConnectionsSignup(), and:
      • Arguments body and headers added as optional, nullable arrays.
      • Now returns a PSR-7 ResponseInterface, instead of an array.
    • Public method dbconnections_change_password() changed to dbConnectionsChangePassword(), and:
      • Arguments body and headers added as optional, nullable arrays.
      • Argument password removed. Use the new body argument for this behavior.

  • Class Auth0\SDK\API\Management updated:

    • __construct updated:
      • configuration added as a required instance of either an SdkConfiguration class, or an array of configuration options. See the 8.0 configuration and 8.0 configuration options guides for usage information.
      • All other arguments have been removed.
    • Public method 'getHttpClient()' added.
    • Public method getResponsePaginator() added.

  • Class Auth0\SDK\API\Management\Tenants updated:

    • Public method get renamed to getSettings.
    • Public method update renamed to updateSettings.

  • Class Auth0\SDK\API\Management\GenericResource renamed to Auth0\SDK\API\Management\ManagementEndpoint, and:

    • Constructor updated to require an HttpClient instance; previously expected an ApiClient instance.
    • Public method getApiClient() renamed to getHttpClient().
    • Public method getLastRequest() added.
    • Public methods normalizeRequest(), normalizePagination(), normalizeIncludeTotals(), and normalizeIncludeFields() were removed, and:
      • Their functionality has been rolled into the new Auth0\SDK\Utility\Request\RequestOptions, Auth0\SDK\Utility\Request\FilteredRequest, and Auth0\SDK\Utility\Request\PaginatedRequest utility classes.
    • Public methods checkInvalidPermissions(), checkEmptyOrInvalidString(), and checkEmptyOrInvalidArray() were removed, and:
      • Their functionality has been rolled into the new Auth0\SDK\Utility\Validate utility class.

  • Class Auth0\SDK\Store\StoreInterface moved to Auth0\SDK\Contract\StoreInterface.

  • Class Auth0\SDK\Exception\CoreException moved to Auth0\SDK\Contract\SdkException.

  • Class Auth0\SDK\Helpers\PKCE moved to Auth0\SDK\Utility\PKCE.

  • Class Auth0\SDK\Helpers\TransientStoreHandler moved to Auth0\SDK\Utility\TransientStoreHandler.

Classes Removed

  • All Auth0\SDK\API\Header classes:

    • Class Auth0\SDK\API\Header\AuthorizationBearer.
    • Class Auth0\SDK\API\Header\ContentType.
    • Class Auth0\SDK\API\Header\ForwardedFor.
    • Class Auth0\SDK\API\Header\Header.
    • Class Auth0\SDK\API\Header\Telemetry.

  • All Auth0\SDK\API\Helpers classes:

    • Class Auth0\SDK\API\Helpers\ApiClient superseded by Auth0\SDK\Utility\HttpClient.
    • Class Auth0\SDK\API\Helpers\RequestBuilder superseded by Auth0\SDK\Utility\HttpRequest.
    • Class Auth0\SDK\API\Helpers\InformationHeaders superseded by Auth0\SDK\Utility\HttpTelemetry.

  • All token-related classes have been replaced by the new Auth0\SDK\Token, Auth0\SDK\Token\Parser, Auth0\SDK\Token\Validator, and Auth0\SDK\Token\Verifier classes.

    • Class Auth0\SDK\Helpers\Tokens\AsymmetricVerifier.
    • Class Auth0\SDK\Helpers\Tokens\IdTokenVerifier.
    • Class Auth0\SDK\Helpers\Tokens\SignatureVerifier.
    • Class Auth0\SDK\Helpers\Tokens\SymmetricVerifier.
    • Class Auth0\SDK\Helpers\Tokens\TokenVerifier.
    • Class Auth0\SDK\Helpers\JWKFetcher.

  • Class Auth0\SDK\Exception\ApiException superseded by more specific exception classes.

  • Class Auth0\SDK\Helpers\Cache\NoCacheHandler no longer relevant.

  • Class Auth0\SDK\Store\EmptyStore no longer relevant.

New Additions

These classes and traits were added in SDK 8.0:

  • Class Auth0\SDK\Configuration\SdkConfiguration.

  • Class Auth0\SDK\Configuration\SdkState.

  • Class Auth0\SDK\Contract\ConfigurableContract.

  • Class Auth0\SDK\Exception\ArgumentException.

  • Class Auth0\SDK\Exception\AuthenticationException.

  • Class Auth0\SDK\Exception\ConfigurationException.

  • Class Auth0\SDK\Exception\NetworkException.

  • Class Auth0\SDK\Exception\PaginatorException.

  • Class Auth0\SDK\Exception\StateException.

  • Class Auth0\SDK\Token\Parser.

  • Class Auth0\SDK\Token\Validator.

  • Class Auth0\SDK\Token\Verifier.

  • Class Auth0\SDK\Token.

  • Class Auth0\SDK\Utility\Request\FilteredRequest.

  • Class Auth0\SDK\Utility\Request\PaginatedRequest.

  • Class Auth0\SDK\Utility\Request\RequestOptions.

  • Class Auth0\SDK\Utility\HttpClient.

  • Class Auth0\SDK\Utility\HttpRequest.

  • Class Auth0\SDK\Utility\HttpResponse.

  • Class Auth0\SDK\Utility\HttpResponsePaginator.

  • Class Auth0\SDK\Utility\HttpTelemetry.

  • Class Auth0\SDK\Utility\Shortcut.

  • Class Auth0\SDK\Utility\Validate.

  • Trait Auth0\SDK\Mixins\ConfigurableMixin.

Configuring Auth0 SDK 8.0

Most class constructors throughout the SDK accept a new SdkConfiguration configuration class, which shares your app configuration by reference throughout the SDK's subclasses, allowing you to make changes on the fly from within your app:

use Auth0\SDK\Auth0;
use Auth0\SDK\Configuration\SdkConfiguration;

// PHP 8.0 named arguments syntax
$configuration = new SdkConfiguration(
    domain: 'your-tenant.auth0.com',
    clientId: 'application_client_id',
    clientSecret: 'application_client_secret',
    redirectUri: 'https://yourapplication.com/auth/callback',
    tokenAlgorithm: 'RS256'
);

$auth0 = new Auth0($configuration);

Alternatively, you can use an array to configure the base Auth0 class, and a SdkConfiguration will instantiate for you. Key names must match the same camelCase format of the constructor arguments for SdkConfiguration.

use Auth0\SDK\Auth0;

// PHP 7.4-compatible array syntax
$auth0 = new Auth0([
    'domain' => 'your-tenant.auth0.com',
    'clientId' => 'application_client_id',
    'clientSecret' => 'application_client_secret',
    'redirectUri' => 'https://yourapplication.com/auth/callback',
    'tokenAlgorithm' => 'HS256'
]);

After initializing the Auth0 SDK with your configuration, you can keep a reference to the SdkConfiguration within your app so you can make changes later. The SDK automatically recognizes changes to your SdkConfiguration and uses them.

$configuration = new SdkConfiguration(
    domain: 'your-tenant.auth0.com',
    clientId: 'application_client_id',
    clientSecret: 'application_client_secret',
    redirectUri: 'https://yourapplication.com/auth/callback',
    tokenAlgorithm: 'RS256'
);

$auth0 = new Auth0($configuration);

// Prints 'your-tenant.auth0.com'
echo $configuration->getDomain();

// Change the configuration
$configuration->setDomain('another-tenant.auth0.com');

// Prints 'another-tenant.auth0.com'
echo $configuration->getDomain();

// Will authenticate the user with 'another-tenant.auth0.com'
$auth->login();

Updated Configuration Options

Some options names have changed for clarity. It would be best to reference the SdkConfiguration constructor comments for an up-to-date list, as there may be new additions with later releases. At the time of this guide's writing, these options are available:

$strategy              string|null                    Defaults to 'webapp'. Should be assigned either 'api', 'management', or 'webapp' to specify the type of application the SDK is being applied to. Determines what configuration options will be required at initialization.
$domain                string|null                    Auth0 domain for your tenant, found in your Auth0 Application settings.
$customDomain          string|null                    If you have configured Auth0 to use a custom domain, configure it here.
$clientId              string|null                    Client ID, found in the Auth0 Application settings.
$redirectUri           string|null                    Authentication callback URI, as defined in your Auth0 Application settings.
$clientSecret          string|null                    Client Secret, found in the Auth0 Application settings.
$audience              array<string>|null             One or more API identifiers, found in your Auth0 API settings. The SDK uses the first value for building links. If provided, at least one of these values must match the 'aud' claim to validate an ID Token successfully.
$organization          array<string>|null             One or more Organization IDs, found in your Auth0 Organization settings. The SDK uses the first value for building links. If provided, at least one of these values must match the 'org_id' claim to validate an ID Token successfully.
$usePkce               bool                           Defaults to true. Use PKCE (Proof Key of Code Exchange) with Authorization Code Flow requests. See https://auth0.com/docs/flows/call-your-api-using-the-authorization-code-flow-with-pkce
$scope                 array<string>                  One or more scopes to request for Tokens. See https://auth0.com/docs/scopes
$responseMode          string                         Defaults to 'query.' Where to extract request parameters from, either 'query' for GET or 'form_post' for POST requests.
$responseType          string                         Defaults to 'code.' Use 'code' for server-side flows and 'token' for application side flow.
$tokenAlgorithm        string                         Defaults to 'RS256'. Algorithm to use for Token verification. Expects either 'RS256' or 'HS256'.
$tokenJwksUri          string|null                    URI to the JWKS when verifying RS256 tokens.
$tokenMaxAge           int|null                       The maximum window of time (in seconds) since the 'auth_time' to accept during Token validation.
$tokenLeeway           int                            Defaults to 60. Leeway (in seconds) to allow during time calculations with Token validation.
$tokenCache            CacheItemPoolInterface|null    A PSR-6 compatible cache adapter for storing JSON Web Key Sets (JWKS).
$tokenCacheTtl         int                            How long (in seconds) to keep a JWKS cached.
$httpClient            ClientInterface|null           A PSR-18 compatible HTTP client to use for API requests.
$httpMaxRetries        int                            When a rate-limit (429 status code) response is returned from the Auth0 API, automatically retry the request up to this many times.
$httpRequestFactory    RequestFactoryInterface|null   A PSR-17 compatible request factory to generate HTTP requests.
$httpResponseFactory   ResponseFactoryInterface|null  A PSR-17 compatible response factory to generate HTTP responses.
$httpStreamFactory     StreamFactoryInterface|null    A PSR-17 compatible stream factory to create request body streams.
$httpTelemetry         bool                           Defaults to true. If true, API requests will include telemetry about the SDK and PHP runtime version to help us improve our services.
$sessionStorage        StoreInterface|null            Defaults to use cookies. A StoreInterface-compatible class for storing Token state.
$sessionStorageId      string                         Defaults to 'auth0_session'. The namespace to prefix session items under.
$cookieSecret          string|null                    The secret used to derive an encryption key for the user identity in a session cookie and to sign the transient cookies used by the login callback.
$cookieDomain          string|null                    Defaults to value of HTTP_HOST server environment information. Cookie domain, for example 'www.example.com', for use with PHP sessions and SDK cookies. To make cookies visible on all subdomains then the domain must be prefixed with a dot like '.example.com'.
$cookieExpires         int                            Defaults to 0. How long, in seconds, before cookies expire. If set to 0 the cookie will expire at the end of the session (when the browser closes).
$cookiePath            string                         Defaults to '/'. Specifies path on the domain where the cookies will work. Use a single slash ('/') for all paths on the domain.
$cookieSecure          bool                           Defaults to false. Specifies whether cookies should ONLY be sent over secure connections.
$persistUser           bool                           Defaults to true. If true, the user data will persist in session storage.
$persistIdToken        bool                           Defaults to true. If true, the Id Token will persist in session storage.
$persistAccessToken    bool                           Defaults to true. If true, the Access Token will persist in session storage.
$persistRefreshToken   bool                           Defaults to true. If true, the Refresh Token will persist in session storage.
$transientStorage      StoreInterface|null            Defaults to use cookies. A StoreInterface-compatible class for storing ephemeral state data, such as nonces.
$transientStorageId    string                         Defaults to 'auth0_transient'. The namespace to prefix transient items under.
$queryUserInfo         bool                           Defaults to false. If true, query the /userinfo endpoint during an authorization code exchange.
$managementToken       string|null                    An Access Token to use for Management API calls. If there isn't one specified, the SDK will attempt to get one for you using your $clientSecret.
$managementTokenCache  CacheItemPoolInterface|null    A PSR-6 compatible cache adapter for storing generated management access tokens.
$eventListenerProvider ListenerProviderInterface|null A PSR-14 compatible event listener provider, for interfacing with events triggered by the SDK.

↗ Learn more about PSR-6 caches.
↗ Learn more about PSR-14 Event Dispatchers.
↗ Learn more about PSR-17 HTTP Factories, which are used to create PSR-7 HTTP messages.
↗ Learn more about the PSR-18 HTTP Client standard.
↗ Find PSR-6 cache libraries on Packagist.
↗ Find PSR-17 HTTP factory libraries on Packagist.
↗ Find PSR-18 HTTP client libraries on Packagist.

Using the new Authentication and Management Factories

SDK v8.0 offers a cleaner approach of accessing the Authentication and Management API sub-classes without having to reconfigure them independently: configure the base Auth0 class, and use the factory methods to configure these API sub-classes for you:

use Auth0\SDK\Auth0;

// Configure just once:
$auth0 = new Auth0([
    'domain' => 'your-tenant.auth0.com',
    'clientId' => 'application_client_id',
    'clientSecret' => 'application_client_secret',
    'redirectUri' => 'https://yourapplication.com/auth/callback',
    'tokenAlgorithm' => 'HS256'
]);

// Returns an instance already configured for you.
$authentication = $auth0->authentication();
$management = $auth0->management();

// Or, a fluent example:
$response = $auth0->management()->users()->getAll();

Support for PSR-18 and PSR-17 factories

Previous versions of the Auth0 PHP SDK had a dependency on Guzzle for issuing network requests. SDK v8.0 uses a more modern approach of accepting developer-supplied PSR-18 and PSR-17 factory interfaces for making these requests. We strongly encourage you to pass the factories of your choice during SDK configuration. The SDK will make a best-effort attempt at auto-discovering any compatible libraries present in your application when none are specified.

As an example, let's say your application is already incorporating Buzz and Nylom's PSR-7 implementation, which include PSR-18 and PSR-17 factories, respectively. Pass these to the SDK to use them:

use Auth0\SDK\Auth0;
use Auth0\SDK\Configuration\SdkConfiguration;
use Buzz\Client\MultiCurl;
use Nyholm\Psr7\Factory\Psr17Factory;

// PSR-17 HTTP Factory (creates http requests and responses)
$httpFactory = new Psr17Factory();

 // PSR-18 HTTP Client (delivers http requests created by the PSR-17 factory above)
$httpClient = new MultiCurl($httpFactory);

$configuration = new SdkConfiguration(
    domain: 'your-tenant.auth0.com',
    clientId: 'application_client_id',
    redirectUri: 'https://yourapplication.com/auth/callback',

    // Specify a PSR-18 HTTP client factory:
    httpClient: $httpClient

    // Specify PSR-17 request/response factories:
    httpRequestFactory: $httpFactory
    httpResponseFactory: $httpFactory
    httpStreamFactory: $httpFactory
);

$auth0 = new Auth0($configuration);

The libraries specified above are simply examples. Any libraries that support the PSR-18 and PSR-17 standards will work.

↗ Guzzle 7 natively supports PSR-18.
↗ Guzzle 6 is compatible with an adaptor library.
↗ Symfony's HttpClient component natively supports PSR-18.
↗ Learn about other compatible libraries from PHP-HTTP.
↗ Search packagist for other PSR-17 HTTP factory libraries.
↗ Search packagist for other PSR-18 HTTP client libraries.

Support for PSR-7 responses

Most functions that issue network requests now return PSR-7 message interfaces, which allow you a greater deal of control over handling the response, such as troubleshooting errors and analyzing headers. We've included a utility class for simplifying working with these responses in general use cases:

use Auth0\SDK\Auth0;
use Auth0\SDK\Utility\HttpResponse;

$auth0 = new Auth0(/* ...configuration */);

// Get all users via fluent interface
$response = $auth0->management()->users()->getAll();

if (HttpResponse::wasSuccessful($response)) { // Checks that the status code was 200
    $users = HttpResponse::decodeContent($response); // Parses the response body as JSON and returns the resulting object
    print_r($users);

    $headers = HttpResponse::getHeaders($response); // Get an array containing all the headers attached to the response.
    print_r($headers);
}

Alternatively, you can achieve the same results with the native PSR-7 standard API without using the HttpResponse utility class:

use Auth0\SDK\Auth0;
use Auth0\SDK\Utility\HttpResponse;

$auth0 = new Auth0(/* ...configuration */);

// Get all users via fluent interface
$response = $auth0->management()->users()->getAll();

if ($response->getStatusCode() === 200) { // Checks that the status code was 200
    print_r(json_decode($response->getBody()->__toString(), true, 512, JSON_THROW_ON_ERROR)); // Print the parsed JSON response body
    print_r($response->getHeaders()); // Print the array containing all the headers attached to the response.
}

Using the new field filtering and pagination API

A new argument has been added to most network endpoints, accepting a new RequestOptions class type. RequestOptions allows you to specify field-filtered and paginated requests easily:

use Auth0\SDK\Auth0;
use Auth0\SDK\Utility\Request\{RequestOptions, FilteredRequest, PaginatedRequest};

$auth0 = new Auth0(/* ...configuration */);

// Fluent example:
$response = $auth0->management()->users()->getAll(
    request: new RequestOptions(
        fields: new FilteredRequest(
            fields: ['user_id', 'email'],
            includeFields: true
        ),
        pagination: new PaginatedRequest(
            page: 0,
            perPage: 50,
            includeTotals: true
        )
    )
);

↗ Learn more about paginating Auth0 API endpoints here..

Auto-pagination support available

You can use the new HttpResponsePaginator utility class with endpoints that support pagination to return a PHP-native iterator type, which will automatically request new pages of results as you loop through it.

use Auth0\SDK\Auth0;
use Auth0\SDK\Utility\Request\{RequestOptions, FilteredRequest, PaginatedRequest};

$auth0 = new Auth0(/* ...configuration */);

// NOTE: Auto-pagination will only work when include_totals is enabled:
$response = $auth0->management()->users()->getAll(
    request: new RequestOptions(
        pagination: new PaginatedRequest(
            page: 0,
            perPage: 50,
            includeTotals: true
        )
    )
);

// Return an HttpResponsePaginator pre-configured with our request above:
$users = $auth0->management()->getResponsePaginator();

// Count will use the total results available as reported from the API rather than what is loaded into memory.
echo 'There are ' . count($users) . ' results available from the API.';

// Our new iterator will make new, paginated network requests as necessary to retrieve more results:
foreach ($users as $user) {
    print_r($user);
}

// You can find out how many network requests were made with this helper method:
echo 'We made ' . $users->countNetworkRequests() . ' paginated network requests.';

⚠️ Note that SDK 8.0's HttpResponsePaginator does not currently support checkpoint pagination. This will be introduced in a later release.

Using the new Auth0::getCredentials() method to retrieve session credentials

Auth0::getCredentials is a new convenience function that returns the available Id Token, Access Token, Access Token expiration timestamp, and Refresh Token (if one is available) when they are available from session storage. It also returns an accessTokenExpired bool value that you can more easily compare to decide if you need to renew or prompt to log back in.

use Auth0\SDK\Auth0;

$sdk = new Auth0(/* ... configuration */);

// If we've just returned from the callback, remove the ?code parameter from the query by redirecting to index route.
if ($sdk->getRequestParameter('code')) {
    header("Location: /");
    exit;
}

// Use the new helper to silently get state.
$credentials = $sdk->getCredentials();

// If there's no session, begin authentication flow. Alternatively you could render the app in guest mode, or offer a login interstitial, etc.
if (! $credentials) {
   $sdk->login();
}

// We have a session available.
if ($credentials) {
    // If the access token has expired, try to renew it.
    if ($credentials->accessTokenExpired) {
        try {
            $sdk->renew();
        } catch (\Auth0\SDK\Exception\StateException $exception) {
            // Couldn't renew the token, we might not have one based on our requested scopes. Let's fallback to starting a fresh authentication flow.
            $sdk->login();
        }
    }

    // Everything is good. Let's echo info about the user as an example.
    print_r($credentials->user);
}

This saves you from needing to call Auth0::getIdToken(), Auth0::getUser(), Auth0::getAccessToken(), Auth0::getRefreshToken(), and Auth0::getAccessTokenExpiration() separately if you simply want to inspect credentials. Auth0::getCredentials() will not throw an error if credentials aren't available, it will simply return a null value.

Upgrading from v5.x → v7.x

The v7 major release adds some new features, removes several 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.

New minimum PHP version: 7.1

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 by 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 response mode. This change may require server-level white-listing 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