Merge pull request #2793 from greew/ticket_2788/azure_xoauth2

Added Azure XOAUTH2 help and examples

composer.json

@@ -48,6 +48,7 @@
     },
     "suggest": {
         "ext-mbstring": "Needed to send email in multibyte encoding charset or decode encoded addresses",
+        "greew/oauth2-azure-provider": "Needed for Microsoft Azure XOAUTH2 authentication",
         "hayageek/oauth2-yahoo": "Needed for Yahoo XOAUTH2 authentication",
         "league/oauth2-google": "Needed for Google XOAUTH2 authentication",
         "psr/log": "For optional PSR-3 debug logging",

examples/azure_xoauth2.phps

@@ -0,0 +1,126 @@
+<?php
+
+/**
+ * This example shows how to send via Microsoft Outlook's servers using XOAUTH2 authentication
+ * using the league/oauth2-client to provide the OAuth2 token.
+ * To use a different OAuth2 library create a wrapper class that implements OAuthTokenProvider and
+ * pass that wrapper class to PHPMailer::setOAuth().
+ */
+
+//Import PHPMailer classes into the global namespace
+use PHPMailer\PHPMailer\PHPMailer;
+use PHPMailer\PHPMailer\SMTP;
+use PHPMailer\PHPMailer\OAuth;
+//Alias the League Google OAuth2 provider class
+use Greew\OAuth2\Client\Provider\Azure;
+
+//SMTP needs accurate times, and the PHP time zone MUST be set
+//This should be done in your php.ini, but this is how to do it if you don't have access to that
+date_default_timezone_set('Etc/UTC');
+
+//Load dependencies from composer
+//If this causes an error, run 'composer install'
+require '../vendor/autoload.php';
+
+//Create a new PHPMailer instance
+$mail = new PHPMailer();
+
+//Tell PHPMailer to use SMTP
+$mail->isSMTP();
+
+//Enable SMTP debugging
+//SMTP::DEBUG_OFF = off (for production use)
+//SMTP::DEBUG_CLIENT = client messages
+//SMTP::DEBUG_SERVER = client and server messages
+$mail->SMTPDebug = SMTP::DEBUG_SERVER;
+
+//Set the hostname of the mail server
+$mail->Host = 'smtp.office365.com';
+
+//Set the SMTP port number:
+// - 465 for SMTP with implicit TLS, a.k.a. RFC8314 SMTPS or
+// - 587 for SMTP+STARTTLS
+$mail->Port = 587;
+
+//Set the encryption mechanism to use:
+// - SMTPS (implicit TLS on port 465) or
+// - STARTTLS (explicit TLS on port 587)
+$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
+
+//Whether to use SMTP authentication
+$mail->SMTPAuth = true;
+
+//Set AuthType to use XOAUTH2
+$mail->AuthType = 'XOAUTH2';
+
+//Start Option 1: Use league/oauth2-client as OAuth2 token provider
+//Fill in authentication details here
+//Either the microsoft account owner, or the user that gave consent
+$email = 'someone@somemicrosoftaccount.com';
+$clientId = 'RANDOMCHARS-----duv1n2TS';
+$clientSecret = 'RANDOMCHARS-----lGyjPcRtvP';
+$tenantId = 'RANDOMCHARS-----HSFTAOIlagss';
+
+//Obtained by configuring and running get_oauth_token.php
+//after setting up an app in Google Developer Console.
+$refreshToken = 'RANDOMCHARS-----DWxgOvPT003r-yFUV49TQYag7_Aod7y0';
+
+//Create a new OAuth2 provider instance
+$provider = new Azure(
+    [
+        'clientId' => $clientId,
+        'clientSecret' => $clientSecret,
+        'tenantId' => $tenantId,
+    ]
+);
+
+//Pass the OAuth provider instance to PHPMailer
+$mail->setOAuth(
+    new OAuth(
+        [
+            'provider' => $provider,
+            'clientId' => $clientId,
+            'clientSecret' => $clientSecret,
+            'refreshToken' => $refreshToken,
+            'userName' => $email,
+        ]
+    )
+);
+//End Option 1
+
+//Option 2: Another OAuth library as OAuth2 token provider
+//Set up the other oauth library as per its documentation
+//Then create the wrapper class that implementations OAuthTokenProvider
+$oauthTokenProvider = new MyOAuthTokenProvider(/* Email, ClientId, ClientSecret, etc. */);
+
+//Pass the implementation of OAuthTokenProvider to PHPMailer
+$mail->setOAuth($oauthTokenProvider);
+//End Option 2
+
+//Set who the message is to be sent from
+//For Outlook, this generally needs to be the same as the user you logged in as
+$mail->setFrom($email, 'First Last');
+
+//Set who the message is to be sent to
+$mail->addAddress('someone@someserver.com', 'John Doe');
+
+//Set the subject line
+$mail->Subject = 'PHPMailer Outlook XOAUTH2 SMTP test';
+
+//Read an HTML message body from an external file, convert referenced images to embedded,
+//convert HTML into a basic plain-text alternative body
+$mail->CharSet = PHPMailer::CHARSET_UTF8;
+$mail->msgHTML(file_get_contents('contentsutf8.html'), __DIR__);
+
+//Replace the plain text body with one created manually
+$mail->AltBody = 'This is a plain-text message body';
+
+//Attach an image file
+$mail->addAttachment('images/phpmailer_mini.png');
+
+//send the message, check for errors
+if (!$mail->send()) {
+    echo 'Mailer Error: ' . $mail->ErrorInfo;
+} else {
+    echo 'Message sent!';
+}

get_oauth_token.php

@@ -44,6 +44,8 @@ use League\OAuth2\Client\Provider\Google;
 use Hayageek\OAuth2\Client\Provider\Yahoo;
 //@see https://github.com/stevenmaguire/oauth2-microsoft
 use Stevenmaguire\OAuth2\Client\Provider\Microsoft;
+//@see https://github.com/greew/oauth2-azure-provider
+use Greew\OAuth2\Client\Provider\Azure;
 
 if (!isset($_GET['code']) && !isset($_POST['provider'])) {
     ?>
@@ -57,11 +59,14 @@ if (!isset($_GET['code']) && !isset($_POST['provider'])) {
     <label for="providerYahoo">Yahoo</label><br>
     <input type="radio" name="provider" value="Microsoft" id="providerMicrosoft">
     <label for="providerMicrosoft">Microsoft</label><br>
+    <input type="radio" name="provider" value="Azure" id="providerAzure">
+    <label for="providerAzure">Azure</label><br>
     <h1>Enter id and secret</h1>
     <p>These details are obtained by setting up an app in your provider's developer console.
     </p>
     <p>ClientId: <input type="text" name="clientId"><p>
     <p>ClientSecret: <input type="text" name="clientSecret"></p>
+    <p>TenantID (only relevant for Azure): <input type="text" name="tenantId"></p>
     <input type="submit" value="Continue">
 </form>
 </body>
@@ -77,18 +82,22 @@ session_start();
 $providerName = '';
 $clientId = '';
 $clientSecret = '';
+$tenantId = '';
 
 if (array_key_exists('provider', $_POST)) {
     $providerName = $_POST['provider'];
     $clientId = $_POST['clientId'];
     $clientSecret = $_POST['clientSecret'];
+    $tenantId = $_POST['tenantId'];
     $_SESSION['provider'] = $providerName;
     $_SESSION['clientId'] = $clientId;
     $_SESSION['clientSecret'] = $clientSecret;
+    $_SESSION['tenantId'] = $tenantId;
 } elseif (array_key_exists('provider', $_SESSION)) {
     $providerName = $_SESSION['provider'];
     $clientId = $_SESSION['clientId'];
     $clientSecret = $_SESSION['clientSecret'];
+    $tenantId = $_SESSION['tenantId'];
 }
 
 //If you don't want to use the built-in form, set your client id and secret here
@@ -130,6 +139,17 @@ switch ($providerName) {
             ]
         ];
         break;
+    case 'Azure':
+        $params['tenantId'] = $tenantId;
+
+        $provider = new Azure($params);
+        $options = [
+            'scope' => [
+                'https://outlook.office.com/SMTP.Send',
+                'offline_access'
+            ]
+        ];
+        break;
 }
 
 if (null === $provider) {