Why another WordPress mail plugin?!

Unlike other WordPress email relay plugins, WP Office 365 Mail uses a different authentication protocol than SMTP to connect to Microsoft’s mail servers. This is because Microsoft has disabled basic authentication (username and password) over the SMTP protocol, requiring more modern and secure methods of authentication such as OAuth 2.0 (the protocol used by this plugin).

Without going into too much detail, OAuth 2.0 requires the Client (in this case our WordPress Plugin) to request a set of keys to our mail server, using the five pieces of information outlined below. Unlike a username and password, one of the returned keys expires after a set amount of time, requiring a new set of keys to be issued by an authentication server, using the second key, Client ID and Client Secret to approve the issuing of a new set of keys without further input (login) of said user.

  • Client ID: this lets Microsoft know which authentication server to go to to authenticate the client
  • Client Secret: this is a unique key linked to your Microsoft Account that should only be held by trusted clients. It allows Microsoft to know that the client is genuine and has permission to request the keys for the requested resource (in this case our Microsoft mail server)
  • Tenancy ID: this is a unique key to identify either our Office 365 business account, or personal account.
  • Redirect URI: this is the location to which the keys are returned by the authorisation server once successful authentication has occurred.
  • Scope Permissions: these define the level of access the returned keys will have to the requested resource

Great, so what are the prerequisites?

To start using WP Office 365 Mail, you need to setup a Microsoft Azure Active Directory account. Azure Active Directory comes in several different flavours (paid and free), but it is possible to use the free tier for the purpose of this plugin. The free version of Azure Active Directory is available to both personal and business accounts (e.g. Outlook, Hotmail, Live, Exchange Server and Office 365). You can register for this here: https://azure.microsoft.com/en-gb/services/active-directory/.

So what Microsoft Account should I use?

You will need to decide which Microsoft account you’ll use to send emails from WordPress. For personal accounts this is simple, as there is only one possible account. However, businesses will likely have several potential accounts to choose from, as well as shared mailboxes. It is worth pointing out at this point, that currently the plugin is not able to send email on behalf of other users in an organisation (although this feature may be added at a later point). This means that shared mailboxes cannot currently be used by this plugin.

Whilst there are ways of getting around this limitation, direct access of a shared mailbox through creation of a shared mailbox password is unsupported by Microsoft and considered insecure, so we do not advise this.

Plugin Setup

Step 1 – navigating to the plugin settings

Once you have installed and activated the plugin, you will need to navigate to the plugin settings page. This can be found under the WordPress settings menu as pictured below (titled ‘Wp Office 365 Mail Settings’):

The page itself looks as follows:

The other steps explain where to get the various required fields. However, for now, please simply copy the ‘Redirect URI’ field value and paste this somewhere so you can refer back to it (as it is required in Step 5 below). Make sure you copy the whole URI (when you click the box it will select the entire URI, highlighting it blue to indicate the selection).

Step 2 – creating and registering the Azure Active Directory Application

Microsoft requires us to register an application that will handle the authentication requests to our mail server. To do this, we need to log into Azure Active Directory and click on ‘App Registrations’ in the right hand column menu. This will present the below screen, with a big blue ‘register an application’ button, or a list of already registered applications.

You can either click the blue register button, or the ‘New registration’ button along the top next to ‘Download (Preview)’ – both will display the below screen. Simply enter a name for the application (it can be anything) and select the support account type from the three options available (the supported account being the account that you wish to send the mail from).

Currently the plugin will only allow one account, and this has to be the account the mail is sent from, rather than sending on behalf of another account (we aim to add this as a feature in future releases).

If account is a personal Outlook account, you only need to choose ‘Personal Microsoft Accounts only’. Similarly if it is a business/organisation account, you can select one of the ‘Accounts in any organisational directory’ options. You don’t have to worry about the ‘any organisation’ aspect, as the Client Secret is what will be used to identify approved Clients. However, we can also choose to restrict access to a specific account, or accounts from a certain domain/tenancy if we wish (something we cover in the optional Step xxx).

Step 3 – creating the Client Secret

As explained in step one, we need a way of identifying that our client is who they say they are, and that they have permission to be issued a key to our mail server. To do this we need to click on the ‘Certificates & Secrets’ menu option within Azure Active Directory as shown below.

You then need to click on the ‘New Client Secret’ button under ‘Client Secrets’, entering a description for the secret within the popup that displays. By default the secret will expire after a year. However, you can set this to ‘never’ if you trust the client (WordPress server). This will avoid you having to remember to setup a new secret after a year or two, updating the plugin settings accordingly. There is a risk to this convenience though, and you need to weight up the pros and cons based on your own security policies within your organisation.

