authbucket/oauth2-php

基于Symfony组件的符合标准的OAuth2.0库

5.0.0-alpha4 2017-06-20 14:18 UTC

README

Build Status Coverage Status Dependency Status Latest Stable Version Total Downloads License

AuthBucket\OAuth2的主要目标是开发一个符合标准的RFC6749 OAuth2.0库;次要目标是开发相应的Symfony2 BundleDrupal模块

这个库包含一个基于SilexAuthBucketOAuth2ServiceProvider,用于单元测试和演示。安装和使用可以参考以下内容。

安装

如果您使用Composer来管理项目依赖,只需将authbucket/oauth2-php添加到项目中的composer.json文件中即可。

以下是一个最小的composer.json示例

{
    "require": {
        "authbucket/oauth2-php": "~5.0"
    }
}

参数

捆绑的AuthBucketOAuth2ServiceProvider包含以下参数

  • authbucket_oauth2.model: (可选) 使用内存中的AccessToken与远程调试端点一起使用资源防火墙时,用您自己的模型类覆盖此参数,默认使用内存中的AccessToken。
  • authbucket_oauth2.model_manager.factory: (可选) 使用内存实现与远程调试端点一起使用资源防火墙时,用您自己的后端模型管理器覆盖此参数,例如使用Doctrine ORM EntityRepository,默认使用内存实现。
  • authbucket_oauth2.user_provider: (可选) 对于使用grant_type = password,使用您自己的用户提供者覆盖此参数,例如使用InMemoryUserProvider或实现UserProviderInterface的Doctrine ORM EntityRepository。

服务

捆绑的AuthBucketOAuth2ServiceProvider包含以下服务控制器,它简化了OAuth2.0控制器实现的负担

  • authbucket_oauth2.authorization_controller: 授权端点控制器。
  • authbucket_oauth2.token_controller: 令牌端点控制器。
  • authbucket_oauth2.debug_controller: 调试端点控制器。

注册

如果您使用Silex,请按照以下方式注册AuthBucketOAuth2ServiceProvider

$app->register(new AuthBucket\OAuth2\Silex\Provider\AuthBucketOAuth2ServiceProvider());

此外,如果尚未启用,请启用以下服务提供者

$app->register(new Silex\Provider\MonologServiceProvider());
$app->register(new Silex\Provider\SecurityServiceProvider());
$app->register(new Silex\Provider\ValidatorServiceProvider());

使用

此库将前端防火墙和后端控制器视角中的端点逻辑分开,因此您需要设置两者才能正常运行。

要启用内置控制器及其对应的路由,您需要手动挂载它

$app->get('/api/oauth2/authorize', 'authbucket_oauth2.authorization_controller:indexAction')
    ->bind('api_oauth2_authorize');

$app->post('/api/oauth2/token', 'authbucket_oauth2.token_controller:indexAction')
    ->bind('api_oauth2_token');

$app->match('/api/oauth2/debug', 'authbucket_oauth2.debug_controller:indexAction')
    ->bind('api_oauth2_debug');

以下是一些常见用例的配方列表。

授权端点

我们不为此端点提供自定义防火墙,您应该自行保护它,例如通过SecurityServiceProvider进行身份验证和捕获用户凭据。

$app['security.default_encoder'] = function ($app) {
    return new Symfony\Component\Security\Core\Encoder\PlaintextPasswordEncoder();
};

$app['security.user_provider.default'] = $app['security.user_provider.inmemory._proto']([
    'demousername1' => ['ROLE_USER', 'demopassword1'],
    'demousername2' => ['ROLE_USER', 'demopassword2'],
    'demousername3' => ['ROLE_USER', 'demopassword3'],
]);

$app['security.firewalls'] = [
    'api_oauth2_authorize' => [
        'pattern' => '^/api/oauth2/authorize$',
        'http' => true,
        'users' => $app['security.user_provider.default'],
    ],
];

令牌端点

与授权端点类似,我们需要用我们的自定义防火墙 oauth2_token 来保护这个端点

$app['security.firewalls'] = [
    'api_oauth2_token' => [
        'pattern' => '^/api/oauth2/token$',
        'oauth2_token' => true,
    ],
];

调试端点

我们应该用我们的自定义防火墙 oauth2_resource 来保护这个端点

$app['security.firewalls'] = [
    'api_oauth2_debug' => [
        'pattern' => '^/api/oauth2/debug$',
        'oauth2_resource' => true,
    ],
];

资源端点

除了上述调试端点外,我们不提供其他资源端点控制器实现。你应该考虑实现自己的端点,带有自定义逻辑,例如获取用户电子邮件地址或个人资料图片。

另一方面,你可以用我们的自定义防火墙 oauth2_resource 来保护你的资源服务器端点。简短版本(默认假设资源服务器与授权服务器捆绑在一起,查询本地模型管理器,没有范围保护)

$app['security.firewalls'] = [
    'api_resource' => [
        'pattern' => '^/api/resource',
        'oauth2_resource' => true,
    ],
];

长版本(假设资源服务器与授权服务器捆绑在一起,查询本地模型管理器,用范围 demoscope1 进行保护)

$app['security.firewalls'] = [
    'api_resource' => [
        'pattern' => '^/api/resource',
        'oauth2_resource' => [
            'resource_type' => 'model',
            'scope' => ['demoscope1'],
        ],
    ],
];

如果授权服务器托管在其他地方,你可以通过查询远程授权服务器调试端点来保护你的本地资源端点

$app['security.firewalls'] = [
    'api_resource' => [
        'pattern' => '^/api/resource',
        'oauth2_resource' => [
            'resource_type' => 'debug_endpoint',
            'scope' => ['demoscope1'],
            'options' => [
                'debug_endpoint' => 'http://example.com/api/oauth2/debug',
                'cache' => true,
            ],
        ],
    ],
];

演示

这个演示是基于 SilexAuthBucketOAuth2ServiceProvider。阅读演示 获取更多信息。

你也可以在本地运行这个演示。打开控制台,并执行以下命令在 oauth2-php 目录中安装最新版本

$ composer create-project authbucket/oauth2-php authbucket/oauth2-php "~5.0"

然后使用 PHP 内置的 Web 服务器来运行演示应用程序

$ cd authbucket/oauth2-php
$ ./bin/console server:run

如果你遇到错误 在 "server" 命名空间中未定义任何命令。,那么你可能在使用 PHP 5.3。没关系!但是内置的 Web 服务器仅适用于 PHP 5.4.0 或更高版本。如果你有较旧的 PHP 版本或更喜欢传统的 Web 服务器,如 Apache 或 Nginx,请阅读 配置 Web 服务器 文章。

打开你的浏览器,访问 http://127.0.0.1:8000 以查看演示应用程序的欢迎页面。

还可以访问 http://127.0.0.1:8000/admin/refresh_database 以使用用户账户 admin:secrete 初始化捆绑的 SQLite 数据库。

文档

OAuth2 的文档是用 Sami 构建的,并公开托管在 GitHub Pages 上。

要本地构建文档,请执行以下命令

$ sami.php update .sami.php

使用您的浏览器打开 build/sami/index.html 以查看文档。

测试

本项目由 PHPUnit 测试用例覆盖;CI 结果可以在 Travis CI 中找到;代码覆盖率报告可以在 Coveralls 中找到。

要本地运行测试套件,请执行以下命令

$ phpunit -c phpunit.xml.dist

使用您的浏览器打开 build/logs/html 以查看覆盖率报告。

参考

许可证

  • 代码在 MIT 许可下发布
  • 文档在 CC BY 4.0 许可下发布