README

这是一个由 非凡软件联盟 编写的 PHP 标准合规 OAuth 2.0 授权服务器和资源服务器的包装包。

此包假设您对 OAuth 2.0 规范 的原理有足够的了解。

包安装

使用 Laravel 包安装器

安装此包的最简单方法是使用 Laravel 包安装器，这将为您设置所有服务提供者和别名。运行以下 artisan 命令来安装包

php artisan package:install lucadegasperi/oauth2-server-laravel

手动安装

或者，您可以通过 composer 手动安装此包。将以下行添加到您的 composer.json 文件中

"lucadegasperi/oauth2-server-laravel": "1.0.x"

将以下代码行添加到您的 app/config/app.php 文件中的 providers 数组

'LucaDegasperi\OAuth2Server\OAuth2ServerServiceProvider',

并将以下行添加到 aliases 数组

'AuthorizationServer' => 'LucaDegasperi\OAuth2Server\Facades\AuthorizationServerFacade',
'ResourceServer' => 'LucaDegasperi\OAuth2Server\Facades\ResourceServerFacade',

配置

为了使用 OAuth2 服务器，首先发布其配置

php artisan config:publish lucadegasperi/oauth2-server-laravel

然后编辑文件 app/config/packages/lucadegasperi/oauth2-server-laravel/oauth2.php 以满足您的需求。

迁移

此包包含运行完整功能的 OAuth2 服务器所需的所有迁移。运行

php artisan migrate --package="lucadegasperi/oauth2-server-laravel"

颁发访问令牌

您可以使用不同的授权类型来颁发访问令牌，具体取决于哪种类型适合您的用例。不同授权类型的详细描述可以在 此处 找到

客户端应向访问令牌端点（如此处定义的端点）发送带有适当参数的 POST 请求（取决于使用的授权类型）。此包将为您处理所有繁琐的工作。

Route::post('oauth/access_token', function()
{
    return AuthorizationServer::performAccessTokenFlow();
});

授权码流

最常见的授权类型是 authorization_code。它的设置也最长，但不用担心，它会很容易。

首先，客户端必须从资源所有者那里获得授权（不是访问令牌），以便代表其访问资源。客户端应用程序应将用户重定向到带有正确查询字符串参数的授权页面，例如

https://www.example.com/oauth/authorize?
client_id=the_client_id&
redirect_uri=client_redirect_uri&
response_type=code&
scope=scope1,scope2&
state=1234567890

Route::get('/oauth/authorize', array('before' => 'check-authorization-params|auth', function()
{
    // get the data from the check-authorization-params filter
    $params = Session::get('authorize-params');

    // get the user id
    $params['user_id'] = Auth::user()->id;

    // display the authorization form
    return View::make('authorization-form', array('params' => $params));
}));

Route::post('/oauth/authorize', array('before' => 'check-authorization-params|auth|csrf', function()
{
    // get the data from the check-authorization-params filter
    $params = Session::get('authorize-params');

    // get the user id
    $params['user_id'] = Auth::user()->id;

    // check if the user approved or denied the authorization request
    if (Input::get('approve') !== null) {

        $code = AuthorizationServer::newAuthorizeRequest('user', $params['user_id'], $params);

        Session::forget('authorize-params');
            
        return Redirect::to(AuthorizationServer::makeRedirectWithCode($code, $params));
    }

    if (Input::get('deny') !== null) {

        Session::forget('authorize-params');

        return Redirect::to(AuthorizationServer::makeRedirectWithError($params));
    }
}));

如果授权过程成功，客户端将被重定向到其 redirect_uri 参数，查询字符串中包含一个授权码，如下例所示

https://www.yourclient.com/redirect?code=XYZ123

客户端现在可以使用此代码在后台发送访问令牌请求。

POST https://www.example.com/oauth/access_token?
grant_type=authorization_code&
client_id=the_client_id&
client_secret=the_client_secret&
redirect_uri=client_redirect_uri&
code=the_authorization_code&
scope=scope1,scope2&
state=123456789

密码流

此授权类型使用起来最简单，非常适合高度信任的客户端。要启用此授权类型，请将以下代码添加到位于 app/config/packages/lucadegasperi/oauth2-server-laravel/oauth2.php 的 grant_types 数组中

