Update passport.md

Adds docs for Authentication code with PKCE Grant - laravel/passport#1065

Author: filipegar

passport.md

@@ -12,6 +12,9 @@
     - [Managing Clients](#managing-clients)
     - [Requesting Tokens](#requesting-tokens)
     - [Refreshing Tokens](#refreshing-tokens)
+- [Authorization Code Grant with PKCE](#code-grant-pkce)
+    - [Creating A Authorization Code Grant with PKCE](#creating-a-auth-pkce-grant-client)
+    - [Requesting Tokens](#requesting-auth-pkce-grant-tokens)
 - [Password Grant Tokens](#password-grant-tokens)
     - [Creating A Password Grant Client](#creating-a-password-grant-client)
     - [Requesting Tokens](#requesting-password-grant-tokens)
@@ -454,6 +457,82 @@ If your application issues short-lived access tokens, users will need to refresh
 
 This `/oauth/token` route will return a JSON response containing `access_token`, `refresh_token`, and `expires_in` attributes. The `expires_in` attribute contains the number of seconds until the access token expires.
 
+<a name="code-grant-pkce"></a>
+## Authorization Code Grant with PKCE
+
+The Authorization Code with Proof Key for Code Exchange (PKCE) is the preferred way for  the front end (e.g. a single page web application) or a native application such as a mobile app to access an API. This grant should be used when you can't guarantee that the client secret will be stored confidentiality or when mitigating the threat of having the authorization code intercepted by an attacker. A combination of a code verifier and a code challenge replaces the client secret when exchanging the authorization code for an access token.
+
+<a name="creating-a-auth-pkce-grant-client"></a>
+### Creating A Authorization Code Grant with PKCE
+
+Before your application can issue tokens via the authorization code grant with PKCE, you will need to create a PKCE-enabled client. You may do this using the `passport:client` command with the `--public` option:
+
+    php artisan passport:client --public
+
+<a name="requesting-auth-pkce-grant-tokens"></a>
+### Requesting Tokens
+
+#### Code verifier and Code challenge
+
+As this authorization grant does not provide a client secret, developers will need to generate a combination of code verifier and code challenge to be able to request a token.
+
+The code verifier is recommended to be a random, case insensitive string of with a minimum length of 43 characters and a maximum length of 128 characters created with letters, numbers and  `"-"`, `"."`, `"_"`, `"~"`, as defined in the [RFC 7636 specification](https://tools.ietf.org/html/rfc7636).
+
+The code challenge should be created using a Base64 encoding with URL and filename-safe characters, with all trailing `'='` characters omitted and without the inclusion of any line breaks, whitespace, or other additional characters.
+
+    $code_challenge = strtr(rtrim(base64_encode(hash('sha256', $code_verifier, true)), '='), '+/', '-_');
+
+#### Redirecting For Authorization
+
+Once a client has been created, developers may use their client ID and a generated code verifier and a code challenge 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 (Request $request) {
+        $request->session()->put('state', $state = Str::random(40));
+        $request->session()->put('code_verifier', $code_verifier = Str::random(128));
+
+        $code_challenge = strtr(rtrim(base64_encode(hash('sha256', $code_verifier, true)), '='), '+/', '-_');
+
+        $query = http_build_query([
+            'client_id' => 'client-id',
+            'redirect_uri' => 'http://example.com/callback',
+            'response_type' => 'code',
+            'scope' => '',
+            'state' => $state,
+            'code_challenge' => $code_challenge,
+            'code_challenge_method' => 'S256',
+        ]);
+
+        return redirect('http://your-app.com/oauth/authorize?'.$query);
+    });
+
+#### 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 verify the `state` parameter against the value that was stored prior to the redirect, as in the standard Authorization Code Grant. 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 along with the originally generated code verifier.
+
+    Route::get('/callback', function (Request $request) {
+        $state = $request->session()->pull('state');
+        $code_verifier = $request->session()->pull('code_verifier');
+
+        throw_unless(
+            strlen($state) > 0 && $state === $request->state,
+            InvalidArgumentException::class
+        );
+
+        $http = new GuzzleHttp\Client;
+
+        $response = $http->post('http://your-app.com/oauth/token', [
+            'form_params' => [
+                'grant_type' => 'authorization_code',
+                'client_id' => 'client-id',
+                'redirect_uri' => 'http://example.com/callback',
+                'code_verifier' => $code_verifier,
+                'code' => $request->code,
+            ],
+        ]);
+
+        return json_decode((string) $response->getBody(), true);
+    });
+
 <a name="password-grant-tokens"></a>
 ## Password Grant Tokens