auth0-laravel

Auth0 Laravel Web 应用集成

使用 auth0/login（Laravel Auth0 SDK）为 Laravel Web 应用添加登录、登出和用户个人资料功能。

---

前提条件

• Laravel 11+ 应用
• PHP 8.2+，并启用扩展：mbstring、openssl、json
• 已安装 Composer
• 已配置 Auth0 Regular Web Application（不是 API，必须是 Application）
• 如果尚未设置 Auth0，请先使用 auth0-quickstart 技能

不适用场景

场景	请改用
使用 JWT Bearer 验证的 Laravel API	auth0-laravel-api（无状态令牌守卫）
纯 PHP（无框架）Web 应用	auth0-php
纯 PHP API	auth0-php-api
单页应用	auth0-react、auth0-vue 或 auth0-angular
Next.js 应用	auth0-nextjs
Node.js Web 应用	auth0-express 或 auth0-fastify
Flask Web 应用	auth0-flask

---

快速入门工作流

1. 安装 SDK

composer require auth0/login

auth0/login 软件包依赖 auth0/auth0-php（v8.19+），并会自动安装该依赖。它还需要 PSR-18 HTTP 客户端；如果尚未安装，请安装 Guzzle：

composer require guzzlehttp/guzzle guzzlehttp/psr7

2. 发布配置

php artisan vendor:publish --tag=auth0

这会创建 config/auth0.php，其中包含守卫、中间件和路由配置。

3. 配置环境

在 .env 中添加：

APP_URL=http://localhost:8000
AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_CLIENT_ID=your_client_id
AUTH0_CLIENT_SECRET=your_client_secret
AUTH0_AUDIENCE=https://your-api-identifier
AUTH0_REDIRECT_URI=${APP_URL}/callback

AUTH0_DOMAIN 是你的 Auth0 租户域名（不含 https://）。AUTH0_CLIENT_ID 和 AUTH0_CLIENT_SECRET 来自 Auth0 Application 设置。AUTH0_AUDIENCE 必须设为在 Auth0 中注册的 API 标识符（Auth0 Dashboard > Applications > APIs）——如果未设置，Auth0 会返回不透明访问令牌，SDK 无法解码这些令牌，导致恢复会话时崩溃。默认情况下，SDK 使用 APP_KEY 作为 Cookie 密钥，无需单独设置密钥。

重要： 如果使用内置开发服务器（http://localhost:8000），请确保 APP_URL 包含端口。全新安装的 Laravel 默认使用 http://localhost（不含端口），这会导致回调 URL 不匹配。

4. 配置 Auth0 Dashboard

在 Auth0 Application 设置中：

• Application Type：Regular Web Application
• Allowed Callback URLs：http://localhost:8000/callback
• Allowed Logout URLs：http://localhost:8000

5. 配置 Auth 守卫

更新 config/auth.php 以使用 Auth0 守卫：

'guards' => [
    'web' => [
        'driver' => 'auth0.authenticator',
        'provider' => 'auth0-provider',
        'configuration' => 'web',
    ],
],

'providers' => [
    'auth0-provider' => [
        'driver' => 'auth0.provider',
        'repository' => 'auth0.repository',
    ],
],

configuration 键映射到 config/auth0.php 中的守卫定义（web 使用 STRATEGY_REGULAR，采用基于会话的身份验证）。我们覆盖默认的 web 守卫，这样 Laravel 内置的 auth 中间件和 auth()->user() 就能正常工作，无需指定守卫名称。SDK 也会自动注册一个配置相同的 auth0-session 守卫，但覆盖 web 更简单。

6. 路由会自动注册

当 config/auth0.php 中的 registerAuthenticationRoutes 为 true 时，SDK 会自动注册以下路由：

• GET /login - 重定向到 Auth0 Universal Login
• GET /callback - 处理 OAuth 回调，并用授权码换取令牌
• GET /logout - 销毁会话并重定向到 Auth0 登出页面

身份验证流程无需手动定义路由。

7. 添加受保护的路由

在 routes/web.php 中：

use Illuminate\Support\Facades\Route;

Route::get('/', function () {
    return view('home', ['user' => auth()->user()]);
});

Route::middleware('auth')->group(function () {
    Route::get('/profile', function () {
        return view('profile', ['user' => auth()->user()]);
    });
});

标准的 auth 中间件可与 Auth0 守卫配合使用。未通过身份验证的用户会被重定向到 /login。

8. 创建视图

创建 resources/views/home.blade.php：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Home</title>
</head>
<body>
    @if($user)
        <h1>Welcome, {{ $user->name }}!</h1>
        <p><a href="/profile">Profile</a></p>
        <p><a href="/logout">Logout</a></p>
    @else
        <h1>Welcome</h1>
        <p><a href="/login">Login</a></p>
    @endif
</body>
</html>

创建 resources/views/profile.blade.php：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Profile</title>
</head>
<body>
    <h1>{{ $user->name }}</h1>
    <p>Email: {{ $user->email }}</p>
    <img src="{{ $user->picture }}" alt="avatar" width="100" />
    <hr>
    <h2>User Claims</h2>
    <pre>{{ json_encode($user->jsonSerialize(), JSON_PRETTY_PRINT) }}</pre>
    <p><a href="/">Home</a> | <a href="/logout">Logout</a></p>
</body>
</html>

9. 测试身份验证

php artisan serve

访问 http://localhost:8000 并点击 Login。

