README

仓库于 2019-12-31 被废弃

该仓库已迁移至 laminas-api-tools/api-tools-oauth2。

ZF 模块，用于实现 OAuth2 身份验证。

本模块使用 Brent Shaffer 的 oauth2-server-php 库提供 OAuth2 支持。

要求

请查看 composer.json 文件。

安装

您可以使用以下方式安装：

$ composer require zfcampus/zf-oauth2

如果您正在使用 ext/mongodb，您还需要安装一个兼容包

$ composer require alcaeus/mongo-php-adapter

最后，您需要将以下模块添加到您应用程序的配置中

'modules' => [
    /* ... */
    'ZF\ApiProblem',
    'ZF\ContentNegotiation',
    'ZF\OAuth2',
],

zf-component-installer

如果您使用 zf-component-installer，则该插件将为您安装 zf-oauth2 和其其他 Apigility 依赖项作为模块。

配置

本模块使用任何 PDO 支持的数据库来管理 OAuth2 信息（用户、客户端、令牌等）。数据库结构存储在 data/db_oauth2.sql 中。

CREATE TABLE oauth_clients (
    client_id VARCHAR(80) NOT NULL,
    client_secret VARCHAR(80) NOT NULL,
    redirect_uri VARCHAR(2000) NOT NULL,
    grant_types VARCHAR(80),
    scope VARCHAR(2000),
    user_id VARCHAR(255),
    CONSTRAINT clients_client_id_pk PRIMARY KEY (client_id)
);
CREATE TABLE oauth_access_tokens (
    access_token VARCHAR(40) NOT NULL,
    client_id VARCHAR(80) NOT NULL,
    user_id VARCHAR(255),
    expires TIMESTAMP NOT NULL,
    scope VARCHAR(2000),
    CONSTRAINT access_token_pk PRIMARY KEY (access_token)
);
CREATE TABLE oauth_authorization_codes (
    authorization_code VARCHAR(40) NOT NULL,
    client_id VARCHAR(80) NOT NULL,
    user_id VARCHAR(255),
    redirect_uri VARCHAR(2000),
    expires TIMESTAMP NOT NULL,
    scope VARCHAR(2000),
    id_token VARCHAR(2000),
    CONSTRAINT auth_code_pk PRIMARY KEY (authorization_code)
);
CREATE TABLE oauth_refresh_tokens (
    refresh_token VARCHAR(40) NOT NULL,
    client_id VARCHAR(80) NOT NULL,
    user_id VARCHAR(255),
    expires TIMESTAMP NOT NULL,
    scope VARCHAR(2000),
    CONSTRAINT refresh_token_pk PRIMARY KEY (refresh_token)
);
CREATE TABLE oauth_users (
    username VARCHAR(255) NOT NULL,
    password VARCHAR(2000),
    first_name VARCHAR(255),
    last_name VARCHAR(255),
    CONSTRAINT username_pk PRIMARY KEY (username)
);
CREATE TABLE oauth_scopes (
    type VARCHAR(255) NOT NULL DEFAULT "supported",
    scope VARCHAR(2000),
    client_id VARCHAR (80),
    is_default SMALLINT DEFAULT NULL
);
CREATE TABLE oauth_jwt (
    client_id VARCHAR(80) NOT NULL,
    subject VARCHAR(80),
    public_key VARCHAR(2000),
    CONSTRAINT jwt_client_id_pk PRIMARY KEY (client_id)
);

PostgreSQL

我们还在 data/db_oauth2_postgresql.sql 中提供了一个 PostgreSQL 特定的 DDL。

出于安全考虑，我们使用 bcrypt 算法（通过类 Zend\Crypt\Password\Bcrypt）加密字段 client_secret（表 oauth_clients）和 password（表 oauth_users）。

为了配置 zf-oauth2 模块以访问数据库，您需要将文件 config/oauth2.local.php.dist 复制到您的 ZF2 应用程序中的 config/autoload/oauth2.local.php，并编辑它以提供您的数据库凭据（DNS、用户名、密码）。

