Send email with Microsoft (OAuth 2)

If you wish to enable Microsoft OAuth 2 authentication for your email connection then you will need to enable the OAuth 2 plugin on your Totara site and go to the Microsoft developer console to configure authentication.

Configure the app in the Microsoft Azure portal

1. Go to the Microsoft Azure portal.
2. Click New registration under App registrations.
3. Give your app a name, e.g. 'Totara Email'.
4. Select the appropriate option for Supported account types. Either Accounts in any organizational directory (Any Azure AD directory - Multitenant) or Accounts in this organizational directory only (Single tenant) can be used. Many organisations use Single tenant for security and organisational reasons.
   Note: If Single tenant is selected, the OAuth 2 endpoints configured later in Totara must use the Tenant ID rather than /common/ (see the Single tenant note in the endpoint configuration below).
5. Choose Web for Redirect URI.
6. Add your site's URL appended with /admin/oauth2callback.php to the Redirect URLs section e.g. 'https://totaralearn.com/admin/oauth2callback.php'.
7. Click Register.
8. Take a note of the Application (client) ID. If Single tenant was selected, also take a note of the Directory (tenant) ID.
9. Select Authentication from the side menu.
10. Ensure that the Implicit grant settings are disabled.
11. Select API permissions from the side menu.
12. Ensure that the SMTP.Send and offline_access permissions are available under Microsoft Graph, and if they are not then add them as delegated permissions.
13. Select Certificates & secrets from the side menu and click New client secret.
14. Add a description, e.g. your app name (Totara Email), and select when the password/secret will expire.
15. Copy the generated secret Value for use in Totara. Copy the Value column, not the Secret ID — the value cannot be retrieved again once you navigate away from this page.

Configure the OAuth 2 service in Totara (recommended)

From Totara 18.7 onwards, the OAuth 2 issuers page provides a Create new Microsoft SMTP service option. This option creates the correct endpoints and configures the required scopes automatically, so only the Client ID and Client Secret need to be added.

17. In Totara go to Quick-access menu > Server > OAuth 2 > OAuth 2 consumer details and click Create new Microsoft SMTP service.
18. Enter a name, e.g. 'Microsoft Email OAuth'.
19. Enter the Client ID (the Application (client) ID from Azure) and the Client secret (the secret Value generated in Azure in the previous step, not the Secret ID).
20. Uncheck Show on login page (it is recommended that you do not mix the email and login OAuth services).
21. Click Save changes.

Alternative: create a custom OAuth 2 service manually

If the Create new Microsoft SMTP service option is not available, a custom service can be configured manually. The endpoints and scopes must then be added by hand.

17. In Totara go to Quick-access menu > Server > OAuth 2 > OAuth 2 consumer details.
18. Click Create a new custom service.
19. Enter a name, e.g. 'Microsoft Email OAuth'.
20. Enter the secret Value generated in the Microsoft Azure portal (not the Secret ID) as the Secret and the application ID as the Client ID.
21. In Scopes included in a login request enter any value. This field is not used, but a value must be provided.
22. In Scopes included in a login request for offline access add the following:
    https://outlook.office.com/SMTP.Send offline_access
23. Uncheck Show on login page (it is recommended that you do not mix the email and login OAuth services).
24. Click Save changes.
25. Click the Configure endpoints icon for the new service.
26. Click Create new endpoints, then add the following:

Connect the account and configure outgoing mail

26. Return to the OAuth 2 services page.
27. Click the Connect to a system account icon.
28. Click Continue.
29. Sign in with your Microsoft email account that is used for your Totara email service.
30. Accept the permissions in Microsoft.
31. Go to Quick-access menu > Server > Email > Outgoing mail configuration.
32. Change SMTP Auth Type to XOAUTH2.
33. Change Oauth2 Service and choose the OAuth service you just created.
34. Set SMTP Username to the email of the account used for sending email (this should be the same as the No-reply address, i.e. the email address of the user connected via OAuth).
35. Set SMTP Password to any random text. It must not be blank, but otherwise, it does not matter.
36. Click Save changes.