重要： 始终通过 http://localhost:8000 访问应用（不要使用 http://127.0.0.1:8000）。回调 URL 使用 localhost，因此会话 Cookie 必须为 localhost 设置，才能在 Auth0 登录重定向后继续生效。使用 127.0.0.1 会导致“Invalid state”错误，因为会话 Cookie 不会发送到 localhost 回调 URL。

常见错误

错误	修复方法
在 Laravel 中直接使用 auth0/auth0-php	使用 auth0/login，它通过 Laravel 守卫、中间件和路由封装 SDK
在 Auth0 Dashboard 中将应用创建为 SPA 类型	服务器端会话认证必须使用 Regular Web Application
在 Auth0 Dashboard 中缺少回调 URL	将 http://localhost:8000/callback 添加到 Allowed Callback URLs
在 Auth0 Dashboard 中缺少登出 URL	将 http://localhost:8000 添加到 Allowed Logout URLs
未发布配置	配置前运行 php artisan vendor:publish --tag=auth0
使用了错误的守卫驱动名称	驱动是 auth0.authenticator（不是 auth0 或 auth0.guard）
忘记设置 APP_KEY	运行 php artisan key:generate - SDK 会将其用作 Cookie 密钥
直接调用 Auth0::getCredentials()	使用 Laravel 的 auth()->user() - SDK 通过守卫集成
手动定义 /login、/callback、/logout 路由	服务提供者会自动注册这些路由
设置 AUTH0_DOMAIN 时带有 https:// 前缀	使用不带前缀的域名：tenant.us.auth0.com，而不是 https://tenant.us.auth0.com
未使用中间件就调用 $request->user()	仅在应用了 auth 中间件的路由中可用
缺少 AUTH0_AUDIENCE 环境变量	没有 audience 时，Auth0 会返回 SDK 无法解析的不透明令牌 - 导致 "JWT string must contain two dots" 崩溃
访问 http://127.0.0.1:8000，而非 http://localhost:8000	为 127.0.0.1 设置的会话 Cookie 不会发送到 localhost 回调 - 导致 "Invalid state" 错误
使用 $user->getName() 或 $user->getEmail()	StatefulUser 使用魔术方法 __get - 请使用 $user->name、$user->email、$user->picture

---

SDK 关键方法

方法	用法	用途
auth()->user()	在路由/控制器中	返回经过认证的 StatefulUser 或 null
auth()->check()	在路由/控制器/视图中	如果用户已通过认证，则返回 true
auth()->guard('web')	使用多个守卫时	获取指定的 Auth0 守卫实例
$user->name	在用户对象上	用户的显示名称（通过 __get 魔术方法获取）
$user->email	在用户对象上	用户的电子邮件（通过 __get 魔术方法获取）
$user->picture	在用户对象上	用户的头像 URL（通过 __get 魔术方法获取）
$user->getAuthIdentifier()	在用户对象上	返回 Auth0 的 sub 声明
$user->getAttribute('claim')	在用户对象上	显式返回任意声明值
$user->jsonSerialize()	在用户对象上	将所有用户声明作为数组返回

---

用户对象

经过认证的用户是一个 StatefulUser 实例，实现了 Laravel 的 Authenticatable 契约。它使用 __get 魔术方法以属性形式访问声明：

$user = auth()->user();

$user->name;                   // display name (via __get)
$user->email;                  // email address (via __get)
$user->picture;                // avatar URL (via __get)
$user->email_verified;         // any claim via property access
$user->getAuthIdentifier();   // Auth0 'sub' (e.g. 'auth0|abc123')
$user->getAttribute('sub');    // explicit claim access
$user->jsonSerialize();        // all claims as array

可将任何 ID 令牌声明作为属性访问：$user->nickname、$user->updated_at、$user->sub 等。如需显式访问，请使用 $user->getAttribute('claim_name')。

---

相关技能

• auth0-laravel-api - 使用 JWT Bearer 令牌验证保护 Laravel API 路由
• auth0-php - 不使用框架的纯 PHP Web 应用
• auth0-quickstart - Auth0 初始设置
• auth0-mfa - 添加多重身份验证
• auth0-cli - 从终端管理 Auth0 资源

---

快速参考

守卫配置（config/auth.php）：

'guards' => [
    'web' => [
        'driver' => 'auth0.authenticator',
        'provider' => 'auth0-provider',
        'configuration' => 'web',
    ],
],
'providers' => [
    'auth0-provider' => [
        'driver' => 'auth0.provider',
        'repository' => 'auth0.repository',
    ],
],

路由保护：

Route::middleware('auth')->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
});

在 Blade 中检查身份验证：

@auth
    <p>Hello, {{ auth()->user()->name }}</p>
@else
    <a href="/login">Login</a>
@endauth

环境变量：

• APP_URL - 应用 URL，包含端口（例如 http://localhost:8000）
• AUTH0_DOMAIN - Auth0 租户域名（例如 tenant.us.auth0.com）
• AUTH0_CLIENT_ID - 应用客户端 ID
• AUTH0_CLIENT_SECRET - 应用客户端密钥
• AUTH0_AUDIENCE - API 标识符（JWT 访问令牌必需）
• AUTH0_REDIRECT_URI - 回调 URL（默认为 ${APP_URL}/callback）
• APP_KEY - Laravel 应用密钥，用作 Cookie 加密密钥

详细文档

• 设置指南 - 自动化设置脚本、环境配置、Auth0 CLI 用法
• 集成指南 - 权限范围检查、调用 API、事件、自定义用户模型、会话管理
• API 参考 - 完整的守卫 API、配置选项、用户模型方法

---

参考资料

• Auth0 Laravel 快速入门
• SDK GitHub 仓库
• Packagist 上的 SDK