Support for client certificate flow introduced, validate token response

Author: vgrem

composer.json

@@ -22,7 +22,8 @@
         "ext-json": "*",
         "ext-simplexml": "*",
         "ext-dom": "*",
-        "ext-libxml": "*"
+        "ext-libxml": "*",
+        "firebase/php-jwt": "*"
     },
     "require-dev": {
         "phpunit/phpunit": "^9"

examples/SharePoint/ConnectWithCert.php

@@ -0,0 +1,38 @@
+<?php
+
+/**
+ * Demonstrates how to authenticate SharePoint API via client certificate flow
+ *
+ * Steps:
+ * 1. generate Self-Signed SSL Certificate
+ *    - generate a private key:  openssl genrsa -out private.key 2048
+ *    - generate a public key:  openssl req -new -x509 -key private.key -out publickey.cer -days 365
+ * 2. upload the publickey.cer to your app in the Azure portal
+ * 3. note the displayed thumbprint for the certificate
+ * 4. initialize ClientContext instance and pass thumbprint and the contents of private.key
+ *    along with tenantName and clientId into withClientCertificate method
+ *
+ * Documentation: https://learn.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azuread
+ */
+
+require_once __DIR__ . '/../vendor/autoload.php';
+$settings = include(__DIR__ . './../../tests/Settings.php');
+
+use Office365\Runtime\Auth\ClientCredential;
+use Office365\SharePoint\ClientContext;
+
+try {
+
+    $thumbprint = "054343442AC255DD07488910C7E000F92227FD98";
+    $privateKey = file_get_contents("./private.key");
+
+    $credentials = new ClientCredential($settings['ClientId'], $settings['ClientSecret']);
+    $ctx = (new ClientContext($settings['Url']))->withClientCertificate(
+        $settings['TenantName'], $settings['ClientId'], $privateKey, $thumbprint);
+
+    $whoami = $ctx->getWeb()->getCurrentUser()->get()->executeQuery();
+    print $whoami->getLoginName();
+}
+catch (Exception $e) {
+	echo 'Authentication failed: ',  $e->getMessage(), "\n";
+}

examples/SharePoint/DocSet/Create.php

@@ -0,0 +1,36 @@
+<?php
+require_once '../../vendor/autoload.php';
+$settings = include('../../../tests/Settings.php');
+
+use Office365\Runtime\Auth\ClientCredential;
+use Office365\SharePoint\ClientContext;
+use Office365\SharePoint\DocumentManagement\DocumentSet\DocumentSet;
+
+$credentials = new ClientCredential($settings['ClientId'], $settings['ClientSecret']);
+$siteUrl = $settings['TeamSiteUrl'];
+$client = (new ClientContext($siteUrl))->withCredentials($credentials);
+
+//$docSetName = "DocSet_" . rand(1, 100000);
+
+$docSetName = "Customers";
+$lib = $client->getWeb()->getLists()->getByTitle("HRDocs");
+$docSet = DocumentSet::create($client, $lib->getRootFolder(), $docSetName)->executeQuery();
+print($docSet->getProperty("ServerRelativeUrl"));
+
+
+//2. retrieve document set by url (document sets addressed bý folder url)
+$docSetUrl = "/sites/team/Shared Documents/Customers";
+$docSet = $client->getWeb()->getFolderByServerRelativeUrl($docSetUrl)->get()->executeQuery();
+
+
+//3. update document set
+$folderUrl = "/sites/team/Shared Documents/Customers";
+$docSet = $client->getWeb()->getFolderByServerRelativeUrl($folderUrl);
+$docSet->getListItemAllFields()->setProperty("CustomerType", "New")->update()->executeQuery();
+
+
+//4. delete document set
+$docSetUrl = "/sites/team/Shared Documents/Customers";
+$docSet = $client->getWeb()->getFolderByServerRelativeUrl($docSetUrl);
+$docSet->deleteObject()->executeQuery();
+

examples/composer.json

@@ -2,7 +2,8 @@
   "name": "vgrem/php-spo-examples",
   "description": "Examples that demonstrate how to utilize library",
   "require": {
-    "fzaninotto/faker": "*"
+    "fzaninotto/faker": "*",
+    "firebase/php-jwt": "*"
   },
   "autoload": {
     "psr-4": {

src/GraphServiceClient.php

@@ -23,6 +23,7 @@
 use Office365\Runtime\Actions\UpdateEntityQuery;
 use Office365\Runtime\Http\RequestOptions;
 use Office365\Teams\TeamCollection;
+use RuntimeException;
 
 
 /**
@@ -157,10 +158,22 @@ public function getServiceRootUrl()
     public function authenticateRequest(RequestOptions $options)
     {
         $token = call_user_func($this->acquireTokenFunc, $this);
+        $this->validateToken($token);
         $headerVal = $token['token_type'] . ' ' . $token['access_token'];
         $options->ensureHeader('Authorization', $headerVal);
     }
 
+    private function validateToken($accessToken){
+        if (isset($accessToken['error'])) {
+            $message = $accessToken['error'];
+
+            if (isset($accessToken['error_description'])) {
+                $message .= PHP_EOL . $accessToken['error_description'];
+            }
+            throw new RuntimeException($message);
+        }
+    }
+
 
     /**
      * @var ODataRequest $pendingRequest

src/Runtime/Auth/AADTokenProvider.php

@@ -4,6 +4,7 @@
 namespace Office365\Runtime\Auth;
 
 use Exception;
+use Firebase\JWT\JWT;
 use Office365\Runtime\Http\HttpMethod;
 use Office365\Runtime\Http\RequestOptions;
 use Office365\Runtime\Http\Requests;
@@ -20,6 +21,13 @@ class AADTokenProvider extends BaseTokenProvider
      */
     private static $TokenEndpoint = '/oauth2/token';
 
+
+    /**
+     * @var string
+     */
+    private static $TokenEndpointV2 = '/oauth2/v2.0/token';
+
+
     /**
      * @var string
      */
@@ -45,6 +53,10 @@ public function __construct($tenant)
         $this->authorityUrl = self::$AuthorityUrl . $tenant;
     }
 
+    public function getTokenUrl($useV2){
+        return $this->authorityUrl . ($useV2 ?  self::$TokenEndpointV2:  self::$TokenEndpoint);
+    }
+
 
     /**
      * @param string $resource
@@ -87,6 +99,36 @@ public function acquireTokenForClientCredential($resource, $clientCredentials, $
     }
 
 
+    /**
+     * @param CertificateCredentials $credentials
+     * @throws Exception
+     */
+    public function acquireTokenForClientCertificate($credentials){
+        $header = [
+            'x5t' => base64_encode(hex2bin($credentials->Thumbprint)),
+        ];
+        $now = time();
+        $payload = [
+            'aud' => $this->getTokenUrl(true),
+            'exp' => $now + 360,
+            'iat' => $now,
+            'iss' => $credentials->ClientId,
+            'jti' => bin2hex(random_bytes(20)),
+            'nbf' => $now,
+            'sub' => $credentials->ClientId,
+        ];
+        $jwt = JWT::encode($payload, str_replace('\n', "\n", $credentials->PrivateKey), 'RS256', null, $header);
+
+        $params['client_assertion_type'] = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer';
+        $params['client_assertion'] = $jwt;
+        $params['grant_type'] = "client_credentials";
+        $params['scope'] = implode(" ", $credentials->Scope);
+
+        return $this->acquireToken($params, true);
+    }
+
+
+
     /**
      * @param string $resource
      * @param string $clientId
@@ -140,24 +182,26 @@ public function acquireTokenByAuthorizationCode($resource, $clientId, $clientSec
     /**
      * Acquires the access token
      * @param array $parameters
+     * @param bool $useV2
      * @return mixed
      * @throws Exception
      */
-    public function acquireToken($parameters)
+    public function acquireToken($parameters, $useV2=false)
     {
-        $request = $this->prepareTokenRequest($parameters);
+        $request = $this->prepareTokenRequest($parameters, $useV2);
         $response = Requests::execute($request);
         $response->validate();
         return $this->normalizeToken($response->getContent());
     }
 
     /**
-     * @param $parameters
+     * @param array $parameters
+     * @param bool $useV2
      * @return RequestOptions
      */
-    private function prepareTokenRequest($parameters)
+    private function prepareTokenRequest($parameters, $useV2)
     {
-        $tokenUrl = $this->authorityUrl . self::$TokenEndpoint;
+        $tokenUrl = $this->getTokenUrl($useV2);
         $request = new RequestOptions($tokenUrl);
         $request->ensureHeader('content-Type', 'application/x-www-form-urlencoded');
         $request->Method = HttpMethod::Post;

src/Runtime/Auth/AuthenticationContext.php

@@ -2,7 +2,6 @@
 
 namespace Office365\Runtime\Auth;
 
-
 use Exception;
 use Office365\Runtime\Http\RequestOptions;
 
@@ -49,7 +48,7 @@ public function __construct($authorityUrl)
     }
 
     /**
-     * @param ClientCredential|UserCredentials $credential
+     * @param ClientCredential|UserCredentials|CertificateCredentials $credential
      */
     public function registerProvider($credential)
     {
@@ -58,14 +57,16 @@ public function registerProvider($credential)
                 $this->acquireTokenForUser($credential->Username, $credential->Password);
             elseif ($credential instanceof ClientCredential)
                 $this->acquireAppOnlyAccessToken($credential->ClientId, $credential->ClientSecret);
+            elseif ($credential instanceof CertificateCredentials)
+                $this->acquireAppOnlyAccessTokenWithCert($credential);
             else
                 throw new Exception("Unknown credentials");
         };
     }
 
 
     /**
-     * @var string
+     * @param string $value
      */
     public function setAccessToken($value)
     {
@@ -105,6 +106,19 @@ public function acquireAppOnlyAccessToken($clientId, $clientSecret){
         ));
     }
 
