Skip to content

Commit 2e7193d

Browse files
kamermanskamermans
committed
Expanded README
1 parent 06343a8 commit 2e7193d

File tree

1 file changed

+139
-3
lines changed

1 file changed

+139
-3
lines changed

‎README.md

+139-3
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,26 @@
11
# Guzzle OAuth 2.0 Subscriber
22

3+
> [![Build Status](https://travis-ci.org/kamermans/guzzle-oauth2-subscriber.svg?branch=master)](https://travis-ci.org/kamermans/guzzle-oauth2-subscriber)
4+
> Tested with Guzzle 4, 5, 6 and PHP 5.4, 5.5, 5.6, 7.0, 7.1 and HHVM
5+
36
This is an OAuth 2.0 client for Guzzle which aims to be 100% compatible with Guzzle 4, 5, 6 and all future versions within a single package.
47
Although I love Guzzle, its interfaces keep changing, causing massive breaking changes every 12 months or so, so I have created this package
58
to help reduce the dependency hell that most third-party Guzzle dependencies bring with them. I wrote the official Guzzle OAuth 2.0 plugin
69
which is still on the `oauth2` branch, [over at the official Guzzle repo](https://github.com/guzzle/oauth-subscriber/tree/oauth2), but I
710
see that they have dropped support for Guzzle < v6 on `master`, which prompted me to split this back off to a separate package.
811

9-
## Installing
12+
## Features
13+
14+
- Acquires access tokens via one of the supported grant types (code, client credentials,
15+
user credentials, refresh token). Or you can set an access token yourself.
16+
- Supports refresh tokens (stores them and uses them to get new access tokens).
17+
- Handles token expiration (acquires new tokens and retries failed requests).
18+
- Allows storage and lookup of access tokens via callbacks
19+
1020

11-
This project can be installed using Composer. Add the following to your
12-
`composer.json`:
21+
## Installation
22+
23+
This project can be installed using Composer. Run `composer require kamermans/guzzle-oauth-subscriber` or add the following to your `composer.json`:
1324

1425
```javascript
1526
{
@@ -18,3 +29,128 @@ This project can be installed using Composer. Add the following to your
1829
}
1930
}
2031
```
32+
33+
## Usage
34+
35+
This plugin integrates seamlessly with Guzzle, transparently adding authentication to outgoing requests and optionally attempting re-authorization if the access token is no longer valid.
36+
37+
There are multiple grant types available like `PasswordCredentials`, `ClientCredentials` and `AuthorizationCode`.
38+
39+
### Guzzle 4 & 5 vs Guzzle 6+
40+
With the Guzzle 6 release, most of the library was refactored or completely rewritten, and as such, the integration of this library is different.
41+
42+
#### Emitters (Guzzle 4 & 5)
43+
Guzzle 4 & 5 use **Event Subscribers**, and this library incudes `OAuth2Subscriber` for that purpose:
44+
45+
```php
46+
$oauth = new OAuth2Subscriber($grant_type);
47+
48+
$client = new Client([
49+
'auth' => 'oauth',
50+
]);
51+
52+
$client->getEmitter()->attach($oauth);
53+
```
54+
55+
#### Middleware (Guzzle 6+)
56+
Starting with Guzzle 6, **Middleware** is used to integrate OAuth, and this library includes `OAuthMiddleware` for that purpose:
57+
58+
```php
59+
$oauth = new OAuth2Middleware($grant_type);
60+
61+
$stack = HandlerStack::create();
62+
$stack->push($oauth);
63+
64+
$client = new Client([
65+
'auth' => 'oauth',
66+
'handler' => $stack,
67+
]);
68+
```
69+
70+
### Client Credentials Example
71+
Client credentials are normally used in server-to-server authentication. With this grant type, a client is requesting authorization in its own behalf, so there are only two parties involved. At a minimum, a `client_id` and `client_secret` are required, although many services require a `scope` and other parameters.
72+
73+
Here's an example of the client credentials method in Guzzle 4 and Guzzle 5:
74+
75+
```php
76+
use kamermans\OAuth2\GrantType\ClientCredentials;
77+
use kamermans\OAuth2\OAuth2Subscriber;
78+
79+
// Authorization client - this is used to request OAuth access tokens
80+
$reauth_client = new GuzzleHttp\Client([
81+
// URL for access_token request
82+
'base_url' => 'http://some_host/access_token_request_url',
83+
]);
84+
$reauth_config = [
85+
"client_id" => "your client id",
86+
"client_secret" => "your client secret",
87+
"scope" => "your scope(s)", // optional
88+
"state" => time(), // optional
89+
];
90+
$grant_type = new ClientCredentials($reauth_client, $reauth_config);
91+
$oauth = new OAuth2Subscriber($grant_type);
92+
93+
// This is the normal Guzzle client that you use in your application
94+
$client = new GuzzleHttp\Client([
95+
'auth' => 'oauth',
96+
]);
97+
$client->getEmitter()->attach($oauth);
98+
$response = $client->get('http://somehost/some_secure_url');
99+
100+
echo "Status: ".$response->getStatusCode()."\n";
101+
```
102+
103+
Here's the same example for Guzzle 6+:
104+
105+
```php
106+
use kamermans\OAuth2\GrantType\ClientCredentials;
107+
use kamermans\OAuth2\OAuthMiddleware;
108+
109+
// Authorization client - this is used to request OAuth access tokens
110+
$reauth_client = new GuzzleHttp\Client([
111+
// URL for access_token request
112+
'base_uri' => 'http://some_host/access_token_request_url',
113+
]);
114+
$reauth_config = [
115+
"client_id" => "your client id",
116+
"client_secret" => "your client secret",
117+
"scope" => "your scope(s)", // optional
118+
"state" => time(), // optional
119+
];
120+
$grant_type = new ClientCredentials($reauth_client, $reauth_config);
121+
$oauth = new OAuth2Middleware($grant_type);
122+
123+
$stack = HandlerStack::create();
124+
$stack->push($oauth);
125+
126+
// This is the normal Guzzle client that you use in your application
127+
$client = new GuzzleHttp\Client([
128+
'handler' => $stack,
129+
'auth' => 'oauth',
130+
]);
131+
132+
$response = $client->get('http://somehost/some_secure_url');
133+
134+
echo "Status: ".$response->getStatusCode()."\n";
135+
```
136+
137+
### Grant Types
138+
The following OAuth grant types are supported directly, and you can always create your own by implementing `kamermans\OAuth2\GrantType\GrantTypeInterface`:
139+
- `AuthorizationCode`
140+
- `ClientCredentials`
141+
- `PasswordCredentials`
142+
- `RefreshToken`
143+
144+
Each of these takes a Guzzle client as the first argument. This client is used to obtain or refresh your OAuth access token, out of band from the other requests you are making.
145+
146+
147+
### Access Token Persistence
148+
> Note: OAuth Access tokens should be stored somewhere securely and/or encrypted. If an attacker gains access to your access token, they could have unrestricted access to whatever resources and scopes were allowed!
149+
150+
By default, access tokens are not persisted anywhere. There are some built-in mechanisms for caching / persisting tokens (in `kamermans\OAuth2\Persistence`):
151+
- `NullTokenPersistence` (default) Disables persistence
152+
- `FileTokenPersitence` Takes the path to a file in which the access token will be saved.
153+
- `DoctrineCacheTokenPersistence` Takes a `Doctrine\Common\Cache\Cache` object and optionally a key name (default: `guzzle-oauth2-token`) where the access token will be saved.
154+
155+
If you want to use your own persistence layer, you should write your own class that implements `TokenPersistenceInterface`.
156+

0 commit comments

Comments
 (0)