auth0/login

Auth0 Laravel SDK. Straight-forward and tested methods for implementing authentication, and accessing Auth0's Management API endpoints.


README

Build Status Latest Stable Version Latest Version Supported PHP Versions License FOSSA Status

This SDK helps you integrate your Laravel application with Auth0 to achieve single sign-on with a few simple steps. The SDK also provides an easy method of integration all the functionality of the underlying Auth0-PHP inside your Laravel application, including all types of authentication, authorization of API endpoints, and issuing Management API calls.

Requirements

Laravel Version PHP Version¹ SDK Version Laravel Version Support Ends²
9.0 ≥ 8.0 ≥ 7.0 February 2024
8.0 7.4³, ≥ 8.0 ≥ 6.0 January 2023
6.0 (LTS) 7.4³, ≥ 8.0 6.0 September 2022

¹ This library follows the PHP release support schedule. We do not support PHP versions after they reach end of life.

² This library follows the Laravel release support schedule. We do not support Laravel framework versions after they reach end of life.

³ PHP 7 will reach its end of life in November 2022. Please upgrade to PHP 8.

Usage

Getting Started

Installation

The supported method of SDK installation is through Composer. From your terminal shell, cd into your project directory and issue the following command:

composer require auth0/login:dev-main

Configuration the SDK

Use the Laravel vendor:publish command to import the configuration file into your application:

php artisan vendor:publish --tag=auth0-config

Now edit your .env file and add Auth0 tenants details for your project, depending on the type of application you're building:

Regular Web Applications

# The URL of your Auth0 tenant domain
# You'll find this in your Auth0 Application's settings page.
AUTH0_DOMAIN=...

# Your Auth0 application's Client ID
# You'll find this in your Auth0 Application's settings page.
AUTH0_CLIENT_ID=...

# Your Auth0 application's Client ID
# You'll find this in your Auth0 Application's settings page.
AUTH0_CLIENT_SECRET=...

# Your Auth0 Custom API identifier/audience.
# You'll find this in your Custom API's settings page.
AUTH0_AUDIENCE=...

# Authentication callback URI, as defined in your Auth0 Application settings.
# (Update this as appropriate for your application's location.)
# (You must configure this in your Auth0 Application's settings page as well!)
AUTH0_REDIRECT_URI=http://localhost:3000/auth0/callback

Backend API Applications

These are applications that accept an Access Token through the 'Authorization' header of a request.

# This tells the Auth0 Laravel SDK about your use case to customize its behavior.
# The 'api' strategy is used for backend API applications like we're building here.
# See: https://github.com/auth0/auth0-PHP/blob/main/README.md#configuration-strategies
AUTH0_STRATEGY=api

# The URL of your Auth0 tenant domain
# You'll find this in your Auth0 Application's settings page.
AUTH0_DOMAIN=...

# Your Auth0 application's Client ID
# You'll find this in your Auth0 Application's settings page.
AUTH0_CLIENT_ID=...

# Your Auth0 Custom API identifier/audience.
# You'll find this in your Custom API's settings page.
AUTH0_AUDIENCE=...

Additional Options

The default configuration provided by the Auth0 Laravel SDK is intentionally limited and designed to support only the most common types of applications. More complex applications may require more robust configuration customizations available in the underlying Auth0-PHP SDK. You can add support for more configuration options by modifying your config/auth0.php and .env files. A complete list of configuration options are available from the Auth0-PHP SDK README.

Configure your Application

Integrating the SDK's Guard requires some small 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',
    ],
],

Finally, 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
    ],
],

Authentication Routes

The SDK offers a number of convenience route controllers to ease supporting authentication in regular web application (that is, an application that handles end users logging in and out).

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');

These routes will automatically handle your regular web application's authentication flow for you.

Protecting Routes with Middleware

The Auth0 Laravel SDK includes a number of middleware that simplify either authenticating (regular web applications) or authorizing (backend api applications) your Laravel routes, depending on the type of application you're building.

Regular Web Applications

These are for traditional applications that handle logging in and out.

The auth0.authenticate middleware will check for an available user session and redirect any requests without one to the login route:

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

The auth0.authenticate.optional middleware will check for an available user session, but won't reject or redirect requests without one, allowing you to treat such requests as "guest" requests:

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

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

Note that the example.user.template and example.guest.templates views are just examples and are not part of the SDK; replace these as appropriate for your app.

Backend API Applications

These are applications that accept an Access Token through the 'Authorization' header of a request.

The auth0.authorize middleware will resolve a Access Token and reject any request with an invalid token.

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']);

The auth0.authorize middleware also allows you to optionally filter requests for access tokens based on scopes:

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']);

The auth0.authorize.optional middleware will resolve an available Access Token, but won't block requests without one. This is useful when you want to treat tokenless requests as "guests":

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']);

Documentation

We provide a number of sample apps that demonstrate common use cases, to help you get started using this SDK:

Contributing

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

Support + Feedback

  • The Auth0 Community is a valuable resource for asking questions and finding answers, staffed by the Auth0 team and a community of enthusiastic developers
  • For code-level support (such as feature requests and bug reports), we encourage you to open issues here on our repo
  • For customers on paid plans, our support center is available for opening tickets with our knowledgeable support specialists

Further details about our support solutions are available on our website.

Vulnerability Reporting

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

What is Auth0?

Auth0 helps you to:

Why Auth0?

License

The Auth0 Laravel SDK is open source software licensed under the MIT license. See the LICENSE file for more info.

FOSSA Status