+    /**
+     * Acquire App-Only access token via client certificate flow
+     * @param CertificateCredentials $credentials
+     * @throws Exception
+     */
+    public function acquireAppOnlyAccessTokenWithCert($credentials){
+        if(!isset($credentials->Scope)){
+            $credentials->Scope[] = "{$this->authorityUrl}/.default";
+        }
+        $this->provider = new AADTokenProvider($credentials->Tenant);
+        $this->accessToken = $this->provider->acquireTokenForClientCertificate($credentials);
+    }
+
 
 
     /**
@@ -132,6 +146,7 @@ public function authenticateRequest(RequestOptions $request)
     /**
      * Ensures Authorization header is set
      * @param RequestOptions $options
+     * @throws Exception
      */
     protected function ensureAuthorizationHeader(RequestOptions $options)
     {

src/Runtime/Auth/CertificateCredentials.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Office365\Runtime\Auth;
+
+class CertificateCredentials
+{
+
+    /**
+     * @param string $tenant
+     * @param string $clientId
+     * @param string $privateKey
+     * @param string $thumbprint
+     * @param string[] $scope
+     */
+    public function __construct($tenant, $clientId, $privateKey, $thumbprint, $scope=null)
+    {
+        $this->Tenant = $tenant;
+        $this->ClientId = $clientId;
+        $this->PrivateKey = $privateKey;
+        $this->Thumbprint = $thumbprint;
+        $this->Scope = $scope;
+    }
+
+
+    /**
+     * @var string $Tenant
+     */
+    public $Tenant;
+
+    /**
+     * @var string $ClientId
+     */
+    public $ClientId;
+
+    /**
+     * @var string $PrivateKey
+     */
+    public $PrivateKey;
+
+    /**
+     * @var string $Thumbprint
+     */
+    public $Thumbprint;
+
+    /**
+     * @var string[] $Scope
+     */
+    public $Scope;
+
+}

src/SharePoint/ClientContext.php

@@ -4,6 +4,7 @@
 
 use Exception;
 use Office365\Runtime\Auth\AuthenticationContext;
+use Office365\Runtime\Auth\CertificateCredentials;
 use Office365\Runtime\Auth\ClientCredential;
 use Office365\Runtime\Auth\IAuthenticationContext;
 use Office365\Runtime\Auth\NetworkCredentialContext;
@@ -22,6 +23,7 @@
 use Office365\SharePoint\Search\SearchService;
 use Office365\SharePoint\Taxonomy\TaxonomyService;
 use Office365\SharePoint\UserProfiles\PeopleManager;
+use function PHPUnit\Framework\throwException;
 
 /**
  * Client context for SharePoint API service
@@ -144,6 +146,16 @@ public function withCredentials($credential)
         return $this;
     }
 
+    /**
+     * @return ClientContext
+     */
+    public function withClientCertificate($tenant, $clientId, $privateKey, $thumbprint, $scopes=null){
+        $this->authContext = new AuthenticationContext($this->baseUrl);
+        $this->authContext->registerProvider(
+            new CertificateCredentials($tenant, $clientId, $privateKey, $thumbprint, $scopes));
+        return $this;
+    }
+
     /**
      * NTLM authentication flow (for SharePoint On-Premises)
      * @param UserCredentials $credential