Stars: 224
Forks: 126
Pull Requests: 245
Issues: 181
Watchers: 65
Last Updated: 2023-08-31 17:43:30
Laravel SDK for Auth0 Authentication and Management APIs.
License: MIT License
Languages: PHP
The Auth0 Laravel SDK is a PHP package that integrates Auth0 into your Laravel application. It includes no-code user authentication, extensive Management API support, permissions-based routing access control, and more.
Your application must use a supported Laravel version, and your host environment must be running a supported PHP version. Please review our support policy for more information.
SDK | Laravel | PHP | Supported Until |
---|---|---|---|
7.5+ | 10.x | 8.2+ | Feb 2025 |
8.1+ | Nov 2024 | ||
7.0+ | 9.x | 8.2+ | Feb 2024 |
8.1+ | Feb 2024 | ||
8.0+ | Nov 2023 |
You will also need Composer and an Auth0 account.
The following is our recommended approach to getting started with the SDK. Alternatives are available in our expanded installation guide.
For new applications, we offer a quickstart template — a version of the default Laravel 9 starter project pre-configured for use with the Auth0 SDK.
composer create-project auth0-samples/laravel auth0-laravel-app && cd auth0-laravel-app
For existing applications, you can install the SDK using Composer.
composer require auth0/login:^7.9 --update-with-all-dependencies
In this case, you will also need to generate an SDK configuration file for your application.
php artisan vendor:publish --tag auth0
Install the Auth0 CLI to manage your account from the command line.
curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b .
Move the CLI to a directory in your PATH
to make it available system-wide.
sudo mv ./auth0 /usr/local/bin
💡 If you prefer not to move the CLI, simply substitute `auth0` in the CLI steps below with `./auth0`.
brew tap auth0/auth0-cli && brew install auth0
scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
scoop install auth0
Authenticate the CLI with your Auth0 account. Choose "as a user" if prompted.
auth0 login
Register a new application with Auth0.
auth0 apps create \
--name "My Laravel Application" \
--type "regular" \
--auth-method "post" \
--callbacks "http://localhost:8000/callback" \
--logout-urls "http://localhost:8000" \
--reveal-secrets \
--no-input \
--json > .auth0.app.json
Register a new API with Auth0.
auth0 apis create \
--name "My Laravel Application API" \
--identifier "https://github.com/auth0/laravel-auth0" \
--offline-access \
--no-input \
--json > .auth0.api.json
Add the new files to .gitignore
.
echo ".auth0.*.json" >> .gitignore
Add-Content .gitignore "`n.auth0.*.json"
echo .auth0.*.json >> .gitignore
Boot the application using PHP's built-in web server.
php artisan serve
Direct your browser to http://localhost:8000 to experiment with the application.
Authentication
Users can log in or out of the application by visiting the /login
or /logout
routes, respectively.
API Authorization
For simplicity sake, generate a test token using the CLI.
auth0 test token \
--audience %IDENTIFIER% \
--scopes "read:messages"
✋ Substitute %IDENTIFIER%
with the identifier of the API you created in step 3 above.
Now you can send requests to the /api
endpoints of the application, including the token as a header.
curl --request GET \
--url http://localhost:8000/api/example \
--header 'Accept: application/json' \
--header 'Authorization: Bearer %TOKEN%'
✋ Substitute %TOKEN%
with the test token returned in the previous step.
Invoke-WebRequest http://localhost:8000/api/example `
-Headers @{'Accept' = 'application/json'; 'Authorization' = 'Bearer %TOKEN%'}
When you're ready to deploy your application to production, review our deployment guide for best practices and advice on securing Laravel.
The SDK automatically registers all the necessary routes and authentication services within the web
middleware group of your application to enable users to authenticate without requiring you to write any code.
Route | Purpose |
---|---|
/login |
Initiates the authentication flow. |
/logout |
Logs the user out. |
/callback |
Handles the callback from Auth0. |
If these routes conflict with your application architecture, you can override this default behavior by adjusting the SDK configuration.
The SDK automatically registers its authentication and authorization guards within the web
and api
middleware groups for your Laravel application, respectively.
For web
routes, you can use Laravel's auth
middleware to require that a user be authenticated to access a route.
Route::get('/private', function () {
return response('Welcome! You are logged in.');
})->middleware('auth');
For api
routes, you can use Laravel's auth
middleware to require that a request be authenticated with a valid bearer token to access a route.
Route::get('/api/private', function () {
return response()->json(['message' => 'Hello! You included a valid token with your request.']);
})->middleware('auth');
In addition to requiring that a user be authenticated, you can also require that the user have specific permissions to access a route, using Laravel's can
middleware.
Route::get('/scope', function () {
return response('You have the `read:messages` permission, and can therefore access this resource.');
})->middleware('auth')->can('read:messages');
Permissions require that RBAC be enabled within your API settings.
Laravel's Auth
Facade can be used to retrieve information about the authenticated user or token associated with a request.
For routes using the web
middleware group in routes/web.php
.
Route::get('/', function () {
if (! auth()->check()) {
return response('You are not logged in.');
}
$user = auth()->user();
$name = $user->name ?? 'User';
$email = $user->email ?? '';
return response("Hello {$name}! Your email address is {$email}.");
});
For routes using the api
middleware group in routes/api.php
.
Route::get('/', function () {
if (! auth()->check()) {
return response()->json([
'message' => 'You did not provide a token.',
]);
}
return response()->json([
'message' => 'Your token is valid; you are authorized.',
'id' => auth()->id(),
'token' => auth()?->user()?->getAttributes(),
]);
});
Once you've authorized your application to make Management API calls, you'll be able to engage nearly any of the Auth0 Management API endpoints through the SDK.
Each API endpoint has its own SDK class which can be accessed through the Facade's management()
factory method. For interoperability, network responses from the API are returned as PSR-7 messages. These can be converted into native arrays using the SDK's json()
method.
For example, to update a user's metadata, you can call the management()->users()->update()
method.
use Auth0\Laravel\Facade\Auth0;
Route::get('/colors', function () {
$colors = ['red', 'blue', 'green', 'black', 'white', 'yellow', 'purple', 'orange', 'pink', 'brown'];
// Update the authenticated user with a randomly assigned favorite color.
Auth0::management()->users()->update(
id: auth()->id(),
body: [
'user_metadata' => [
'color' => $colors[random_int(0, count($colors) - 1)]
]
]
);
// Retrieve the user's updated profile.
$profile = Auth0::management()->users()->get(auth()->id());
// Convert the PSR-7 response into a native array.
$profile = Auth0::json($profile);
// Extract some values from the user's profile.
$color = $profile['user_metadata']['color'] ?? 'unknown';
$name = auth()->user()->name;
return response("Hello {$name}! Your favorite color is {$color}.");
})->middleware('auth');
All the SDK's Management API methods are documented here.
You may find the following integration guidance useful:
You may also find the following resources helpful:
Contributions to improve our documentation are welcomed.
The Auth0 Community is where you can get support, ask questions, and share your projects.
We appreciate feedback and contributions to this library. Before you get started, please review Auth0's General Contribution guidelines.
The Contribution Guide contains information about our development process and expectations, insight into how to propose bug fixes and improvements, and instructions on how to build and test changes to the library.
To provide feedback or report a bug, please raise an issue.
Participants are expected to adhere to Auth0's Code of Conduct when interacting with this project.
If you believe you have found a security vulnerability, we encourage you to responsibly disclose this and not open a public issue. We will investigate all reports. The Responsible Disclosure Program details the procedure for disclosing security issues.
This library is open-sourced software licensed under the MIT license.
Auth0 is an easy-to-implement, adaptable authentication and authorization platform.
To learn more, check out "Why Auth0?"