Once you’ve decided on the expiry length, click add and the secret will be displayed for you to copy as shown below.

Please note that this secret should not be shared publicly and must be kept securely and only shared with trusted Clients! The secret will only be displayed once within the certificates and secrets section of Azure Active directory, and you will not be able to copy it again once you reload the page. It is important therefore that you store it somewhere secure, or save it within the plugins settings straight away! If you forget the secret and you require it again, you would need to delete the previous secret and recreate it, following the same process.

Paste the Client Secret into the appropriate area of the plugins settings page (you should have this open from Step 1 above). Do not click the blue save button on the plugin settings page just yet, as we still need to paste in the Client ID and Tennant ID that we will get in Step 4 below. Given that you’re not saving the settings just yet, you’ll need to keep the settings page open and not reload the page until you’ve added the Client ID and Tennant ID from Step 4.

Step 4 – copying the Client ID and Tenant ID to the plugin settings

To get the Client ID and Tenant ID, we need to navigate to the ‘Overview’ page of our Azure Active Directory Application. Here you will find both the Client ID and Tenant ID. If you’ve closed the application page from Step 3, you can get to this again by logging back into Azure Active Directory, navigating to ‘App registrations’, and then clicking on your application from the shown list (as outlined in Step 2 above).

The overview page looks as follows. We have circled both the Client ID and Tenant ID which will be unique to your own application. These need to be copied in full and pasted into the plugin settings page from Step 1.

Once you’ve added these to the settings page (including the Client Secret from Step 3), you need to make sure you click the blue ‘Save’ button on the plugin settings page (see Step 1) to ensure the plugin settings are saved securely.

Step 5 – setting the application platform & Redirect URI

We now need to add the ‘Redirect URI’ we copied from Step 1 to our Azure Active Directory Application. To do this we need to navigate the ‘Authentication’ page of our app as shown below. You may have to click ‘Add a platform’ as pictured, in which case you need to select the ‘Web’ option under the ‘Configure platforms’ window that appears once the ‘Add a platform’ button is clicked.

The next window that appears after selecting ‘Web’ looks as follows. This is where you need to paste the ‘Redirect URI’ and then click ‘Configure’. You can ignore the ‘Logout URL’ and ‘Implicit Grant’ options.

Step 6 – setting the application permissions

The next step is to set the access permissions for the application, to ensure we are only granting access to the required services (in this case the ability to Send and Email through Microsoft’s servers using our Microsoft Account).

To do this we need to navigate to ‘API Permissions’ page, clicking on the ‘Add a permission’ option and then choosing the ‘Microsoft Graph’ option as pictured below:

At this point the following window appears where we can select our required permissions. We need to make sure we have chosen ‘Delegated’ rather than ‘Application’ permissions as shown:

You need to ensure the following permissions are checked before clicking the ‘Add Permissions’ button:

  • OpenId permissions -> email
  • OpenId permissions -> offline_access
  • OpenId permissions -> openid
  • OpenId permissions -> profile
  • Mail -> Mail.Send
  • User -> User.Read

Step 7 – authorising WordPress to use your Microsoft Account

The final required step is to authorise your WordPress installation to use your Microsoft Account to send email. To do this we need to go back to the plugin settings page within the WordPress administration area (as explained in Step 1).

Provided you have followed Steps 1 – 6 above, you should now see an ‘authorise’ button as pictured below. When you click this you will be redirected to a login page where you need to enter the login details for your chosen Microsoft Account (the account you wish your emails to be sent from).

Top Tip! If you are set to use a different Microsoft Account to your own (for example [email protected], rather than [email protected]). If you save your Microsoft Account credentials in your browser (i.e. [email protected] in this case), you should make sure you open a new in-private/incognito browser window before logging in to WordPress and navigating to the plugin settings. This will ensure that when you click the authorise button on the plugin settings page, you are prompted for the credentials of the account you wish to use (i.e. [email protected] in this example), rather than logging you in automatically with your own saved account credentials and linking WordPress to the wrong account!

Step 8 (optional) – account restriction

Given that this plugin can only currently work with one account, you can if you wish, ensure that only this account can authenticate with WordPress by restricting the Active Directory Application to that user.

To do this you need to login to Azure Active Directory and navigate to ‘Enterprise Applications’ as pictured below. Note this is a separate area to ‘App registrations’!