[DOCS] Added OAuth2 section under Authentication

Basic examples for 2 and 3-legged flows.

ref: #34

Author: vimishor

docs/examples/authentication.md

@@ -44,8 +44,80 @@ http client with oauth credentials before making a request.
   $response = $user->get();
   ```
 
+### OAuth2 authorization
+
+You can use `OAuth2Listener` in order to make authorized requests using version 2 of OAuth protocol.
+
+#### OAuth2 client credentials (_2-legged flow_)
+
+  ```php
+  // @see: https://bitbucket.org/account/user/<username or team>/api
+  $oauth_params = array(
+      'client_id'         => 'aaa',
+      'client_secret'     => 'bbb'
+  );
+
+  $bitbucket = new \Bitbucket\API\Api();
+  $bitbucket->getClient()->addListener(
+      new \Bitbucket\API\Http\Listener\OAuth2Listener($oauth_params)
+  );
+
+  $repositories = $bitbucket->api('Repositories');
+  $response     = $repositories->all('my_account'); // should include private repositories
+  ```
+
+#### OAuth2 Authorization code (_3-legged flow_)
+
+You can use any 3rd party library to complete this [flow][3] and set `access_token` option when you instantiate `OAuth2Listener`.
+
+In the following example [PHP League's OAuth 2.0 Client][1] is used with [Bitbucket Provider][2].
+
+  ```php
+  session_start();
+
+  $provider = new Stevenmaguire\OAuth2\Client\Provider\Bitbucket([
+      'clientId'          => $_ENV['bitbucket_consumer_key'],
+      'clientSecret'      => $_ENV['bitbucket_consumer_secret'],
+      'redirectUri'       => 'http://example.com/bitbucket_login.php'
+  ]);
+  if (!isset($_GET['code'])) {
+
+      // If we don't have an authorization code then get one
+      $authUrl = $provider->getAuthorizationUrl();
+      $_SESSION['oauth2state'] = $provider->getState();
+      header('Location: '.$authUrl);
+      exit;
+
+  // Check given state against previously stored one to mitigate CSRF attack
+  } elseif (empty($_GET['state']) || ($_GET['state'] !== $_SESSION['oauth2state'])) {
+
+      unset($_SESSION['oauth2state']);
+      exit('Invalid state');
+
+  } else {
+
+      // Try to get an access token (using the authorization code grant)
+      $token = $provider->getAccessToken('authorization_code', [
+          'code' => $_GET['code']
+      ]);
+
+      $bitbucket = new Bitbucket\API\Repositories();
+      $bitbucket->getClient()->addListener(
+          new \Bitbucket\API\Http\Listener\OAuth2Listener(
+              array('access_token'  => $token->getToken())
+          )
+      );
+
+      echo $bitbucket->all('my_account')->getContent(); // should include private repositories
+  }
+  ```
+
 ----
 
 #### Related:
   * [Authentication @ BB Wiki](https://confluence.atlassian.com/display/BITBUCKET/Use+the+Bitbucket+REST+APIs#UsetheBitbucketRESTAPIs-Authentication)
   * [OAuth on Bitbucket @ BB Wiki](https://confluence.atlassian.com/display/BITBUCKET/OAuth+on+Bitbucket)
+
+[1]: http://oauth2-client.thephpleague.com/
+[2]: https://github.com/stevenmaguire/oauth2-bitbucket
+[3]: http://oauthbible.com/#oauth-2-three-legged