Sign up for an{" "}
Auth0 account
{" "}
or{" "}
console.log("log in")}>
log in
{" "}
to your existing account to integrate directly with your own tenant.
;
};
export const sections = [{
id: "laravel-installation",
title: "Laravel Installation"
}, {
id: "sdk-installation",
title: "SDK Installation"
}, {
id: "sdk-configuration",
title: "SDK Configuration"
}, {
id: "login-routes",
title: "Login Routes"
}, {
id: "access-control",
title: "Access Control"
}, {
id: "user-information",
title: "User Information"
}, {
id: "user-management",
title: "User Management"
}, {
id: "run-the-application",
title: "Run the Application"
}];
[Auth0's Laravel SDK](https://github.com/auth0/laravel-auth0)
allows you to quickly add authentication, user profile management, and routing access control to your Laravel
application. This guide demonstrates how to integrate Auth0 with a new (or existing) [Laravel 9
or 10](https://github.com/auth0/laravel-auth0#support-policy) application.
Test Change
**If you do not already have a Laravel application set up**, open a shell to a suitable directory for a new
project and run the following command:
```sh wrap lines
composer create-project --prefer-dist laravel/laravel auth0-laravel-app ^9.0
```
All the commands in this guide assume you are running them from the root of your Laravel project, directory so
you should `cd` into the new project directory:
```sh lines
cd auth0-laravel-app
```
Run the following command within your project directory to install the [Auth0 Laravel SDK](https://github.com/auth0/laravel-auth0):
```sh wrap lines
composer require auth0/login:^7.8 --update-with-all-dependencies
```
Then generate an SDK configuration file for your application:
```sh lines
php artisan vendor:publish --tag auth0
```
Run the following command from your project directory to download the Auth0 CLI:
```sh wrap lines
curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b .
```
Then authenticate the CLI with your Auth0 account, choosing "as a user" when prompted:
```sh lines
./auth0 login
```
Next, create a new application with Auth0:
```sh lines
./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
```
You should also create a new API:
```sh lines
./auth0 apis create \
--name "My Laravel Application's API" \
--identifier "https://github.com/auth0/laravel-auth0" \
--offline-access \
--no-input \
--json > .auth0.api.json
```
This produces two files in your project directory that configure the SDK.
As these files contain credentials it's important to treat these as sensitive. You should ensure you do not
commit these to version control. If you're using Git, you should add them to your `.gitignore` file:
```sh lines
echo ".auth0.*.json" >> .gitignore
```
The SDK automatically registers all the necessary routes for your application's users to authenticate.
If you require more control over these, or if they conflict with existing routes in your application, you can
manually register the SDK's controllers instead. Please see [the SDK's README](https://github.com/auth0/laravel-auth0) for advanced integrations.
Laravel's authentication facilities use "guards" to define how users are authenticated for each request. You can
use the Auth0 SDK's authentication guard to restrict access to your application's routes.
To require users to authenticate before accessing a route, you can use Laravel's `auth` middleware.
```text lines
Route::get('/private', function () {
return response('Welcome! You are logged in.');
})->middleware('auth');
```
You can also require authenticated users to have specific [permissions](https://auth0.com/docs/manage-users/access-control/rbac) by combining this
with Laravel's `can` middleware.
```text lines
Route::get('/scope', function () {
return response('You have `read:messages` permission, and can therefore access this resource.');
})->middleware('auth')->can('read:messages');
```
Information about the authenticated user is available through Laravel's `Auth` Facade, or the
`auth()` helper function.
For example, to retrieve the user's identifier and email address:
```text lines
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}.");
});;
```
You can update user information using the [Auth0 Management API](https://github.com/auth0/laravel-auth0/blob/main/docs/Management.md). All Management endpoints are accessible through the SDK's
`management()` method.
**Before making Management API calls you must enable your application to communicate with the Management
API.** This can be done from the [Auth0 Dashboard's API page](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq/apis/), choosing
`Auth0 Management API`, and selecting the 'Machine to Machine Applications' tab. Authorize your Laravel
application, and then click the down arrow to choose the scopes you wish to grant.
For the following example, in which we will update a user's metadata and assign a random favorite color, you
should grant the `read:users` and `update:users` scopes. A list of API endpoints and the
required scopes can be found in [the Management
API documentation](https://auth0.com/docs/api/management/v2).
```text lines
use Auth0\Laravel\Facade\Auth0;
Route::get('/colors', function () {
$endpoint = Auth0::management()->users();
$colors = ['red', 'blue', 'green', 'black', 'white', 'yellow', 'purple', 'orange', 'pink', 'brown'];
$endpoint->update(
id: auth()->id(),
body: [
'user_metadata' => [
'color' => $colors[random_int(0, count($colors) - 1)]
]
]
);
$metadata = $endpoint->get(auth()->id());
$metadata = Auth0::json($metadata);
$color = $metadata['user_metadata']['color'] ?? 'unknown';
$name = auth()->user()->name;
return response("Hello {$name}! Your favorite color is {$color}.");
})->middleware('auth');
```
A quick reference guide of all the SDK's Management API methods is [available here](https://github.com/auth0/laravel-auth0/blob/main/docs/Management.md).
You are now ready to start your Laravel application, so it can accept requests:
```text lines
php artisan serve
```
##### Checkpoint
Open your web browser and try accessing the following routes:
* [http://localhost:8000](http://localhost:8000/)
to see the public route.
* [http://localhost:8000/private](http://localhost:8000/private) to be prompted to authenticate.
* [http://localhost:8000](http://localhost:8000/)
to see the public route, now authenticated.
* [http://localhost:8000/scope](http://localhost:8000/scope) to check if you have the
`read:messages`[permission](https://auth0.com/docs/manage-users/access-control/rbac).
* [http://localhost:8000/update](http://localhost:8000/update) to update the user's profile.
* [http://localhost:8000/logout](http://localhost:8000/logout) to log out.
### Additional Reading
* [User Repositories and Models](https://github.com/auth0/laravel-auth0/blob/main/docs/Users.md) extends the Auth0 Laravel SDK to use custom user
models, and how to store and retrieve users from a database.
* [Hooking Events](https://github.com/auth0/laravel-auth0/blob/main/docs/Events.md) covers how to listen for events raised by the Auth0 Laravel
SDK, to fully customize the behavior of your integration.
* [Management API](https://github.com/auth0/laravel-auth0/blob/main/docs/Management.md) support is built into the Auth0 Laravel SDK, allowing you to
interact with the Management API from your Laravel application.
## Next Steps
Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.
This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:
* [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
* [laravel-auth0 SDK](https://github.com/auth0/laravel-auth0) - Explore the SDK used in this tutorial more fully
* [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
```php web.php highlight={6-12} lines
middleware('auth');
Route::get('/scope', function () {
return response('You have `read:messages` permission, and can therefore access this resource.');
})->middleware('auth')->can('read:messages');
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}.");
});
Route::get('/colors', function () {
$endpoint = Auth0::management()->users();
$colors = ['red', 'blue', 'green', 'black', 'white', 'yellow', 'purple', 'orange', 'pink', 'brown'];
$endpoint->update(
id: auth()->id(),
body: [
'user_metadata' => [
'color' => $colors[random_int(0, count($colors) - 1)]
]
]
);
$metadata = $endpoint->get(auth()->id()); // Retrieve the user's metadata.
$metadata = Auth0::json($metadata); // Convert the JSON to a PHP array.
$color = $metadata['user_metadata']['color'] ?? 'unknown';
$name = auth()->user()->name;
return response("Hello {$name}! Your favorite color is {$color}.");
})->middleware('auth');
```
```php web.php highlight={14-24} lines
middleware('auth');
Route::get('/scope', function () {
return response('You have `read:messages` permission, and can therefore access this resource.');
})->middleware('auth')->can('read:messages');
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}.");
});
Route::get('/colors', function () {
$endpoint = Auth0::management()->users();
$colors = ['red', 'blue', 'green', 'black', 'white', 'yellow', 'purple', 'orange', 'pink', 'brown'];
$endpoint->update(
id: auth()->id(),
body: [
'user_metadata' => [
'color' => $colors[random_int(0, count($colors) - 1)]
]
]
);
$metadata = $endpoint->get(auth()->id()); // Retrieve the user's metadata.
$metadata = Auth0::json($metadata); // Convert the JSON to a PHP array.
$color = $metadata['user_metadata']['color'] ?? 'unknown';
$name = auth()->user()->name;
return response("Hello {$name}! Your favorite color is {$color}.");
})->middleware('auth');
```
```php web.php highlight={26-43} lines
middleware('auth');
Route::get('/scope', function () {
return response('You have `read:messages` permission, and can therefore access this resource.');
})->middleware('auth')->can('read:messages');
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}.");
});
Route::get('/colors', function () {
$endpoint = Auth0::management()->users();
$colors = ['red', 'blue', 'green', 'black', 'white', 'yellow', 'purple', 'orange', 'pink', 'brown'];
$endpoint->update(
id: auth()->id(),
body: [
'user_metadata' => [
'color' => $colors[random_int(0, count($colors) - 1)]
]
]
);
$metadata = $endpoint->get(auth()->id()); // Retrieve the user's metadata.
$metadata = Auth0::json($metadata); // Convert the JSON to a PHP array.
$color = $metadata['user_metadata']['color'] ?? 'unknown';
$name = auth()->user()->name;
return response("Hello {$name}! Your favorite color is {$color}.");
})->middleware('auth');
```
Sign up for an{" "}
Auth0 account
{" "}
or{" "}
console.log("log in")}>
log in
{" "}
to your existing account to integrate directly with your own tenant.