如何在Laravel中实现OAuth认证

幻夢星雲

发布时间：2025-07-09 21:02:01

766人浏览过

来源于php中文网

原创

在laravel中实现oauth认证的推荐方式是使用laravel passport。1. 安装passport：通过composer安装包；2. 运行迁移：创建存储客户端和令牌所需的数据库表；3. 安装passport：执行命令生成加密密钥和默认客户端；4. 配置用户模型：引入hasapitokens trait；5. 注册passport路由：在authserviceprovider中调用passport::routes()；6. 配置api认证守卫：将api守卫驱动设为passport。passport提供完整oauth2实现，简化了授权流程、令牌管理和api保护，支持多种授权类型，如个人访问令牌、密码授权、授权码授权（含pkce）和服务凭证授权，适用于不同场景。客户端和令牌生命周期可通过命令创建、配置过期时间、撤销特定或全部令牌来管理，保障系统安全性。

如何在Laravel中实现OAuth认证

在Laravel中实现OAuth认证，最直接且推荐的方式是使用官方提供的Laravel Passport包。它为你的Laravel应用提供了一个完整的OAuth2服务器实现，极大地简化了令牌的颁发、刷新和验证过程，让你能专注于业务逻辑而非底层协议细节。

解决方案

要在Laravel中集成OAuth认证，主要步骤围绕Laravel Passport展开：

安装 Passport 包： 首先，通过 Composer 将 Passport 安装到你的项目中。
```
composer require laravel/passport
```
运行迁移： 安装完成后，你需要运行数据库迁移，Passport 会创建它所需的所有表，比如存储客户端、访问令牌和刷新令牌的表。
```
php artisan migrate
```
安装 Passport： 执行 Passport 的安装命令。这个命令会创建加密密钥（用于签名令牌）和默认的“个人访问客户端”以及“密码授权客户端”。
```
php artisan passport:install
```
这些客户端对后续生成令牌非常关键。
配置用户模型： 在你的 App\Models\User 模型中，引入 Laravel\Passport\HasApiTokens trait。这个 trait 提供了方便的方法来管理用户的访问令牌。

注册 Passport 路由： 在 App\Providers\AuthServiceProvider 文件的 boot 方法中，调用 Passport::routes() 方法。这会注册所有必要的 OAuth 认证路由，例如用于颁发令牌和撤销令牌的路由。

 'App\Policies\ModelPolicy',
    ];

    /**
     * Register any authentication / authorization services.
     *
     * @return void
     */
    public function boot()
    {
        $this->registerPolicies();

        Passport::routes(); // 注册 Passport 路由
        // 如果需要，你也可以在这里定义令牌的过期时间
        // Passport::tokensExpireIn(now()->addDays(15));
        // Passport::refreshTokensExpireIn(now()->addDays(30));
        // Passport::personalAccessTokensExpireIn(now()->addMonths(6));
    }
}

配置 API 认证守卫： 最后一步是修改 config/auth.php 文件，将 api 守卫的驱动器设置为 passport。这样，当你的 API 路由使用 auth:api 中间件时，Laravel 就会使用 Passport 来验证请求。

// config/auth.php
'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],

    'api' => [
        'driver' => 'passport', // 将驱动器改为 passport
        'provider' => 'users',
        'hash' => false,
    ],
],

完成这些步骤后，你的 Laravel 应用就具备了OAuth2认证的能力。你可以通过 Passport 提供的客户端（如个人访问令牌或密码授权客户端）来生成和验证访问令牌，进而保护你的 API 路由。例如，保护一个路由只需简单地添加 auth:api 中间件：

Route::middleware('auth:api')->get('/user', function (Request $request) {
    return $request->user();
});

当请求这个 /user 路由时，如果请求头中带有有效的 Passport 令牌，$request->user() 就能获取到当前认证的用户。

Laravel Passport是什么？它如何简化OAuth实现？

Laravel Passport 可以说是 Laravel 官方提供的一站式 OAuth2 解决方案。它不是简单地提供了一些OAuth的工具函数，而是一个完整的、开箱即用的 OAuth2 服务器实现。我个人觉得，Passport 的出现，极大地降低了在 Laravel 应用中实现安全、符合规范的 API 认证的门槛。如果没有它，我们可能需要花费大量时间去理解 OAuth2 协议的各种授权流程、令牌管理、密钥生成等细节，并且要自己编写大量代码来处理这些。

Passport 的简化体现在几个方面：

