Merge pull request KnpLabs#439 from naderman/t/integrations

Accessing the API as an integration

Author: cursedcoder

doc/README.md

@@ -7,6 +7,7 @@ APIs:
 * [Enterprise](enterprise.md)
 * [Gists](gists.md)
   * [Comments](gists/comments.md)
+* [Integrations](integrations.md)
 * [Issues](issues.md)
   * [Comments](issue/comments.md)
   * [Labels](issue/labels.md)

doc/integrations.md

@@ -0,0 +1,15 @@
+## Instegrations API
+[Back to the navigation](README.md)
+
+Wraps [GitHub Integrations API](http://developer.github.com/v3/integrations/).
+
+### Create a new installation token
+For the installation id 123 use the following:
+```php
+$token = $client->api('integrations')->createInstallationToken(123);
+```
+
+To create an access token on behalf of a user with id 456 use:
+```php
+$token = $client->api('integrations')->createInstallationToken(123, 456);
+```

doc/security.md

@@ -13,15 +13,17 @@ $client->authenticate($usernameOrToken, $password, $method);
 ```
 
 `$usernameOrToken` is, of course, the username (or in some cases token/client ID, more details you can find below),
-and guess what should contain `$password`. The `$method` can contain one of the three allowed values:
+and guess what should contain `$password`. The `$method` can contain one of the five allowed values:
 
 * `Github\Client::AUTH_URL_TOKEN`
 * `Github\Client::AUTH_URL_CLIENT_ID`
 * `Github\Client::AUTH_HTTP_TOKEN`
 * `Github\Client::AUTH_HTTP_PASSWORD`
+* `Github\Client::AUTH_JWT`
 
-The required value of `$password` depends on the chosen `$method`. For the `Github\Client::AUTH_*_TOKEN` methods,
-you should provide the API token in `$username` variable (`$password` is omitted in this particular case). For the
+The required value of `$password` depends on the chosen `$method`. For `Github\Client::AUTH_URL_TOKEN`,
+`Github\Client::AUTH_HTTP_TOKEN` and `Github\Client::JWT` methods you should provide the API token in
+`$username` variable (`$password` is omitted in this particular case). For the
 `Github\Client::AUTH_HTTP_PASSWORD`, you should provide the password of the account. When using `Github\Client::AUTH_URL_CLIENT_ID`
 `$usernameOrToken` should contain your client ID, and `$password` should contain client secret.
 
@@ -32,10 +34,37 @@ all further requests are done as the given user.
 
 The `Github\Client::AUTH_URL_TOKEN` authentication method sends the API token in URL parameters.
 The `Github\Client::AUTH_URL_CLIENT_ID` authentication method sends the client ID and secret in URL parameters.
-The `Github_Client::AUTH_HTTP_*` authentication methods send their values to GitHub using HTTP Basic Authentication.
+The `Github\Client::AUTH_HTTP_*` authentication methods send their values to GitHub using HTTP Basic Authentication.
+The `Github\Client::AUTH_JWT` authentication method sends the specified JSON Web Token in an Authorization header.
 
 `Github\Client::AUTH_URL_TOKEN` used to be the only available authentication method. To prevent existing applications
 from changing their behavior in case of an API upgrade, this method is chosen as the default for this API implementation.
 
 Note however that GitHub describes this method as deprecated. In most case you should use the
 `Github\Client::AUTH_HTTP_TOKEN` instead.
+
+### Authenticating as an Integration
+
+To authenticate as an integration you need to supply a JSON Web Token with `Github\Client::AUTH_JWT` to request
+and installation access token which is then usable with `Github\Client::AUTH_HTTP_TOKEN`. [Github´s integration
+authentication docs](https://developer.github.com/early-access/integrations/authentication/) describe the flow in detail.
+It´s important for integration requests to use the custom Accept header `application/vnd.github.machine-man-preview`.
+
+The following sample code authenticates as an installation using [lcobucci/jwt](https://github.com/lcobucci/jwt/tree/3.2.0)
+to generate a JSON Web Token (JWT).
+
+```php
+$github = new Github\Client(new GuzzleClient(), 'machine-man-preview');
+
+$jwt = (new Builder)
+    ->setIssuer($integrationId)
+    ->setIssuedAt(time())
+    ->setExpiration(time() + 60)
+    ->sign(new Sha256(),  (new Keychain)->getPrivateKey($pemPrivateKeyPath))
+    ->getToken();
+
+$github->authenticate($jwt, null, Github\Client::AUTH_JWT);
+
+$token = $github->api('integrations')->createInstallationToken($installationId);
+$github->authenticate($token['token'], null, Github\Client::AUTH_HTTP_TOKEN);
+```

lib/Github/Api/Integrations.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Github\Api;
+
+/**
+ * @link   https://developer.github.com/v3/integrations/
+ * @author Nils Adermann <naderman@naderman.de>
+ */
+class Integrations extends AbstractApi
+{
+    /**
+     * Create an access token for an installation
+     *
+     * @param int $installationId An integration installation id
+     * @param int $userId         An optional user id on behalf of whom the
+     *                            token will be requested
+     *
+     * @return array token and token metadata
+     */
+    public function createInstallationToken($installationId, $userId = null)
+    {
+        $parameters = array();
+        if ($userId) {
+            $parameters['user_id'] = $userId;
+        }
+
+        return $this->post('/installations/'.rawurlencode($installationId).'/access_tokens', $parameters);
+    }
+}

lib/Github/Client.php

@@ -86,6 +86,12 @@ class Client
      */
     const AUTH_HTTP_TOKEN = 'http_token';
 
+    /**
+     * Constant for authentication method. Indicates JSON Web Token
+     * authentication required for integration access to the API.
+     */
+    const AUTH_JWT = 'jwt';
+
     /**
      * @var string
      */
@@ -204,6 +210,11 @@ public function api($name)
                 $api = new Api\Gists($this);
                 break;
 
+            case 'integration':
+            case 'integrations':
+                $api = new Api\Integrations($this);
+                break;
+
             case 'issue':
             case 'issues':
                 $api = new Api\Issue($this);
@@ -293,7 +304,7 @@ public function authenticate($tokenOrLogin, $password = null, $authMethod = null
             throw new InvalidArgumentException('You need to specify authentication method!');
         }
 
-        if (null === $authMethod && in_array($password, array(self::AUTH_URL_TOKEN, self::AUTH_URL_CLIENT_ID, self::AUTH_HTTP_PASSWORD, self::AUTH_HTTP_TOKEN))) {
+        if (null === $authMethod && in_array($password, array(self::AUTH_URL_TOKEN, self::AUTH_URL_CLIENT_ID, self::AUTH_HTTP_PASSWORD, self::AUTH_HTTP_TOKEN, self::AUTH_JWT))) {
             $authMethod = $password;
             $password   = null;
         }

lib/Github/HttpClient/Plugin/Authentication.php

@@ -71,6 +71,10 @@ public function handleRequest(RequestInterface $request, callable $next, callabl
                 $request = $request->withUri($uri);
                 break;
 
+            case Client::AUTH_JWT:
+                $request = $request->withHeader('Authorization', sprintf('Bearer %s', $this->tokenOrLogin));
+                break;
+
             default:
                 throw new RuntimeException(sprintf('%s not yet implemented', $this->method));
                 break;