README

此包提供了 PiPA OpenID 支持，使用 PHP League 的 OAuth 2.0 客户端 和 lcobucci 的 jwt 库。

需求

支持以下版本的 PHP。

• PHP 5.6+
• PHP 7.1+

还必须启用以下模块

• php-mbstring
• php-xml
• php-openssl

安装

要安装，推荐的方式是使用 composer 和将 pipa 仓库添加到你的 composer 文件中。

composer require pipasolutions/openid-client-php

在 PHP 5.* 上，需要额外的步骤，因为 random_bytes 函数不是由核心库提供的。为了解决这个问题，请运行以下命令

composer require "paragonie/random_compat" ">=1 <9.99"

用法

用法遵循 OpenID Connect/OAuth2 标准。请参阅 OpenID Connect 文档 和 OAuth2 文档以获取更多信息。

在您能够使用客户端进行身份验证之前，您需要注册以获取客户端 ID 和密钥。请联系 PiPA 获取更多信息，并获取客户端 ID 和密钥。

如何存储 client_id 和 client_secret 由您选择，但建议不要将它们存储在源代码中。相反，它们（尤其是 client_secret）应该从（受保护的）配置文件或密钥管理系统加载。

执行身份验证请求

您必须初始化 PiPAOpenId 类。

use PiPASolutions\OpenId\PiPAOpenId;

...

$clientId = $secured_credentials['client_id'];
$clientSecret = $secured_credentials['client_secret'];

$oauthServerPath = 'https://path.to/server/'
$redirectUrl = 'https://this.server/login/redirect'

$this->openid = new PiPAOpenId($clientId, $clientSecret, $redirecturl, $oauthServerPath);

重要：请确保 oauthServerPath 是 https。如果它是 http 并进行重定向，客户端可能无法通过身份验证。

oauthServerPath 和 redirectUrl 如上所述。 clientId 和 clientSecret 将由 PiPA 提供，或者是之前通过 clientRegistration 调用并获得并持久化的结果。

要启动登录过程

$this->openid->startAuth();

此调用还具有以下可选参数

1. 用户 ID（字符串）- 关于用户 ID 的提示，如果提供，则仅允许该用户登录
2. 作用域（数组）- 要请求访问的列表作用域
3. 强制配对（布尔值）- 如果为 true，将强制配对而不是允许身份验证请求。仅在需要时使用，建议将用户重定向到 pipa.co/pair

您还必须实现您在 $redirectUrl 中定义的回调 URL 的处理程序。在回调中使用以下内容

$tokens = $this->openid->getTokens($state, $code);

// We have an access token, which we may use in authenticated
// requests against the service provider's API.
echo 'Access Token: ' . $tokens->getAccessToken() . "<br>";
echo 'Refresh Token: ' . $tokens->getRefreshToken() . "<br>";
echo 'Expired in: ' . $tokens->getExpires() . "<br>";
echo 'User id: ' . $tokens->getUserId() . "<br>";
echo 'Already expired? ' . ($tokens->hasExpired() ? 'expired' : 'not expired') . "<br>";

$tokens.getUserId() 将为您提供用户的唯一标识符；这可以用于您的数据库以表示用户，应在后续登录中进行检查。

如果您只是执行登录，其余的方法可能对您并不重要。它们提供各种令牌；访问令牌可用于从服务器请求数据，刷新令牌可用于获取另一个访问令牌，访问令牌在一段时间后过期。OpenID 和 OAuth 文档对此有更详细的说明。

从 $tokens.getUserId() 返回的 userID 可用于在启动登录时在 $this->openid->startAuth(userId) 中进行选择，这样它就不再是接受任何 PiPA 身份验证，而需要特定的用户进行身份验证。

最终，此提供程序将扩展以允许与服务器进行更复杂的交互，包括获取有关用户更多信息。

请求电子邮件地址

要从用户请求电子邮件地址，您必须在调用 openid->startAuth() 时指定电子邮件作用域 - 这将类似于

$openid->startAuth(null, [PiPAOpenIdConstants::SCOPE_EMAIL]);

当指定此选项时，用户将被提示提供电子邮件地址，但可以选择不提供。是否在这种情况下接受认证或拒绝认证由实现者决定。

要获取电子邮件地址，使用 getIdToken() 从令牌数组中获取 Id Token，它返回一个 Token 对象。

$tokens = $this->openid->getTokens($state, $code);
$idToken = $tokens->getIdToken();
if ($idToken->hasClaim(PiPAOpenIdConstants::CLAIM_EMAIL)) {
  $email = $idToken->getClaim(PiPAOpenIdConstants::CLAIM_EMAIL);
  // handle receiving email
} else {
  // handle not receiving email
}

测试

尚未实现！

$ ./vendor/bin/phpunit

许可协议

MIT 许可协议 (MIT)。更多信息请参阅许可文件。