Laravel SDK for Auth0 Authentication and Management APIs.

📚 Documentation - 🚀 Getting Started - 💬 Feedback

• Quickstarts
  • Authentication using Sessions (GitHub) — An application that uses sessions and supports logging in, logging out, and querying user profiles.
  • Authorization using Tokens (GitHub) — A backend API service that authorizes requests using tokens from a frontend application.
• Documentation
  • Events — Hooking into events raised by the SDK to customize behavior.
  • Management API — Making API calls to Auth0 Management API endpoints.
  • User Models and Repositories — Extending the SDK to support database storage, Eloquent, and other scenarios.
  • Examples — Solutions for other common scenarios and questions.
• Documentation Hub — Learn more about integrating Auth0.

You will need to use a supported version of PHP and Laravel:

You'll also need an Auth0 account, as well as Composer and the Auth0 CLI.

Run the following command within your project directory to install the Auth0 Laravel SDK:

composer require auth0/login:^7.8 --update-with-all-dependencies

Then generate an SDK configuration file for your application:

php artisan vendor:publish --tag auth0

Note If you prefer to use environment variables to configure the SDK, please see docs/Installation for guidance.

Run the following command from your project directory to download the Auth0 CLI:

curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b .

Then authenticate the CLI with your Auth0 account:

./auth0 login

Next, create 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

You should also create a new API:

./auth0 apis create \
  --name "My Laravel Application 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:

echo ".auth0.*.json" >> .gitignore

The SDK automatically registers all the necessary facilities within the web middleware group for your users to authenticate with your application. These routes are:

See docs/Configuration for guidance on disabling automatic registration, and manually registering these facilities.

The SDK automatically registers its authentication and authorization guards into the standard web and api middleware for your Laravel application, respectively.

See docs/Configuration for guidance on disabling this automatic registration, and manually registering the guards.

You can use the Auth0 SDK's authentication guard to restrict access to your application's routes.

To require the requesting party to be authenticated (routes using the web middleware defined in routes/web.php) or authorized (routes using the api middleware defined in routes/api.php), you can use Laravel's auth middleware:

Route::get('/private', function () {
  return response('Welcome! You are logged in.');
})->middleware('auth');

You can also require the requestor have specific permissions by combining this with Laravel's can middleware:

Route::get('/scope', function () {
    return response('You have the `read:messages` permissions, and can therefore access this resource.');
})->middleware('auth')->can('read:messages');

Note Permissions need RBAC to be enabled on your Auth0 API's settings.

When requests are made to your application, the SDK will automatically attempt to authenticate or authorize the requestor, depending on the type of route. Information about the requesting party is expressed through the user() method of Laravel's Auth Facade, or the auth() helper function.

For routes using the web middleware defined in routes/web.php, the user() method will return profile information for the authenticated user.

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 defined in routes/api.php, the user() method will return details about the access token.

Route::get('/', function () {
  if (! auth()->check()) {
    return response()->json([
      'message' => 'You did not provide a valid token.',
    ]);
  }

  return response()->json([
    'message' => 'Your token is valid; you are authorized.',
    'id' => auth()->id(),
    'token' => auth()?->user()?->getAttributes(),
  ]);
});

You can update user information using the Auth0 Management API. 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, 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.

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.

The SDK supports Laravel's Authorization API and provides several convenient pre-built Gates for common tasks.

Using these gates, you can easily authorize users or access tokens to perform actions in your application. Your application can use Laravel's Policies API in combination with these gates to further simplify authorization.

Our support lifecycle mirrors the Laravel release support and PHP release support schedules.

We drop support for Laravel and PHP versions when they reach end-of-life and cease receiving security fixes from Laravel and the PHP Foundation, whichever comes first. Please ensure your environment remains up to date so you can continue receiving updates for Laravel, PHP, and this SDK.

Octane compatibility is currently considered experimental and unsupported.

Although we are working toward ensuring the SDK is fully compatible with this feature, we do not recommend using this with our SDK in production until we have full confidence and announced support. Due to the caching behavior of Octane, there is an opportunity for problems we have not fully identified or resolved yet.

Feedback and bug-fix contributions are greatly appreciated as we work toward full support.

We appreciate feedback and contribution to this repo! Before you get started, please see the following:

• Auth0's general contribution guidelines
• Auth0's code of conduct guidelines

To provide feedback or report a bug, please raise an issue on our issue tracker.

Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

Auth0 is an easy-to-implement, adaptable authentication and authorization platform.
To learn more, check out "Why Auth0?"

This project is licensed under the MIT license. See the LICENSE file for more info.