'password' => array(
    'class'            => 'League\OAuth2\Server\Grant\Password',
    'access_token_ttl' => 604800,
    'callback'         => function($username, $password){
        
        $credentials = array(
            'email' => $username,
            'password' => $password,
        );

        $valid = Auth::validate($credentials);

        if (!$valid) {
            return false;
        }

        return Auth::getProvider()->retrieveByCredentials($credentials)->id;
    }
),

使用此授权类型请求访问令牌的示例请求可能如下所示。

POST https://www.example.com/oauth/access_token?
grant_type=password&
client_id=the_client_id&
client_secret=the_client_secret&
username=the_username&
password=the_password&
scope=scope1,scope2&
state=123456789

客户端凭据流

有时客户端和资源所有者是同一事物。此授权类型允许客户端代表其自身访问您的 API。要启用此授权类型，请将以下代码添加到位于 app/config/packages/lucadegasperi/oauth2-server-laravel/oauth2.php 的 grant_types 数组中

'client_credentials' => array(
    'class'            => 'League\OAuth2\Server\Grant\ClientCredentials',
    'access_token_ttl' => 3600,
),

使用此授权类型请求访问令牌的示例请求可能如下所示。

POST https://www.example.com/oauth/access_token?
grant_type=client_credentials&
client_id=the_client_id&
client_secret=the_client_secret&
scope=scope1,scope2&
state=123456789

刷新令牌流

访问令牌确实会过期，但通过使用刷新令牌流程，您可以交换一个刷新令牌以获取一个访问令牌。当启用此授权类型时，每次访问令牌请求都会颁发一个刷新令牌，您可以使用它来获取新的访问令牌，当当前令牌过期时。在位于 app/config/packages/lucadegasperi/oauth2-server-laravel/oauth2.php 的 grant_types 数组中配置此授权类型，如下所示

'refresh_token' => array(
    'class'                 => 'League\OAuth2\Server\Grant\RefreshToken',
    'access_token_ttl'      => 3600,
    'refresh_token_ttl'     => 604800,
    'rotate_refresh_tokens' => false,
),

使用此授权类型请求访问令牌的示例请求可能如下所示。

POST https://www.example.com/oauth/access_token?
grant_type=refresh_token&
refresh_token=the_refresh_token&
client_id=the_client_id&
client_secret=the_client_secret&
state=123456789

保护API端点

您可以通过在laravel路由上应用 oauth 前置过滤器来使用oauth保护它们，如下例所示

Route::get('secure-route', array('before' => 'oauth', function(){
    return "oauth secured route";
}));

此外，您可以通过将它们传递到过滤器名称中来向 oauth 前置过滤器提供允许的作用域。

Route::get('secure-route', array('before' => 'oauth:scope1,scope2', function(){
    return "oauth secured route";
}));

一个有趣的功能是，当使用客户端凭据授权类型时，可以将端点限制为特定所有者类型。这可以通过向您的路由添加 oauth-owner 前置过滤器来实现。

Route::get('secure-route', array('before' => 'oauth:scope1,scope2|oauth-owner:client', function(){
    return "oauth secured route for clients only";
}));

访问API

要访问任何api路由，在颁发令牌后，您必须将其作为参数传递给api调用

http://www.example.com/secure-route?access_token= '有效令牌'

获取令牌所有者ID和类型

当使用访问令牌访问您的API时，您可能想知道令牌的所有者是谁。服务器使其变得非常简单。

$ownerId = ResourceServer::getOwnerId();

当使用 client_credentials 授权类型时，您可能会有用户和客户端混合在一起，为了区分它们，请使用以下方法

$ownerType = ResourceServer::getOwnerType();

此包的目的是使在Laravel中与oauth2服务器功能一起工作变得容易。您仍然可以通过 ResourceServer 和 AuthorizationServer 门面访问所有底层league/oauth2-server包的功能。

支持

错误和功能请求在 GitHub 上跟踪

许可

此包在MIT许可证下发布。

致谢

此包基于的代码主要由 Alex Bilbie 开发和维护。