完整协议实现： 它内置了 OAuth2 规范中常见的几种授权类型（如授权码授权、密码授权、客户端凭证授权和个人访问令牌），开发者不需要从零开始理解和实现这些复杂的流程。
数据库集成： 令牌、客户端等关键信息都存储在数据库中，Passport 提供了相应的迁移和模型，使得管理这些数据变得非常方便。
令牌管理： 它自动处理令牌的生成、刷新、过期和撤销。比如，当你需要撤销一个用户的某个令牌时，只需调用一个简单的方法即可。
API 保护中间件： 通过简单的 auth:api 中间件，就能轻松保护你的 API 路由，Passport 会自动验证传入的访问令牌。
前端组件： 尽管现在前端框架多样，但 Passport 也曾提供过一些 Vue 组件，帮助快速搭建客户端管理界面，虽然现在可能更倾向于自定义前端，但其核心思想是提供便利。
密钥管理： 自动生成并管理用于令牌签名的加密密钥，这对于保证令牌的安全性至关重要。

总的来说，Passport 就像一个“黑盒”，你只需要按照它的规则配置好，它就能为你处理所有 OAuth2 的复杂性，让你能更专注于业务逻辑的实现，而不是陷入认证机制的泥潭。这对于我这种不太想深究底层加密和协议细节的开发者来说，简直是福音。

不同OAuth授权类型在Laravel Passport中如何选择和使用？

Laravel Passport 支持多种 OAuth2 授权类型，每种类型都有其特定的适用场景。理解它们之间的区别，并根据你的应用需求选择最合适的类型，是构建安全 API 的关键。我经常看到一些项目，不分青红皂白地都用密码授权，这其实是存在安全隐患的。

Shakespeare

一款人工智能文案软件，能够创建几乎任何类型的文案。

下载

个人访问令牌 (Personal Access Tokens - PATs)：
- 适用场景： 当你需要为自己的应用或脚本访问 API 时，或者当用户希望授权第三方应用访问他们自己的数据时。例如，一个用户希望通过一个命令行工具来管理自己的博客文章，就可以生成一个 PAT。
- 使用方式： 通常由用户在你的应用界面中生成。通过 php artisan passport:client --personal 命令可以创建一个个人访问客户端。生成后，用户会得到一个长字符串令牌，直接在请求头中作为 Bearer 令牌使用。
- 特点： 长期有效，不依赖用户密码，用户可以随时撤销。非常适合机器到机器的通信或用户个人工具。
密码授权 (Password Grant)：
- 适用场景： 当你的“客户端”是你的第一方应用（例如，你自己的移动应用或单页应用 SPA）时。用户直接在你的应用中输入用户名和密码进行认证，应用将这些凭据发送给你的 Laravel 后端，后端再通过 Passport 交换得到访问令牌。
- 使用方式： 你的前端应用向 /oauth/token 路由发送 POST 请求，包含 grant_type=password 以及用户的 username 和 password。Passport 验证后返回 access_token 和 refresh_token。
- 特点： 方便快捷，用户体验流畅。但请注意，这不适用于第三方应用！因为这意味着第三方应用会获取到用户的密码，这在安全上是极大的风险。只在你完全信任并控制客户端时使用。
授权码授权 (Authorization Code Grant with PKCE)：
- 适用场景： 这是最安全、最推荐的授权类型，尤其适用于第三方应用（如公共客户端，如浏览器中的 JavaScript 应用、桌面应用、移动应用）。它通过浏览器重定向，将用户导向你的认证服务器进行授权，然后返回一个授权码，客户端再用这个码去交换访问令牌。
- 使用方式： 客户端将用户重定向到你的 /oauth/authorize 路由，用户在你的应用中同意授权后，浏览器会重定向回客户端的 redirect_uri 并带上一个授权码。客户端再用这个授权码和 code_verifier（PKCE 关键）向 /oauth/token 交换访问令牌。
- 特点： 安全性最高，用户的凭据永远不会暴露给第三方客户端。PKCE (Proof Key for Code Exchange) 的加入，进一步增强了公共客户端的安全性，防止授权码被拦截后滥用。我强烈建议所有公共客户端都优先考虑这种方式。
客户端凭证授权 (Client Credentials Grant)：
- 适用场景： 当你的客户端本身就是一个“服务”或“机器”，需要访问你的 API，但没有用户上下文时。例如，一个后台服务需要访问另一个服务的 API 来同步数据。
- 使用方式： 客户端直接使用其 client_id 和 client_secret 向 /oauth/token 路由请求令牌。
- 特点： 没有用户参与，直接基于客户端的身份进行认证。适用于服务到服务的通信。

