README

🇷🇺 俄罗斯公民

我们，Laminas的参与者，来自不同的国家。我们中许多人有在俄罗斯和乌克兰的朋友、亲属和同事。我们中的一些人生于俄罗斯。我们中的一些人现在住在俄罗斯。我们中的一些祖父母在二战中与法西斯作战。在这里，没有人支持法西斯主义。

我们中的一位成员有一位乌克兰亲属，她和儿子一起逃离了家园。火车因为前方的轰炸而延误。我们有一些朋友躲在防空洞里。我们在空袭后焦虑地等待他们的消息，空袭不分青红皂白地攻击医院、学校、幼儿园和住宅。我们不从任何媒体上得知这些消息。这是我们的亲身经历。

您足够信任我们，使用我们的程序，我们请求您再次信任我们。我们需要您的帮助。走出去，抗议这场无意义的战争。停止杀戮。说“不，战争！”

🇺🇸 致俄罗斯公民

我们在Laminas来自世界各地。我们中许多人有在俄罗斯和乌克兰的朋友、家人和同事。我们中的一些人生于俄罗斯。我们中的一些人现在住在俄罗斯。我们中的一些祖父母在二战中与纳粹作战。在这里，没有人支持法西斯主义。

我们中的一位成员有一位乌克兰亲属，她和儿子一起逃离了家园。火车因为前方的轰炸而延误。我们有一些朋友躲在防空洞里。我们在空袭后焦虑地等待他们的消息，空袭不分青红皂白地攻击医院、学校、幼儿园和住宅。我们不从任何媒体上得知这些消息。这是我们的亲身经历。

您足够信任我们，使用我们的软件。我们要求您信任我们，说出真相。我们需要您的帮助。走出去，抗议这场不必要的战争。停止杀戮。说“停止战争！”

Laminas模块，用于OAuth2身份验证。

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

要求

请参阅composer.json文件。

安装

您可以使用以下命令进行安装

$ composer require laminas-api-tools/api-tools-oauth2

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

$ composer require alcaeus/mongo-php-adapter

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

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

laminas-component-installer

如果您使用laminas-component-installer，该插件将自动安装api-tools-oauth2及其其他Laminas API Tools依赖项作为模块。

配置

本模块使用任何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算法（通过类bcrypt和Laminas\Crypt\Password\Bcrypt）加密了字段client_secret（表oauth_clients）和password（表oauth_users）。

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

我们还包含了一个SQLite数据库，位于data/dbtest.sqlite，您可以在测试环境中使用它。在这个数据库中，您将找到一个具有client_id "testclient"和client_secret "testpass"的测试客户端账户。如果您想使用此数据库，可以按照以下方式配置您的config/autoload/oauth2.local.php文件

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

Mongo配置

Mongo OAuth2适配器通过添加与api-tools相同的密码加密来包装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路由。这将把user_id存储在access_token、refresh_token和authorization_code表中，用户在oauth2过程中进行。

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

默认用户ID提供者使用请求查询参数user_id，并由类Laminas\ApiTools\OAuth2\Provider\UserId\Request处理。

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

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

如何测试OAuth2

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

因为我们使用bcrypt算法加密密码，所以您需要使用Laminas中的Laminas\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"。

请求令牌（client_credentials）

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

http --auth testclient:testpass -f POST http://<URL of your Laminas 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连接。

AUTHORIZE (代码)

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

http://<URL of your Laminas 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 Laminas app>/oauth grant_type=authorization_code&code=YOUR_CODE&redirect_uri=/oauth/receivecode

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

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

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

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

http://<URL of your Laminas 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));

REVOKE (代码)

从版本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 Laminas app>/oauth/resource access_token=000ab5afab4cbbbda803fb9e50e7943f5e766748
# or
http http://<<URL of your Laminas 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）。