Configure OAuth 2.0 on Microsoft 365

You can configure Microsoft 365 to use OAuth 2.0 for email notifications. You must configure Microsoft 365 using the Microsoft Entra admin center to set up the client ID, client secret, and refresh token. You need these credentials when you're setting up OAuth 2.0 for notification emails on Administration > Notification settings in Sophos Firewall.

The key steps are as follows:

Register Sophos Firewall as an application.
Add delegated permissions.
Turn on SMTP authentication.
Create a client secret.
Generate the refresh token.

Warning

This information was correct at the time of writing. To ensure you're following the most current steps, review the Microsoft documentation. See Register an application with the Microsoft identity platform.

Register Sophos Firewall as an application

To register Sophos Firewall as an application, do as follows:

In the Microsoft Entra admin center, go to Identity > Applications > App registrations and select New registration.
Enter a name for the application.
Under Supported account types, for Who can use this application or access this API?, select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant).
Under Redirect URI (optional), in the Select a platform list, select Web.
In the URL field, enter https://outlook.office365.com/ or http://localhost/.

Both the URLs work. When you're generating the refresh token, make sure you use the same URL you enter in this field.
Click Register.

The admin center shows the details of the application you created.
Copy Application (client) ID.

When you're configuring OAuth 2.0 for email alerts in the firewall, you must paste this value in Client ID.

Add delegated permissions

To add delegated permissions, do as follows:

Go to the application you created for the firewall.
Go to API permissions and click Add a permission.
In the Request API permissions pane, click Microsoft Graph.
Select Delegated permissions.
Under Select permissions, select the SMTP.Send and offline_access permissions.
Click Add permissions.
Grant admin consent for the selected permissions and click Yes when prompted.

Turn on SMTP authentication

You must turn SMTP authentication on for the user sending the email notifications.

To turn SMTP authentication on for a user, do as follows:

In the Microsoft Entra admin center, go to Users and select Active users.
Select the user from whom you want to send the email notifications.
In the pop-up window, click Mail, then go to Email apps and click Manage email apps.
Turn Authenticated SMTP on.

Create a client secret

To create a client secret, do as follows:

Go to the application you created for the firewall.
In the application, go to Certificates & secrets > Client secrets and click New client secret.
Enter a description, specify the secret's expiration time, and click Add.
Copy the secret from Value next to the name of the secret immediately.

Note

You must copy the secret immediately because the admin center hides the secret once the page reloads.

When you're configuring OAuth 2.0 for email alerts in the firewall, you must paste this secret in Client secret.

Generate the refresh token

To generate the refresh token, do as follows:

In a web browser, enter the following URL:
```
https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={client-id}&response_type=code&redirect_uri={redirect-uri}&response_mode=query&scope=https://outlook.office365.com/.default+offline_access&state=12345
```
In the above URL, replace the following variables as follows:
- Replace {client-id} with the client ID you created.
- Replace {redirect-uri} with the URL you entered in step 5 of Register Sophos Firewall as an application.
Sign in with your Microsoft account.

You will receive an authorization code.

Here's an example:
```
https://outlook.office365.com/?code=AUTH_CODE_HERE&state=12345
```
Use an API client, such as Postman, to send a POST request as follows:

Warning

Make sure the system running the API client is in the same time zone as the firewall. If you change the firewall's time zone, you must restart the firewall.
1. POST URL:
```
https://login.microsoftonline.com/common/oauth2/v2.0/token
```
2. POST body:
```
client_id=YOUR_CLIENT_ID
&scope=https://outlook.office365.com/.default offline_access
&code=AUTH_CODE_FROM_STEP_2
&redirect_uri=YOUR_REDIRECT_URI
&grant_type=authorization_code
&client_secret=YOUR_CLIENT_SECRET
```
  Replace the following variables as follows:
  - Replace YOUR_CLIENT_ID with the client ID you created.
  - Replace AUTH_CODE_FROM_STEP_2 with the authorization code you received.
  - Replace YOUR_REDIRECT_URI with the URL you entered in step 5 of Register Sophos Firewall as an application.
  - Replace YOUR_CLIENT_SECRET with the client secret your created.
  You will receive the access and refresh tokens.
  
  Access tokens provide short-lived, one-time access. Applications use refresh tokens, which last longer and automatically renew through the application.
  
  Here's an example:
```
{
"token_type": "Bearer",
"scope": "https://outlook.office365.com/SMTP.Send https://outlook.office365.com/.default",
"expires_in": 5366,
"ext_expires_in": 5366,
"access_token": "xxxxxxx",
"refresh_token": "xxxxxxx"
}
```
  When you're configuring OAuth 2.0 for email alerts in the firewall, you must paste this token in Refresh token.