我们还包含一个 SQLite 数据库在 data/dbtest.sqlite 中，您可以在测试环境中使用。在此数据库中，您将找到一个测试客户端帐户，其 client_id 为 "testclient"，client_secret 为 "testpass"。如果您想使用此数据库，您可以将您的 config/autoload/oauth2.local.php 文件配置如下：

return array(
    'zf-oauth2' => array(
        'db' => array(
            'dsn' => 'sqlite:<path to zf-oauth2 module>/data/dbtest.sqlite',
        ),
    ),
);

Mongo 配置

mongo OAuth2适配器通过添加与apigility其余部分相同的密码加密，封装了bshaffer适配器。所需集合与上述PDO适配器中的相同。要创建OAuth2客户端，请将以下文档插入到oauth_clients集合中

{
    "client_id":     "testclient",
    "client_secret": "$2y$14$f3qml4G2hG6sxM26VMq.geDYbsS089IBtVJ7DlD05BoViS9PFykE2",
    "redirect_uri":  "/oauth/receivecode",
    "grant_types":   null
}

用户ID提供者

当用户请求授权码时，他们可以将他们的user_id作为请求参数提供给/oauth/authorize路由。这将随着用户通过oauth2过程，在access_token、refresh_token和authorization_code表中存储user_id。

用户可以通过Zend\Authentication\AuthenticationService或另一种认证方式来认证。当用户在访问/oauth/authorize路由之前必须提供认证时，应使用认证过的用户ID。这通过服务管理器别名ZF\OAuth2\Provider\UserId完成。

默认的用户ID提供者使用请求查询参数user_id，并通过类ZF\OAuth2\Provider\UserId\Request处理。

此存储库提供了一个备用提供者ZF\OAuth2\Provider\UserId\AuthorizationService，它使用Zend\Authentication\AuthenticationService获取身份。要将用户ID提供者更改为使用此服务，将服务别名ZF\OAuth2\Provider\UserId更改为指向它。

return array(
    'service_manager' => 
        'aliases' => array(
            'ZF\OAuth2\Provider\UserId' => 'ZF\OAuth2\Provider\UserId\AuthenticationService',
        ),
    ),
);

如何测试OAuth2

要测试OAuth2模块，您必须将client_id和client_secret添加到oauth2数据库中。如果您使用的是SQLite测试数据库，则不需要添加client_id；只需使用默认的“testclient”/“testpass”帐户即可。

因为我们使用bcrypt算法加密密码，您需要使用来自Zend Framework 2的Zend\Crypt\Password\Bcrypt类来加密密码。我们提供了一个简单的脚本/bin/bcrypt.php来生成用户密码的散列值。您可以从命令行使用此工具，以下为语法

php bin/bcrypt.php testpass

其中“testpass”是要加密的用户密码。上一条命令的输出将是用户密码的散列值，一个60字节的字符串，如下所示

$2y$14$f3qml4G2hG6sxM26VMq.geDYbsS089IBtVJ7DlD05BoViS9PFykE2

在生成密码的散列值（client_secret）后，您可以使用以下SQL语句在数据库中添加一个新的client_id

INSERT INTO oauth_clients (
    client_id,
    client_secret,
    redirect_uri)
VALUES (
    "testclient",
    "$2y$14$f3qml4G2hG6sxM26VMq.geDYbsS089IBtVJ7DlD05BoViS9PFykE2",
    "/oauth/receivecode"
);

要测试OAuth2模块，您可以使用HTTP客户端，如HTTPie或CURL。以下示例使用HTTPie和测试帐户“testclient”/“testpass”。

请求令牌（客户端凭据）

您可以使用以下HTTPie命令请求OAuth2令牌

http --auth testclient:testpass -f POST http://<URL of your ZF2 app>/oauth grant_type=client_credentials

此POST请求使用client_credentials模式向OAuth2服务器请求新的令牌。这在机器到机器交互中的应用访问中很常见。如果一切正常，您应该收到如下响应

{
    "access_token":"03807cb390319329bdf6c777d4dfae9c0d3b3c35",
    "expires_in":3600,
    "token_type":"bearer",
    "scope":null
}

安全提示：因为这个POST使用基本HTTP认证，client_secret以明文形式暴露在HTTP请求中。为了保护这个调用，需要TLS/SSL连接。

授权（代码）

