README

这是 dormilich/http-client（包括）的 OAuth2 扩展，用于使用 客户端凭据 授权方案。

主要用途是后端 API 通信，其中资源消费者（后端服务）是资源所有者（通过为资源授予永久凭证）的受信任客户端。

安装

您可以通过 composer 安装此库

composer require dormilich/http-oauth

要使用此库，安装您个人选择的 PSR-16 缓存。另外，父库需要 PSR-18 HTTP 客户端和 PSR-17 HTTP 工厂。

配置

HTTP 客户端配置

此配置在相应项目中进行了描述。

缓存配置

缓存组件没有特定于项目的配置。

OAuth 配置

由于 OAuth2 可能导致预检请求，因此需要配置 HTTP 客户端。

use Dormilich\HttpClient\Client;
use Dormilich\HttpClient\Transformer\JsonDecoder;
use Dormilich\HttpClient\Transformer\JsonEncoder;
use Dormilich\HttpOauth\TokenClient;
use Dormilich\HttpOauth\TokenProvider;
use Dormilich\HttpOauth\Credentials\ClientCredentials;
use Dormilich\HttpOauth\Credentials\DefaultProvider;
use Dormilich\HttpOauth\Encoder\AuthorisationEncoder;

// replace this with the actual implementations
$httpClient = new HttpClient();         // PSR-18
$requestFactory = new RequestFactory(); // PSR-17
$streamFactory = new StreamFactory();   // PSR-17
$simpleCache = new SimpleCache();       // PSR-16

// define your OAuth credentials
$credentials = new ClientCredentials('<client-id>', '<client-secret>', '<authorisation-url>');
// use a credentials provider
$provider = new DefaultProvider($credentials);

// set up the extension
# the token client is responsible for making the authorisation requests
$tokenClient = new TokenClient($provider, $httpClient, $requestFactory, $streamFactory);
# the token provider is a Facade for getting the OAuth token
# either from a persistence layer or the authorisation server
$tokenProvider = new TokenProvider($tokenClient, $simpleCache);
# the request processor for the HTTP client 
$authorisation = new AuthorisationEncoder($tokenProvider);

// set up the HTTP client
$client = new Client($httpClient, $requestFactory, $streamFactory);
// add OAuth extension
$client->addEncoder($authorisation);
// add more encoders/decoders as necessary, e.g.
$client->addTransformer(new JsonEncoder());
$client->addTransformer(new JsonEncoder());

根据 OAuth 规范，令牌不需要定义过期时间。在这种情况下，令牌可能会变得过时，资源请求可能会因 403 未授权响应（或类似响应）而失败。如果发现令牌已过期，扩展将在尝试资源请求之前获取新的令牌。

凭据

扩展支持在同一个 HTTP 客户端中使用多个 OAuth 凭据。

预定义的凭据提供者是

• DefaultProvider：为每个资源请求返回相同的凭据。
• DomainProvider：根据资源请求 URL 的（部分）域名返回凭据。
• ChainProvider：多个提供者的聚合器。

如果找不到资源请求 URL 的凭据，则不会向资源请求添加授权头。

示例

use Dormilich\HttpOauth\Credentials\ChainProvider;
use Dormilich\HttpOauth\Credentials\ClientCredentials;
use Dormilich\HttpOauth\Credentials\DefaultProvider;
use Dormilich\HttpOauth\Credentials\DomainProvider;

$credentials = new ClientCredentials('<client-id>', '<client-secret>', '<outhorisation-url>');

$default = new DefaultProvider($credentials);

// return credentials when requesting authorisation for "example.com" and
// its subdomains like "api.example.com" as well as "api.example.org" (etc.)
$domain = new DomainProvider();
$domain->add($credentials, ['example.com', 'api.example.org']);

$chain = new ChainProvider([$domain, $default]);