在实际项目中，我通常会根据客户端的类型和信任程度来选择授权方式。如果是我的移动应用或SPA，且我能完全控制其代码，可能会考虑密码授权（虽然授权码+PKCE 更优）。但只要涉及到第三方集成，授权码授权是唯一的选择。

如何在Laravel中管理OAuth客户端和令牌的生命周期？

管理 OAuth 客户端和令牌的生命周期是确保 API 安全和可控性的重要组成部分。Laravel Passport 提供了一些工具和方法来帮助我们完成这项工作。

客户端管理： OAuth 客户端是你的应用中请求访问令牌的实体。它们可以是你的第一方应用，也可以是第三方应用。
- 创建客户端： 除了 php artisan passport:install 自动创建的两个默认客户端外，你可以通过 php artisan passport:client 命令手动创建新的客户端。
```
php artisan passport:client --name="My Third-Party App" --redirect_uri="http://localhost/callback"
```
  这个命令会生成一个 client_id 和 client_secret。对于授权码授权，redirect_uri 是必须的。你也可以在代码中通过 Passport::client()->create(...) 来创建客户端。
- 客户端类型： 在 oauth_clients 表中，personal_access_client 字段表示是否是个人访问令牌客户端，password_client 表示是否是密码授权客户端。revoked 字段则用于标记客户端是否已被撤销。
- 撤销客户端： 如果一个客户端不再需要访问你的 API，或者你怀疑它已被泄露，你可以将其标记为已撤销。这通常通过更新 oauth_clients 表中的 revoked 字段为 true 来实现。被撤销的客户端将无法再请求新的令牌。
令牌管理： 访问令牌 (Access Tokens) 是客户端访问受保护资源的凭证，而刷新令牌 (Refresh Tokens) 则用于获取新的访问令牌，避免用户频繁重新认证。
- 令牌的颁发： 当用户通过任何授权流程成功认证后，Passport 会生成一个访问令牌和一个刷新令牌，并存储在 oauth_access_tokens 和 oauth_refresh_tokens 表中。
- 令牌的过期： 访问令牌通常是短期有效的（例如几小时或几天），而刷新令牌则可以长期有效。你可以在 AuthServiceProvider 的 boot 方法中配置令牌的过期时间：
```
Passport::tokensExpireIn(now()->addMinutes(30)); // 访问令牌30分钟过期
Passport::refreshTokensExpireIn(now()->addDays(7)); // 刷新令牌7天过期
```
  当访问令牌过期时，客户端可以使用刷新令牌来获取新的访问令牌，而无需用户重新登录。
- 令牌的撤销： 这是令牌生命周期管理中非常关键的一环，尤其是在用户退出登录或更改密码时。
  - 撤销当前用户的令牌： 当用户退出登录时，你可以通过 Auth::user()->token()->revoke(); 来撤销当前用户正在使用的访问令牌。这将使该令牌立即失效。
  - 撤销用户的所有令牌： 如果你希望强制用户重新登录，或者怀疑某个用户的令牌被泄露，你可以撤销该用户的所有令牌：
```
DB::table('oauth_access_tokens')
    ->where('user_id', $userId)
    ->update(['revoked' => true]);
```
    同时，也应该撤销相关的刷新令牌。
  - 撤销特定令牌： 如果你知道某个令牌的 ID，也可以单独撤销它。
- 刷新令牌的自动处理： Passport 会自动处理刷新令牌的逻辑。当客户端使用一个过期的访问令牌但提供了有效的刷新令牌时，Passport 会验证刷新令牌的有效性，然后颁发一个新的访问令牌和刷新令牌。

我个人在实际项目中，尤其注重令牌的撤销机制。一个健壮的退出登录流程，不应该仅仅是清除前端的令牌，更重要的是通知后端将该令牌标记为无效。这能有效防止已泄露或不再需要的令牌继续被滥用。此外，定期审查 oauth_clients 和 oauth_access_tokens 表，清理或撤销不再活跃的客户端和令牌，也是维护系统安全性的好习惯。

Laravel Asset编译怎么配置_Laravel Vite前端构建工具使用

Laravel如何集成Inertia.js与Vue/React？（安装配置）

Laravel怎么集成Vue.js_Laravel Mix配置Vue开发环境

Laravel Inertia.js入门教程_Laravel构建单页应用指南

Laravel Jetstream是什么_Laravel Jetstream高级脚手架安装与使用详解