如果您需要将OAuth2服务与Web应用程序集成，您需要使用授权代码授予类型。此授权需要一个批准步骤来授权Web应用程序。此步骤通过一个简单的表单实现，该表单请求用户批准对资源（帐户）的访问。此模块提供了一个简单的表单来授权特定的客户端。此表单可以通过以下URL通过浏览器访问

http://<URL of your ZF2 app>/oauth/authorize?response_type=code&client_id=testclient&redirect_uri=/oauth/receivecode&state=xyz

此页面将显示一个表单，询问用户是否授权或拒绝客户端的访问。如果用户授权访问，OAuth2模块将返回一个授权码。此代码必须用于请求OAuth2令牌；以下HTTPie命令提供了一个示例，说明了如何进行请求。

http --auth testclient:testpass -f POST http://<URL of your ZF2 app>/oauth grant_type=authorization_code&code=YOUR_CODE&redirect_uri=/oauth/receivecode

在客户端场景（例如移动端）中，如果您无法以安全方式存储客户端凭据，则不能使用之前的流程。在这种情况下，我们可以使用隐式授权。这与授权码类似，但不是从授权请求中返回授权码，而是返回一个令牌。

要使模块能够接受隐式授权类型，您需要将config/autoload/oauth2.local.php文件中的allow_implicit配置更改为true。

return array(
    'zf-oauth2' => array(
        // ...
        'allow_implicit' => true,
        // ...
    ),
);

要从客户端请求令牌，您需要通过OAuth2服务器请求授权。

http://<URL of your ZF2 app>/oauth/authorize?response_type=token&client_id=testclient&redirect_uri=/oauth/receivecode&state=xyz

此请求将显示与上一个示例中相同的授权表单。如果您授权访问，请求将被重定向到/oauth/receivecode（如上述示例中提供的redirect_uri参数所示），并在URI片段中指定access_token，如下所示。

/oauth/receivecode#access_token=559d8f9b6bedd8d94c8e8d708f87475f4838c514&expires_in=3600&token_type=Bearer&state=xyz

要获取access_token，您可以通过解析URI来实现。我们使用URI片段传递access_token，因为这样令牌就不会被传输到服务器；它只对客户端可用。

在JavaScript中，您可以使用以下代码片段轻松解析URI。

// function to parse fragment parameters
var parseQueryString = function( queryString ) {
    var params = {}, queries, temp, i, l;

    // Split into key/value pairs
    queries = queryString.split("&");

    // Convert the array of strings into an object
    for ( i = 0, l = queries.length; i < l; i++ ) {
        temp = queries[i].split('=');
        params[temp[0]] = temp[1];
    }
    return params;
};

// get token params from URL fragment
var tokenParams = parseQueryString(window.location.hash.substr(1));

撤销（代码）

从版本1.4.0开始，您可以撤销访问令牌。默认情况下，撤销通过向路径/oauth/revoke发送POST请求来完成，该路径期望一个包含以下内容的负载：

• token：要撤销的OAuth2访问令牌。
• token_type_hint => 'access_token'，表示正在撤销访问令牌。

负载可以以application/x-www-form-urlencoded或JSON格式交付。

访问测试资源

当您获得有效的令牌时，您可以访问受限制的API资源。OAuth2模块附带一个可使用URL/oauth/resource访问的测试资源。这是一个返回JSON数据的简单资源。

要访问测试资源，您可以使用以下HTTPie命令。

http -f POST http://<URL of your ZF2 app>/oauth/resource access_token=000ab5afab4cbbbda803fb9e50e7943f5e766748
# or
http http://<<URL of your ZF2 app>/oauth/resource "Authorization:Bearer 000ab5afab4cbbbda803fb9e50e7943f5e766748"

如您所见，OAuth2模块支持通过POST使用access_token值或使用Bearer授权头传递数据。

如何使用OAuth2保护您的API

您可以使用以下代码（例如，在控制器的顶部）来保护您的API。

if (!$this->server->verifyResourceRequest(OAuth2Request::createFromGlobals())) {
    // Not authorized return 401 error
    $this->getResponse()->setStatusCode(401);
    return;
}

其中$this->server是OAuth2\Server的一个实例（请参阅AuthController.php）。