Merge pull request #5363 from matt-allan/passport-state-param

Use the state parameter in Passport examples

passport.md

@@ -342,12 +342,15 @@ This route is used to delete clients:
 
 Once a client has been created, developers may use their client ID and secret to request an authorization code and access token from your application. First, the consuming application should make a redirect request to your application's `/oauth/authorize` route like so:
 
-    Route::get('/redirect', function () {
+    Route::get('/redirect', function (Request $request) {
+        $request->session()->put('state', $state = Str::random(40));
+
         $query = http_build_query([
             'client_id' => 'client-id',
             'redirect_uri' => 'http://example.com/callback',
             'response_type' => 'code',
             'scope' => '',
+            'state' => $state,
         ]);
 
         return redirect('http://your-app.com/oauth/authorize?'.$query);
@@ -386,9 +389,13 @@ Sometimes you may wish to skip the authorization prompt, such as when authorizin
 
 #### Converting Authorization Codes To Access Tokens
 
-If the user approves the authorization request, they will be redirected back to the consuming application. The consumer should then issue a `POST` request to your application to request an access token. The request should include the authorization code that was issued by your application when the user approved the authorization request. In this example, we'll use the Guzzle HTTP library to make the `POST` request:
+If the user approves the authorization request, they will be redirected back to the consuming application. The consumer should first verify the `state` parameter against the value that was stored prior to the redirect. If the state parameter matches the consumer should issue a `POST` request to your application to request an access token. The request should include the authorization code that was issued by your application when the user approved the authorization request. In this example, we'll use the Guzzle HTTP library to make the `POST` request:
 
     Route::get('/callback', function (Request $request) {
+        $state = $request->session()->pull('state');
+
+        throw_unless(strlen($state) > 0 && $state === $request->state, InvalidArgumentException::class);
+
         $http = new GuzzleHttp\Client;
 
         $response = $http->post('http://your-app.com/oauth/token', [
@@ -559,12 +566,15 @@ The implicit grant is similar to the authorization code grant; however, the toke
 
 Once a grant has been enabled, developers may use their client ID to request an access token from your application. The consuming application should make a redirect request to your application's `/oauth/authorize` route like so:
 
-    Route::get('/redirect', function () {
+    Route::get('/redirect', function (Request $request) {
+        $request->session()->put('state', $state = Str::random(40));
+
         $query = http_build_query([
             'client_id' => 'client-id',
             'redirect_uri' => 'http://example.com/callback',
             'response_type' => 'token',
             'scope' => '',
+            'state' => $state,
         ]);
 
         return redirect('http://your-app.com/oauth/authorize?'.$query);