Skip to content

Commit b016cce

Browse files
author
Luca Degasperi
committed
Huge documentation improvements
1 parent 7201a0d commit b016cce

File tree

3 files changed

+217
-7
lines changed

3 files changed

+217
-7
lines changed

‎README.md‎

Lines changed: 188 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,9 +53,195 @@ This package comes with all the migrations you need to run a full featured oauth
5353
php artisan migrate --package="lucadegasperi/oauth2-server-laravel"
5454
```
5555

56-
## Issuing access tokens
56+
## Issuing an access token
57+
58+
You can use different grant types to issue an access token depending on which suits your use cases. A detailed description of the different grant types can be found [here](https://github.com/php-loep/oauth2-server/wiki/Which-OAuth-2.0-grant-should-I-use%3F)
59+
60+
A client should make a ```POST``` request with the appropriate parameters (depending on the grant type used) to an access token endpoint like the one defined here. This package will take care of all the fuss for you.
61+
62+
```php
63+
Route::post('oauth/access_token', function()
64+
{
65+
return AuthorizationServer::performAccessTokenFlow();
66+
});
67+
```
68+
69+
### Authorization Code flow
70+
71+
The most common grant type is the ```authorization_code```. It's also the longest to setup, but don't worry, it will be easy.
72+
73+
First the client must obtain the authorization (not an access token) from the resource owner to access the resources on its behalf. The client application should redirect the user to the authorization page with the correct query string parameters, for example:
74+
75+
```
76+
https://www.example.com/oauth/authorize?
77+
client_id=the_client_id&
78+
redirect_uri=client_redirect_uri&
79+
response_type=code&
80+
scope=scope1,scope2&
81+
state=1234567890
82+
```
83+
84+
```php
85+
Route::get('/oauth/authorize', array('before' => 'check-authorization-params|auth', function()
86+
{
87+
// get the data from the check-authorization-params filter
88+
$params['client_id'] = Session::get('client_id');
89+
$params['client_details'] = Session::get('client_details');
90+
$params['redirect_uri'] = Session::get('redirect_uri');
91+
$params['response_type'] = Session::get('response_type');
92+
$params['scopes'] = Session::get('scopes');
93+
$params['state'] = Session::get('state');
94+
95+
// get the user id
96+
$params['user_id'] = Auth::user()->id;
97+
98+
// display the authorization form
99+
return View::make('authorization-form', array('params' => $params));
100+
}));
101+
```
102+
103+
```php
104+
Route::post('/oauth/authorize', array('before' => 'check-authorization-params|auth|csrf', function()
105+
{
106+
// get the data from the check-authorization-params filter
107+
$params['client_id'] = Session::get('client_id');
108+
$params['client_details'] = Session::get('client_details');
109+
$params['redirect_uri'] = Session::get('redirect_uri');
110+
$params['response_type'] = Session::get('response_type');
111+
$params['scopes'] = Session::get('scopes');
112+
$params['state'] = Session::get('state');
113+
114+
// get the user id
115+
$params['user_id'] = Auth::user()->id;
116+
117+
// check if the user approved or denied the authorization request
118+
if (Input::get('approve') !== null) {
119+
120+
$code = AuthorizationServer::getGrantType('authorization_code')->newAuthoriseRequest('user', $params['user_id'], $params);
121+
122+
// not appropriate
123+
Session::flush();
124+
125+
return Redirect::to(
126+
AuthorizationServer::makeRedirect($params['redirect_uri'],
127+
array(
128+
'code' => $code,
129+
'state' => isset($params['state']) ? $params['state'] : ''
130+
)
131+
));
132+
}
133+
134+
if (Input::get('deny') !== null) {
135+
136+
// just for demonstration purposes (you should flush the vars individually)
137+
Session::flush();
138+
139+
return Redirect::to(
140+
AuthorizationServer::makeRedirect($params['redirect_uri'],
141+
array(
142+
'error' => 'access_denied',
143+
'error_message' => AuthorizationServer::getExceptionMessage('access_denied'),
144+
'state' => isset($params['state']) ? $params['state'] : ''
145+
)
146+
));
147+
}
148+
});
149+
```
150+
151+
If the authorization process is successful the client will be redirected to its ```redirect_uri``` parameter with an authorization code in the query string like in the example below
152+
153+
```
154+
https://www.yourclient.com/redirect?code=XYZ123
155+
```
156+
157+
The client can now use this code to make an access token request in the background.
158+
159+
```
160+
POST https://www.example.com/oauth/access_token?
161+
grant_type=authorization_code&
162+
client_id=the_client_id&
163+
client_secret=the_client_secret&
164+
scope=scope1,scope2&
165+
state=123456789
166+
```
167+
168+
### Password flow
169+
170+
This grant type is the easiest to use and is ideal for highly trusted clients. To enable this grant type add the code below to the ```grant_types``` array located at ```app/config/packages/lucadegasperi/oauth2-server-laravel/oauth2.php```
171+
172+
```php
173+
'password' => array(
174+
'class' => 'League\OAuth2\Server\Grant\Password',
175+
'access_token_ttl' => 604800,
176+
'callback' => function($username, $password){
177+
178+
return Auth::validate(array(
179+
'email' => $username,
180+
'password' => $password,
181+
));
182+
}
183+
),
184+
```
185+
An example request for an access token using this grant type might look like this.
186+
187+
```
188+
POST https://www.example.com/oauth/access_token?
189+
grant_type=password&
190+
client_id=the_client_id&
191+
client_secret=the_client_secret&
192+
username=the_username&
193+
password=the_password&
194+
scope=scope1,scope2&
195+
state=123456789
196+
```
197+
198+
### Client Credentials flow
199+
200+
Sometimes the client and the resource owner are the same thing. This grant types allows for client to access your API on their own behalf. To enable this grant type add the code below to the ```grant_types``` array located at ```app/config/packages/lucadegasperi/oauth2-server-laravel/oauth2.php```
201+
202+
```php
203+
'client_credentials' => array(
204+
'class' => 'League\OAuth2\Server\Grant\ClientCredentials',
205+
'access_token_ttl' => 3600,
206+
),
207+
```
208+
209+
An example request for an access token using this grant type might look like this.
210+
211+
```
212+
POST https://www.example.com/oauth/access_token?
213+
grant_type=client_credentials&
214+
client_id=the_client_id&
215+
client_secret=the_client_secret&
216+
scope=scope1,scope2&
217+
state=123456789
218+
```
219+
220+
### Refresh token flow
221+
222+
Access tokens do expire but by using the refresh token flow you can exchange a refresh token for an access token.
223+
When this grant type is enabled, every access token request will also issue a refresh token you can use to get a new access token when the current one expires. Configure this grant type in the ```grant_types``` array located at ```app/config/packages/lucadegasperi/oauth2-server-laravel/oauth2.php``` like this:
224+
225+
```php
226+
'refresh_token' => array(
227+
'class' => 'League\OAuth2\Server\Grant\RefreshToken',
228+
'access_token_ttl' => 3600,
229+
'refresh_token_ttl' => 604800,
230+
'rotate_refresh_tokens' => false,
231+
),
232+
```
233+
234+
An example request for an access token using this grant type might look like this.
235+
236+
```
237+
POST https://www.example.com/oauth/access_token?
238+
grant_type=refresh_token&
239+
refresh_token=the_refresh_token&
240+
client_id=the_client_id&
241+
client_secret=the_client_secret&
242+
state=123456789
243+
```
57244

58-
TBD
59245

60246
## Securing the API endpoints
61247

‎src/LucaDegasperi/OAuth2Server/Facades/AuthorizationServerFacade.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
use Illuminate\Support\Facades\Facade;
44
use League\OAuth2\Server\Util\RedirectUri;
55
use League\OAuth2\Server\Exception\ClientException;
6+
use Exception;
67
use Response;
78

89
class AuthorizationServerFacade extends Facade {

‎src/config/oauth2.php‎

Lines changed: 28 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,34 @@
1111
| you can even provide your own grant type.
1212
| Available grant types are:
1313
|
14-
| League\OAuth2\Server\Grant\AuthCode
15-
| League\OAuth2\Server\Grant\Password
16-
| League\OAuth2\Server\Grant\RefreshToken
17-
| League\OAuth2\Server\Grant\ClientCredentials
18-
| League\OAuth2\Server\Grant\Implicit
14+
| 'grant_types' => array(
15+
|
16+
| 'authorization_code' => array(
17+
| 'class' => 'League\OAuth2\Server\Grant\AuthCode',
18+
| 'access_token_ttl' => 3600,
19+
| 'auth_token_ttl' => 3600,
20+
| ),
21+
|
22+
| 'password' => array(
23+
| 'class' => 'League\OAuth2\Server\Grant\Password',
24+
| 'access_token_ttl' => 604800,
25+
| 'callback' => function($username, $password){
26+
|
27+
| return Auth::validate(array(
28+
| 'email' => $username,
29+
| 'password' => $password,
30+
| ));
31+
| }
32+
| ),
33+
|
34+
| 'refresh_token' => array(
35+
| 'class' => 'League\OAuth2\Server\Grant\RefreshToken',
36+
| 'access_token_ttl' => 3600,
37+
| 'refresh_token_ttl' => 604800,
38+
| 'rotate_refresh_tokens' => false,
39+
| ),
40+
|
41+
| ),
1942
|
2043
*/
2144
'grant_types' => array(

0 commit comments

Comments
 (0)