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.
- 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.
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.
These classes were updated in SDK 8.0:
-
Class
Auth0\SDK\Auth0
updated:__construct
updated:configuration
added as a required instance of either anSdkConfiguration
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 theAuth0\SDK\API\Authentication
class. - Public method
management()
added. It returns a pre-configured singleton of theAuth0\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
, andadditionalParameters
have been removed. Use the newparams
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.
- Method now accepts an argument,
- 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 toAuth0\SDK\API\Authentication\getLoginLink()
, and:- Argument
params
is now a nullable array.
- Argument
- Public method
renewTokens()
renamed torenew()
, and:- Argument
options
renamed toparams
and is now a nullable array.
- Argument
- Public method
decodeIdToken()
renamed todecode()
, and:- Argument
idToken
renamed totoken.
- Argument
verifierOptions
removed. - Arguments
tokenAudience
andtokenOrganization
added as optional, nullable arrays. - Argument
tokenNonce
added as an optional string. - Arguments
tokenMaxAge
,tokenLeeway
, andtokenNow
were added as optional, nullable integers. - Now returns an instance of
Auth0\SDK\Token
instead of an array.
- Argument
- Public methods
getAuthorizationCode()
andgetState()
were removed; please usegetRequestParameter()
method. - Public method
deleteAllPersistentData()
renamed toclear()
. - Public methods
getNonce()
andurlSafeBase64Decode()
were removed. - Public methods
getAccessTokenExpiration()
andsetAccessTokenExpiration()
were added for retrieving for storing an access token expiration timestamp in session storage, respectively. - Public methods
getUser()
,getAccessToken()
,getIdToken()
andgetRefreshToken()
no longer implicitly invokeexchange()
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 callAuth0::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 anSdkConfiguration
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 togetLoginLink()
, 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 optionalstate
argument is now required.
- Method now accepts an argument,
- Public method
get_samlp_link()
renamed togetSamlpLink()
, and:- Argument
client_id
renamed toclientId
.
- Argument
- Public method
get_samlp_metadata_link()
renamed togetSamlpMetadataLink()
, and:- Argument
client_id
renamed toclientId
.
- Argument
- Public method
get_wsfed_link()
renamed togetWsfedLink()
, and:- Argument
client_id
renamed toclientId
.
- Argument
- Public method
get_wsfed_metadata_link()
renamed togetWsfedMetadataLink()
. - Public method
get_logout_link()
renamed togetLogoutLink()
, and:- Argument
returnTo
renamed toreturnUri
. - Arguments
client_id
andfederated
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.
- Argument
- Public method
passwordlessStart()
added. - Public method
email_passwordless_start()
renamed toemailPasswordlessStart()
, 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 newheaders
argument with an 'AUTH0_FORWARDED_FOR' key-value pair for this behavior. - Now returns a PSR-7 ResponseInterface, instead of an array.
- Argument
- Public method
sms_passwordless_start()
renamed tosmsPasswordlessStart()
, and:- Argument
phone_number
renamed tophoneNumber
. - Argument
headers
added to specify additional headers to pass with the request. - Argument
forwarded_for
removed. Use the newheaders
argument with an 'AUTH0_FORWARDED_FOR' key-value pair for this behavior. - Now returns a PSR-7 ResponseInterface, instead of an array.
- Argument
- Public method
userinfo()
renamed touserInfo()
, and:- Argument
access_token
renamed toaccessToken
. - Now returns a PSR-7 ResponseInterface, instead of an array.
- Argument
- Public method
oauth_token()
renamed tooauthToken()
, and:- Argument
grantType
added. It requires a string. - Arguments
headers
andparams
were added as optional, nullable arrays. - Argument
options
removed. Use the newheaders
andparams
arguments for these functions. - Now returns a PSR-7 ResponseInterface, instead of an array.
- Argument
- Public method
code_exchange()
renamed tocodeExchange()
, and:- Argument
redirect_uri
renamed toreturnUri
. - Argument
code_verifier
renamed tocodeVerifier
. - Now returns a PSR-7 ResponseInterface, instead of an array.
- Argument
- Public method
login()
updated:- Arguments
username
,password,
andrealm
added as required strings. - Arguments
headers
andparams
were added as optional, nullable arrays. - Argument
ip_address
removed. Use the newheaders
argument with an 'AUTH0_FORWARDED_FOR' key-value pair for this behavior. - Argument
options
removed. Use the newheaders
andparams
arguments for these functions. - Now returns a PSR-7 ResponseInterface, instead of an array.
- Arguments
- Public method
login_with_default_directory()
renamed tologinWithDefaultDirectory()
, and:- Arguments
username
andpassword
added as required strings. - Arguments
headers
andparams
were added as optional, nullable arrays. - Argument
ip_address
removed. Use the newheaders
argument with an 'AUTH0_FORWARDED_FOR' key-value pair for this behavior. - Argument
options
removed. Use the newheaders
andparams
arguments for these functions. - Now returns a PSR-7 ResponseInterface, instead of an array.
- Arguments
- Public method
client_credentials()
renamed toclientCredentials()
, and:- Arguments
headers
andparams
were added as optional, nullable arrays. - Argument
options
removed. Use the newheaders
andparams
arguments for these functions. - Now returns a PSR-7 ResponseInterface, instead of an array.
- Arguments
- Public method
refresh_token()
renamed torefreshToken()
, and:- Argument
refresh_token
renamed torefreshToken
. - Arguments
headers
andparams
were added as optional, nullable arrays. - Argument
options
removed. Use the newheaders
andparams
arguments for these functions. - Now returns a PSR-7 ResponseInterface, instead of an array.
- Argument
- Public method
dbconnections_signup()
renamed todbConnectionsSignup()
, and:- Arguments
body
andheaders
added as optional, nullable arrays. - Now returns a PSR-7 ResponseInterface, instead of an array.
- Arguments
- Public method
dbconnections_change_password()
changed todbConnectionsChangePassword()
, and:- Arguments
body
andheaders
added as optional, nullable arrays. - Argument
password
removed. Use the newbody
argument for this behavior.
- Arguments
-
Class
Auth0\SDK\API\Management
updated:__construct
updated:configuration
added as a required instance of either anSdkConfiguration
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 togetSettings
. - Public method
update
renamed toupdateSettings
.
- Public method
-
Class
Auth0\SDK\API\Management\GenericResource
renamed toAuth0\SDK\API\Management\ManagementEndpoint
, and:- Constructor updated to require an
HttpClient
instance; previously expected anApiClient
instance. - Public method
getApiClient()
renamed togetHttpClient()
. - Public method
getLastRequest()
added. - Public methods
normalizeRequest()
,normalizePagination()
,normalizeIncludeTotals()
, andnormalizeIncludeFields()
were removed, and:- Their functionality has been rolled into the new
Auth0\SDK\Utility\Request\RequestOptions
,Auth0\SDK\Utility\Request\FilteredRequest
, andAuth0\SDK\Utility\Request\PaginatedRequest
utility classes.
- Their functionality has been rolled into the new
- Public methods
checkInvalidPermissions()
,checkEmptyOrInvalidString()
, andcheckEmptyOrInvalidArray()
were removed, and:- Their functionality has been rolled into the new
Auth0\SDK\Utility\Validate
utility class.
- Their functionality has been rolled into the new
- Constructor updated to require an
-
Class
Auth0\SDK\Store\StoreInterface
moved toAuth0\SDK\Contract\StoreInterface
. -
Class
Auth0\SDK\Exception\CoreException
moved toAuth0\SDK\Contract\SdkException
. -
Class
Auth0\SDK\Helpers\PKCE
moved toAuth0\SDK\Utility\PKCE
. -
Class
Auth0\SDK\Helpers\TransientStoreHandler
moved toAuth0\SDK\Utility\TransientStoreHandler
.
-
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
.
- Class
-
All
Auth0\SDK\API\Helpers
classes:- Class
Auth0\SDK\API\Helpers\ApiClient
superseded byAuth0\SDK\Utility\HttpClient
. - Class
Auth0\SDK\API\Helpers\RequestBuilder
superseded byAuth0\SDK\Utility\HttpRequest
. - Class
Auth0\SDK\API\Helpers\InformationHeaders
superseded byAuth0\SDK\Utility\HttpTelemetry
.
- Class
-
All token-related classes have been replaced by the new
Auth0\SDK\Token
,Auth0\SDK\Token\Parser
,Auth0\SDK\Token\Validator
, andAuth0\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
-
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.
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
.
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();
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.
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();
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.
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.
}
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..
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.';
HttpResponsePaginator
does not currently support checkpoint pagination. This will be introduced in a later release.
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.
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.
The v7 release requires PHP 7.1 or later to enable a number of helpful features like type hinting and null coalescing.
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 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.
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
.
The following classes were removed in v7:
- Class
Firebase\JWT\JWT
provided by thefirebase/php-jwt
package was replaced with classes from thelcobucci/jwt
package - Class
JWTVerifier
was removed, see theAuth0->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
The following class constructors were changed in v7:
- Class
Authentication
now requires aclient_id
parameter - Class
NoCacheHandler
now implementsPsr\SimpleCache\CacheInterface
- Class
JWKFetcher
now requires an instance ofPsr\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 toAuth0\SDK\API\Header\AuthorizationBearer
The following methods were changed in a breaking way in v7:
- Public method
RequestBuilder->withHeader()
now only accepts aHeader
instance as an argument. - Public method
Authentication->code_exchange()
now throws anApiException
if class-levelclient_secret
is empty - Public method
Authentication->client_credentials()
now throws anApiException
ifaudience
is empty - Public method
Authentication->get_authorize_link()
now adds class-levelscope
andaudience
if none are passed in
The following methods were removed in v7:
- Public magic method
ApiClient->__call()
was removed, useApiClient->method()
to indicate an HTTP verb to use - Public magic method
RequestBuilder->__call()
was removed, useRequestBuilder->addPath()
to add paths - Public method
RequestBuilder->addPathVariable()
was removed, useRequestBuilder->addPath()
to add paths - Public method
RequestBuilder->dump()
was removed, no replacement provided - Public method
RequestBuilder->withParams()
was removed, useRequestBuilder->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, useUsers->getAll()
instead - Public method
Users->unlinkDevice()
was removed, no replacement provided - Public method
JWKFetcher->requestJwkX5c()
was removed, useJWKFetcher->getKeys()
instead - Public method
JWKFetcher->findJwk()
was removed, useJWKFetcher->getKeys()
instead - Public method
JWKFetcher->subArrayHasEmptyFirstItem()
was removed, no replacement provided - Public method
JWKFetcher->fetchKeys()
was removed, useJWKFetcher->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
The following properties were removed in v7:
- Public property
Management->blacklists
was made private, replaced byManagement->blacklists()
- Public property
Management->clients
was made private, replaced byManagement->clients()
- Public property
Management->client_grants
was made private, replaced byManagement->clientGrants()
- Public property
Management->connections
was made private, replaced byManagement-> connections()
- Public property
Management->deviceCredentials
was made private, replaced byManagement->deviceCredentials()
- Public property
Management->emails
was made private, replaced byManagement->emails()
- Public property
Management->emailTemplates
was made private, replaced byManagement->emailTemplates()
- Public property
Management->grants
was made private, replaced byManagement->grants()
- Public property
Management->jobs
was made private, replaced byManagement->jobs()
- Public property
Management->logs
was made private, replaced byManagement->logs()
- Public property
Management->roles
was made private, replaced byManagement->roles()
- Public property
Management->rules
was made private, replaced byManagement->rules()
- Public property
Management->resource_servers
was made private, replaced byManagement->resourceServers()
- Public property
Management->stats
was made private, replaced byManagement->stats()
- Public property
Management->tenants
was made private, replaced byManagement->tenants()
- Public property
Management->tickets
was made private, replaced byManagement->tickets()
- Public property
Management->userBlocks
was made private, replaced byManagement->userBlocks()
- Public property
Management->users
was made private, replaced byManagement->users()
- Public property
Management->usersByEmail
was made private, replaced byManagement->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