README

Auth0 Laravel SDK是一个PHP包，可以将Auth0集成到您的Laravel应用程序中。它包括无代码用户身份验证、广泛的管理API支持、基于权限的路由访问控制等功能。

要求
入门
文档
快速入门
贡献
行为准则
安全性
许可

要求

您的应用程序必须使用一个受支持的Laravel版本，并且您的托管环境必须运行一个维护的PHP版本。请参阅我们的支持策略以获取更多信息。

您还需要Composer和一个Auth0账户。

支持的Laravel版本

Laravel的下一次重大版本预计将在2025年第一季度发布。我们预计将在发布后支持它。

我们努力支持所有活跃维护的Laravel版本，优先支持最新的主要版本。如果新的Laravel主要版本引入了破坏性变更，我们可能需要提前终止对之前Laravel版本的支持。

受影响的Laravel版本将在其生命周期的最后一天之前继续接收安全修复，如发布说明中所述。

维护版本

以下版本不再由Auth0更新新功能，但将继续在生命周期的最后一天之前接收安全更新。

不受支持的版本

以下版本不受Auth0支持。虽然它们可能适合某些旧应用程序，但性能可能会有所不同。我们建议尽快升级到支持的版本。

入门

以下是我们开始使用SDK的建议方法。我们的扩展安装指南中提供了其他选择。

1. 安装SDK

对于新应用程序，我们提供了一个快速入门模板——这是一个预配置用于与Auth0 SDK一起使用的默认Laravel 9启动项目版本。
```
composer create-project auth0-samples/laravel auth0-laravel-app && cd auth0-laravel-app
```
对于现有应用程序，您可以使用Composer安装SDK。
```
composer require auth0/login:^7 --update-with-all-dependencies
```
在这种情况下，您还需要为您的应用程序生成一个SDK配置文件。
```
php artisan vendor:publish --tag auth0
```

2. 安装CLI

安装Auth0 CLI以通过命令行管理您的账户。
```
curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b .
```
将CLI移动到您的PATH中的目录，使其在整个系统中可用。
```
sudo mv ./auth0 /usr/local/bin
```
💡 如果您不想移动CLI，只需在以下CLI步骤中将“auth0”替换为“./auth0”。
使用Homebrew (macOS)
```
brew tap auth0/auth0-cli && brew install auth0
```
使用Scoop (Windows)
```
scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
scoop install auth0
```
使用您的Auth0账户认证CLI。如果提示，请选择“作为用户”。
```
auth0 login
```

3. 配置SDK

使用Auth0注册一个新的应用程序。

auth0 apps create \
  --name "My Laravel Application" \
  --type "regular" \
  --auth-method "post" \
  --callbacks "https://:8000/callback" \
  --logout-urls "https://:8000" \
  --reveal-secrets \
  --no-input \
  --json > .auth0.app.json

使用Auth0注册一个新的API。

auth0 apis create \
  --name "My Laravel Application API" \
  --identifier "https://github.com/auth0/laravel-auth0" \
  --offline-access \
  --no-input \
  --json > .auth0.api.json

将新文件添加到.gitignore文件中。

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

使用Windows PowerShell

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

使用Windows命令提示符

echo .auth0.*.json >> .gitignore

4. 运行应用程序

使用PHP内置的Web服务器启动应用程序。

php artisan serve

将浏览器指向https://:8000以测试应用程序。

身份验证
用户可以通过访问/login或/logout路由分别登录或注销应用程序。

API授权
为了简化起见，使用CLI生成测试令牌。

auth0 test token \
  --audience %IDENTIFIER% \
  --scopes "read:messages"

✋ 将%IDENTIFIER%替换为步骤3中创建的API标识符。

现在您可以发送请求到应用程序的/api端点，包括作为头的令牌。

curl --request GET \
  --url https://:8000/api/example \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer %TOKEN%'

✋ 将%TOKEN%替换为上一步返回的测试令牌。

使用Windows PowerShell

Invoke-WebRequest http://localhost:8000/api/example `
  -Headers @{'Accept' = 'application/json'; 'Authorization' = 'Bearer %TOKEN%'}

当您准备好将应用程序部署到生产环境时，请查看我们的部署指南，以了解最佳实践和有关保护Laravel的建议。

集成示例

用户身份验证

SDK自动在您的应用程序的web中间件组中注册所有必要的路由和身份验证服务，以启用用户无需编写任何代码即可进行身份验证。

如果这些路由与您的应用程序架构冲突，您可以通过调整SDK配置来覆盖此默认行为。

路由授权（访问控制）

SDK自动在您的Laravel应用程序的web和api中间件组中分别注册其身份验证和授权保护。

对于web路由，您可以使用Laravel的auth中间件要求用户通过身份验证才能访问路由。

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

对于api路由，您可以使用Laravel的auth中间件要求请求通过有效的承载令牌进行身份验证才能访问路由。

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

除了要求用户通过身份验证外，您还可以要求用户具有特定的权限才能访问路由，使用Laravel的can中间件。

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

权限需要RBAC在您的API设置中启用。

用户和令牌

Laravel的Auth外观可以用来自动获取有关通过请求关联的已验证用户或令牌的信息。

对于在routes/web.php中使用web中间件组的路由。

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}.");
});

对于在routes/api.php中使用api中间件组的路由。

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(),
  ]);
});

管理API调用

一旦您授权应用程序进行管理API调用，您就可以通过SDK使用Auth0管理API的几乎所有端点。

每个API端点都有自己的SDK类，可以通过外观的management()工厂方法访问。为了互操作性，API的网络响应以PSR-7消息返回。这些可以使用SDK的json()方法转换为原生数组。

例如，要更新用户的元数据，您可以调用management()->users()->update()方法。

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

所有SDK的管理API方法都在此处文档化。

文档

安装 — 安装SDK并生成配置文件。
配置 — 使用JSON文件或环境变量配置SDK。
会话 — 关于选择哪个Laravel会话API驱动的指导。
Cookies — 使用Laravel的Cookie会话驱动的重要注意事项和替代选项。
管理API — 使用SDK与Auth0管理API交互。
用户 — 扩展SDK以支持持久存储和Eloquent模型。
事件 — 在SDK的事件中挂钩以响应对特定动作的响应。
部署 — 将您的应用程序部署到生产环境。

以下集成指南可能对您有帮助

Laravel Eloquent — 支持Eloquent ORM。
Laravel Octane — 目前不支持Octane。
Laravel Telescope — 自SDK v7.11.0起兼容Telescope。

您还可以找到以下资源有所帮助

欢迎为改进我们的文档做出贡献。

快速入门

社区

您可以在Auth0社区获得支持、提问和分享您的项目。

贡献

我们感谢对库的反馈和贡献。在您开始之前，请查阅Auth0的通用贡献指南。

贡献指南包含有关我们的开发过程和期望的信息，以及如何提出错误修复和改进的见解，以及如何构建和测试对库的更改的说明。

要提供反馈或报告错误，请提出问题。

行为准则

参与者在与本项目互动时，应遵守Auth0的行为准则。

安全性

如果您认为您发现了安全漏洞，我们鼓励您负责任地披露此事，而不是公开创建问题。我们将调查所有报告。有关披露安全问题的负责任披露计划详细说明了披露程序。

许可

此库是开源软件，根据MIT许可授权。

Auth0是一个易于实现、可适应的认证和授权平台。
想了解更多信息，请查看“为什么选择Auth0？”

auth0 / login

维护者

详细信息