Skip to content

Commit c699e1b

Browse files
weierophinneyweierophinney
committedNov 16, 2017
Documents the component
·
2.0.00.1.0
1 parent 1837a79 commit c699e1b

File tree

6 files changed

+263
-5
lines changed

6 files changed

+263
-5
lines changed
 

‎README.md

+17-1
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,16 @@
33
[![Build Status](https://secure.travis-ci.org/phly/phly-expressive-oauth2clientauthentication.svg?branch=master)](https://secure.travis-ci.org/phly/phly-expressive-oauth2clientauthentication)
44
[![Coverage Status](https://coveralls.io/repos/github/phly/phly-expressive-oauth2clientauthentication/badge.svg?branch=master)](https://coveralls.io/github/phly/phly-expressive-oauth2clientauthentication?branch=master)
55

6-
This library provides ...
6+
This library provides a [league/oauth2-client](http://oauth2-client.thephpleague.com)
7+
adapter for use with [zend-expressive-authentication](https://docs.zendframework.com/zend-expressive-authentication).
8+
It currently supports only the OAuth2 providers officially maintained by that
9+
project, including:
10+
11+
- Facebook
12+
- GitHub
13+
- Google
14+
- Instagram
15+
- LinkedIn
716

817
## Installation
918

@@ -13,6 +22,13 @@ Run the following to install this library:
1322
$ composer require phly/phly-expressive-oauth2clientauthentication
1423
```
1524

25+
You will also need to install one or more of the OAuth2 providers you wish to
26+
use. As an example:
27+
28+
```bash
29+
$ composer require league/oauth2-instagram league/oauth2-google league/oauth2-facebook
30+
```
31+
1632
## Documentation
1733

1834
Documentation is [in the doc tree](docs/book/), and can be compiled using [mkdocs](http://www.mkdocs.org):

‎docs/book/config.md

+167
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Configuration
2+
3+
In order to use this authentication adapter, you will need to provide
4+
configuration for the OAuth2 providers you plan to use.
5+
6+
Examples are provided in the `config/` directory of this component, and repeated
7+
here for purposes of documentation:
8+
9+
## Global configuration
10+
11+
This is configuration that should be present no matter what environment you are
12+
in, and it covers the base path for the OAuth2 client callbacks and debug
13+
provider URIs.
14+
15+
```php
16+
// e.g. config/autoload/oauth2-client.global.php:
17+
18+
return [
19+
'oauth2clientauthentication' => [
20+
// Configure the base path for all OAuth2 client callbacks. By default,
21+
// this is "/auth".
22+
// 'auth_path' => '/auth',
23+
24+
// Configure the production and debug routes for OAuth2 client callbacks
25+
// if desired. These strings will be relative to the 'auth_path' config
26+
// as specified above.
27+
'routes' => [
28+
// Production path.
29+
// 'production' => '/{provider:facebook|github|google|instagram}|linkedin[/oauth2callback]',
30+
31+
// Debug path.
32+
// 'debug' => '/{provider:debug|facebook|github|google|instagram|linkedin}[/oauth2callback]',
33+
],
34+
],
35+
];
36+
```
37+
38+
## Local/Environment-specific configuration
39+
40+
This is configuration for the providers you wish to enable. You will need to
41+
review the [league/oauth2-client providers documentation](http://oauth2-client.thephpleague.com/providers/league/
42+
for links to both full configuration documentation, as well as resources on how
43+
to obtain the various client identifiers and secrets you will need to use.
44+
45+
This information should _not_ be shipped directly in your repository, but rather
46+
included as part of your application environment.
47+
48+
```php
49+
// e.g. config/autoload/oauth2-client.local.php:
50+
51+
return [
52+
'oauth2clientauthentication' => [
53+
// Debug
54+
// This is the debug provider shipped within this component for purposes
55+
// of testing the OAuth2 client workflow within your applications.
56+
'debug' => [
57+
// Provide this if you have provided an alternate route path via
58+
// the oauth2clientauthentication.routes.debug key:
59+
// 'callback_uri_template' => '/alternate/debug/callback?code=%s&state=%s',
60+
61+
// Provide this if you want to use an alternate path for the OAuth2
62+
// "server" authorization:
63+
// 'authorization_url' => '/alternate/debug/authorization',
64+
],
65+
66+
// Facebook
67+
// 'facebook' => [
68+
// 'clientId' => '{facebook-app-id}',
69+
// 'clientSecret' => '{facebook-app-secret}',
70+
// 'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
71+
// 'graphApiVersion' => 'v2.10',
72+
// ],
73+
74+
// GitHub
75+
// 'github' => [
76+
// 'clientId' => '{github-client-id}',
77+
// 'clientSecret' => '{github-client-secret}',
78+
// 'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
79+
// ],
80+
81+
// Google
82+
// 'google' => [
83+
// 'clientId' => '{google-client-id}',
84+
// 'clientSecret' => '{google-client-secret}',
85+
// 'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
86+
// 'hostedDomain' => '', // scheme + domain of your app
87+
// ],
88+
89+
// Instagram
90+
// 'instagram' => [
91+
// 'clientId' => '{instagram-client-id}',
92+
// 'clientSecret' => '{instagram-client-secret}',
93+
// 'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
94+
// 'host' => 'https://api.instagram.com', // Optional; this is the default
95+
// ],
96+
97+
// LinkedIn
98+
// 'linkedin' => [
99+
// 'clientId' => '{linkedin-client-id}',
100+
// 'clientSecret' => '{linkedin-client-secret}',
101+
// 'redirectUri' => '', // based on the auth_path + production route; must be fully qualifed
102+
// ],
103+
],
104+
'dependencies' => [
105+
'factories' => [
106+
// Enable this when in debug mode:
107+
// Debug\DebugProviderMiddleware::class => Debug\DebugProviderMiddlewareFactory::class,
108+
],
109+
],
110+
];
111+
```
112+
113+
## Pipeline configuration
114+
115+
The various callbacks operate under a base path as specified by the
116+
`oauth2clientauthentication.auth_path` configuration, which defaults to `/auth`.
117+
You will need to pipe the `Phly\Expressive\OAuth2ClientAuthentication\OAuth2CallbackMiddleware`
118+
service to that path:
119+
120+
```php
121+
// In config/pipeline.php:
122+
123+
use Phly\Expressive\OAuth2ClientAuthentication\OAuth2CallbackMiddleware;
124+
125+
$app->pipe('/auth', OAuth2CallbackMiddleware::class);
126+
```
127+
128+
@todo Detail how to pipe the callback middleware when using other middleware frameworks.
129+
130+
## Route configuration
131+
132+
Once the above is complete, you can add
133+
`Zend\Expressive\Authentication\AuthenticationMiddleware` to your route-specific
134+
pipelines. You will also need to pipe
135+
`Zend\Expressive\Session\SessionMiddleware` in these pipelines as this adapter
136+
persists user information within the session.
137+
138+
As an example:
139+
140+
```php
141+
// In config/routes.php
142+
143+
use Zend\Expressive\Authentication\AuthenticationMiddleware;
144+
use Zend\Expressive\Session\SessionMiddleware;
145+
146+
$app->post('/api/books', [
147+
SessionMiddleware::class,
148+
AuthenticationMiddleware::class,
149+
CreateBookHandler::class,
150+
]);
151+
```
152+
153+
> ### Create a delegator factory
154+
>
155+
> You may want to consider creating a delegator factory for registering these
156+
> two middleware in a pipeline with any handler. As an example:
157+
>
158+
> ```php
159+
> function (ContainerInterface $container, $serviceName, callable $callback)
160+
> {
161+
> $pipeline = new MiddlewarePipe();
162+
> $pipeline->pipe($container->get(SessionMiddleware::class));
163+
> $pipeline->pipe($container->get(AuthenticationMiddleware::class));
164+
> $pipeline->pipe($callback());
165+
> return $pipeline;
166+
> }
167+
> ```

‎docs/book/debug.md

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# The Debug Provider
2+
3+
OAuth2 providers generally require that requests for the registered client come
4+
from a specific domain — and this can be problematic when testing your
5+
OAuth2 client workflow or pages behind authentication.
6+
7+
To help solve this problem, this package provides a custom league/oauth2-client
8+
provider, `Phly\Expressive\OAuth2ClientAuthentication\Debug\DebugProvider`,
9+
along with an associated "authorization" handler.
10+
11+
These features are only enabled when you enable the application `debug` flag;
12+
when that occurs, the debug provider is added to the list of allowed providers,
13+
and its authorization handler is mapped to a route.
14+
15+
You can configure both the authorization URI as well as the template for the
16+
callback URI:
17+
18+
```php
19+
// e.g. config/autoload/oauth2-client.local.php:
20+
21+
return [
22+
'oauth2clientauthentication' => [
23+
'debug' => [
24+
// Provide this if you have provided an alternate route path via
25+
// the oauth2clientauthentication.routes.debug key:
26+
// 'callback_uri_template' => '/alternate/debug/callback?code=%s&state=%s',
27+
28+
// Provide this if you want to use an alternate path for the OAuth2
29+
// "server" authorization:
30+
// 'authorization_url' => '/alternate/debug/authorization',
31+
],
32+
],
33+
];
34+
```

‎docs/book/index.html

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<div class="jumbotron">
33
<h1>phly/phly-expressive-oauth2clientauthentication</h1>
44

5-
<p>Description of component here</p>
5+
<p>league/oauth2-client adapter for zend-expressive-authentication</p>
66

77
<pre><code class="language-bash">$ composer require phly/phly-expressive-oauth2clientauthentication</code></pre>
88
</div>

‎docs/book/intro.md

+40-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,42 @@
11
# phly-expressive-oauth2clientauthentication
22

3-
This component provides ...
3+
This library provides a [league/oauth2-client](http://oauth2-client.thephpleague.com)
4+
adapter for use with [zend-expressive-authentication](https://docs.zendframework.com/zend-expressive-authentication).
5+
It currently supports only the OAuth2 providers officially maintained by that
6+
project, including:
7+
8+
- Facebook
9+
- GitHub
10+
- Google
11+
- Instagram
12+
- LinkedIn
13+
14+
## Installation
15+
16+
Install via Composer:
17+
18+
```bash
19+
$ composer require phly/phly-expressive-oauth2clientauthentication
20+
```
21+
22+
If you are using the [zend-component-installer Composer
23+
plugin](https://docs.zendframework.com/zend-component-installer/),
24+
this will automatically register the shipped `ConfigProvider` with your
25+
application, as well as those of its dependencies (including
26+
zend-expressive-authentication and zend-expressive-session). If you are not, you
27+
will need to use the shipped
28+
`Phly\Expressive\OAuth2ClientAuthentication\ConfigProvider` to add configuration
29+
to your application:
30+
31+
```php
32+
use Phly\Expressive\OAuth2ClientAuthentication\ConfigProvider;
33+
34+
return (new ConfigProvider())();
35+
```
36+
37+
You will also need to install one or more of the OAuth2 providers you wish to
38+
use. As an example:
39+
40+
```bash
41+
$ composer require league/oauth2-instagram league/oauth2-google league/oauth2-facebook
42+
```

‎mkdocs.yml

+4-2
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,9 @@ site_dir: docs/html
33
pages:
44
- index.md
55
- Introduction: intro.md
6-
site_name: Component Name Goes Here
7-
site_description: 'Component Description goes here'
6+
- Configuration: config.md
7+
- "Debug Provider": debug.md
8+
site_name: 'phly'
9+
site_description: 'league/oauth2-client adapter for zend-expressive-authentication'
810
repo_url: 'https://github.com/phly/phly-expressive-oauth2clientauthentication'
911
copyright: 'Copyright (c) 2017 <a href="http://www.zend.com/">Zend Technologies USA Inc.</a>'

0 commit comments

Comments
 (0)
Please sign in to comment.