Laravel SDK for Auth0 Authentication and Management APIs.

📚 Documentation - 🚀 Getting Started - 💬 Feedback

• Stateful Applications
  • Quickstart — add login, logout, and user information to a Laravel application using Auth0.
  • Sample Application — a sample Laravel web application integrated with Auth0.
• Stateless Applications
  • Quickstart — add access token handling and route authorization to a backend Laravel application using Auth0.
  • Sample Application — a sample Laravel backend application integrated with Auth0.
• Examples — code samples for common scenarios.
• Docs site — explore our docs site and learn more about Auth0.

• Laravel 10 (PHP 8.1+) or Laravel 9 (PHP 8.0+)
• Composer
• PHP Extensions:
  • mbstring
• Dependencies:
  • PSR-18 HTTP Client implementation
  • PSR-17 HTTP Factory implementation
  • PSR-7 HTTP Messages implementation

Please review our support policy for details on our PHP and Laravel version support.

Octane support is experimental and not advisable for use in production at this time.

Ensure you have the necessary dependencies installed, then add the SDK to your application using Composer:

composer require auth0/login

Create a Regular Web Application in the Auth0 Dashboard. Verify that the "Token Endpoint Authentication Method" is set to POST.

Next, configure the callback and logout URLs for your application under the "Application URIs" section of the "Settings" page:

• Allowed Callback URLs: The URL of your application where Auth0 will redirect to during authentication, e.g., http://localhost:3000/callback.
• Allowed Logout URLs: The URL of your application where Auth0 will redirect to after logout, e.g., http://localhost:3000/login.

Note the Domain, Client ID, and Client Secret. These values will be used during configuration later.

Use Laravels CLI to generate an Auth0 configuration file within your project:

php artisan vendor:publish --tag auth0-config

A new file will appear within your project, app/config/auth0.php. You should avoid making changes to this file directly.

Open the .env file within your application's directory, and add the following lines appropriate for your application type:

AUTH0_DOMAIN="Your Auth0 domain"
AUTH0_CLIENT_ID="Your Auth0 application client ID"
AUTH0_CLIENT_SECRET="Your Auth0 application client secret"
AUTH0_COOKIE_SECRET="A randomly generated string"

AUTH0_STRATEGY="api"
AUTH0_DOMAIN="Your Auth0 domain"
AUTH0_CLIENT_ID="Your Auth0 application client ID"
AUTH0_CLIENT_SECRET="Your Auth0 application client secret"
AUTH0_AUDIENCE="Your Auth0 API identifier"

Integrating the SDK's Guard requires changes to your config\auth.php file.

To begin, find the defaults section. Set the default guard to auth0, like this:

// 📂 config/auth.php
'defaults' => [
    'guard' => 'auth0',
    // 📝 Leave any other settings in this section alone.
],

Next, find the guards section, and add auth0 there:

// 👆 Continued from above, in config/auth.php
'guards' => [
    // 📝 Any additional guards you use should stay here, too.
    'auth0' => [
        'driver' => 'auth0',
        'provider' => 'auth0',
    ],
],

Next, find the providers section, and add auth0 there as well:

// 👆 Continued from above, in config/auth.php
'providers' => [
    // 📝 Any additional providers you use should stay here, too.
    'auth0' => [
        'driver' => 'auth0',
        'repository' => \Auth0\Laravel\Auth\User\Repository::class
    ],
],

Although it is enabled by default, now is a good time to ensure the StartSession middleware is enabled in your app/Http/Kernel.php file:

protected $middlewareGroups = [
    'web' => [
        // ...
        \Illuminate\Session\Middleware\StartSession::class,
        // ...
    ],
];

For regular web applications that provide login and logout, we provide prebuilt route controllers to add to your app/routes/web.php file that will automatically handle your application's authentication flow with Auth0 for you:

Route::get('/login', \Auth0\Laravel\Http\Controller\Stateful\Login::class)->name('login');
Route::get('/logout', \Auth0\Laravel\Http\Controller\Stateful\Logout::class)->name('logout');
Route::get('/auth0/callback', \Auth0\Laravel\Http\Controller\Stateful\Callback::class)->name('auth0.callback');

This SDK includes middleware to simplify either authenticating (regular web applications) or authorizing (backend api applications) your Laravel routes, depending on your application type.

Route::get('/required', function () {
    return view('example.user.template');
})->middleware(['auth0.authenticate']);

Route::get('/', function () {
    if (Auth::check()) {
        return view('example.user.template');
    }

    return view('example.guest.template');
})->middleware(['auth0.authenticate.optional']);

Route::get('/api/private', function () {
    return response()->json([
        'message' => 'Hello from a private endpoint! You need to be authenticated to see this.',
        'authorized' => Auth::check(),
        'user' => Auth::check() ? json_decode(json_encode((array) Auth::user(), JSON_THROW_ON_ERROR), true) : null,
    ], 200, [], JSON_PRETTY_PRINT);
})->middleware(['auth0.authorize']);

Route::get('/api/private-scoped', function () {
    return response()->json([
        'message' => 'Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this.',
        'authorized' => Auth::check(),
        'user' => Auth::check() ? json_decode(json_encode((array) Auth::user(), JSON_THROW_ON_ERROR), true) : null,
    ], 200, [], JSON_PRETTY_PRINT);
})->middleware(['auth0.authorize:read:messages']);

Route::get('/api/public', function () {
    return response()->json([
        'message' => 'Hello from a public endpoint! You don\'t need to be authenticated to see this.',
        'authorized' => Auth::check(),
        'user' => Auth::check() ? json_decode(json_encode((array) Auth::user(), JSON_THROW_ON_ERROR), true) : null,
    ], 200, [], JSON_PRETTY_PRINT);
})->middleware(['auth0.authorize.optional']);

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 aggressive changes Octane makes to Laravel's core behavior, there is an opportunity for problems we haven't fully identified or resolved yet.

Feedback and bug fix contributions are greatly appreciated as we work toward full. Octane 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.