auth0/laravel-auth0

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.

• Requirements
• Getting Started
  • 1. Install the SDK
  • 2. Install the CLI
  • 3. Configure the SDK
  • 4. Run the Application
• Documentation
• QuickStarts
• Contributing
• Code of Conduct
• Security
• License

Requirements

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.

You will also need Composer and an Auth0 account.

Getting Started

The following is our recommended approach to getting started with the SDK. Alternatives are available in our expanded installation guide.

1. Install the SDK

• 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

2. Install the CLI

1. 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`.

   Using Homebrew (macOS)

    

   brew tap auth0/auth0-cli && brew install auth0

   Using Scoop (Windows)

    

   scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
   scoop install auth0

2. Authenticate the CLI with your Auth0 account. Choose "as a user" if prompted.

   auth0 login

3. Configure the SDK

1. 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

2. 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

3. Add the new files to .gitignore.

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

   Using Windows PowerShell

    

   Add-Content .gitignore "`n.auth0.*.json"

   Using Windows Command Prompt

    

   echo .auth0.*.json >> .gitignore

4. Run the Application

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.

  Using Windows PowerShell

   

  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.

Integration Examples

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

Route::get('/api/private', function () {
  return response()->json(['message' => 'Hello! You included a valid token with your request.']);
})->middleware('auth');

Route::get('/scope', function () {
    return response('You have the `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('/', 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(),
  ]);
});

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

Documentation

• Installation — Installing the SDK and generating configuration files.
• Configuration — Configuring the SDK using JSON files or environment variables.
• Sessions — Guidance on deciding which Laravel Session API driver to use.
• Cookies — Important notes about using Laravel's Cookie session driver, and alternative options.
• Management API — Using the SDK to work with the Auth0 Management API.
• Users — Extending the SDK to support persistent storage and Eloquent models.
• Events — Hooking into SDK events to respond to specific actions.
• Deployment — Deploying your application to production.

You may find the following integration guidance useful:

• Laravel Eloquent — Eloquent ORM is supported.
• Laravel Octane — Octane is not supported at this time.
• Laravel Telescope — Telescope is compatible as of SDK v7.11.0.

You may also find the following resources helpful:

• Auth0 Documentation Hub
• Auth0 Management API Explorer
• Auth0 Authentication API Explorer

Contributions to improve our documentation are welcomed.

QuickStarts

• Session-based Authentication (GitHub)
• Token-based Authorization (GitHub)

Community

The Auth0 Community is where you can get support, ask questions, and share your projects.

Contributing

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.

Code of Conduct

Participants are expected to adhere to Auth0's Code of Conduct when interacting with this project.

Security

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.

License

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?"