Mail Configuration

VoIP Detective requires an external email server in order to send reports, alerts, and administrator emails out.  To that end, VoIP Detective can use the following to send email:

• SMTP (including basic authentication and STARTTLS)
• Microsoft 365 OAuth2 Email Authentication.

Mail can be configured by going to Administration -> Configuration.

Under the Mail settings section, you can enter information relevant to your configuration.

Troubleshooting

To verify your mail settings, go to Administration -> Troubleshooting and look for "Mail System Test"  This will allow you to send a test mail and view detailed debugging information.

Configuring SMTP

To configure SMTP for email delivery, do the following:

1. Go to Administration -> Configuration
2. Scroll down to the "Mail Settings" section
3. Set Mail enable / disable to "enabled" and press the go button
4. Set Mail Transport to SMTP and press the go button
5. Enter your SMTP host and press the go button
6. Enter any other necessary information like username, password, etc.
7. Enter the 

Configuring Microsoft 365 OAuth2 Email Authentication

Important: Microsoft 365 is retiring Basic SMTP authentication. Basic auth will be permanently disabled starting March 1, 2026 and completing April 30, 2026. Follow this guide to configure OAuth2 authentication before that date.

Prerequisites

Before you begin, ensure you have:

• Administrator access to your Microsoft 365 / Azure tenant
• VoIP Detective OS 4.x or later with PHPMailer installed (use the command line (CLI) menu option 5.5.2)
• A valid Microsoft 365 mailbox that will be used to send emails

Step 1: Register an Application in Azure Portal

1. Go to https://portal.azure.com and sign in with your administrator account
2. Navigate to Microsoft Entra ID → App registrations (Note: Azure Active Directory has been renamed to Microsoft Entra ID)
3. Click New registration
4. Configure the application:
   • Name: Enter a descriptive name (e.g., "VoIP Detective Email")
   • Supported account types: Select "Accounts in this organizational directory only"
   • Redirect URI: Leave blank (not required for Device Code Flow)
5. Click Register
6. On the application overview page, copy and save:
   • Application (client) ID
   • Directory (tenant) ID

Step 2: Enable Public Client Flow

1. In your application, click Authentication in the left sidebar
2. Go to Settings
3. Set Allow public client flows to Yes
4. Click Save

Note:This setting is required for the Device Code Flow, which allows authentication from servers that are not accessible from the internet.

Step 3: Configure API Permissions

1. Click API permissions in the left sidebar
2. Click Add a permission
3. Select Microsoft Graph
4. Select Delegated permissions
5. Search for and add the following permissions:
   • offline_access - Allows the app to refresh tokens automatically
   • SMTP.Send - Allows sending emails via SMTP
6. Click Add permissions
7. Click Grant admin consent for [Your Organization] and confirm

Note: You must grant admin consent for the permissions to take effect. Look for the green checkmarks in the Status column.

Step 4: Enable SMTP AUTH for the Mailbox

1. Go to the Microsoft 365 Admin Center
2. Navigate to Users → Active users
3. Select the user/mailbox that will send emails
4. Click the Mail tab
5. Under "Email apps", click Manage email apps
6. Ensure Authenticated SMTP is enabled
7. Click Save changes

Step 5: Install PHPMailer on VoIP Detective

1. Connect to your VoIP Detective server via SSH or console
2. Navigate to Option 5 (Configure) → Option 5.5 (Mail Services)
3. Select Option 2 to install PHPMailer with Microsoft 365 OAuth2 support
4. Wait for the installation to complete

This will install the required components to send mail with M365 OAuth2

Step 6: Generate OAuth2 Tokens

1. Log in to VoIP Detective as an administrator
2. Navigate to Admin → Microsoft 365 OAuth2 Setup (or go directly to https://YOUR_SERVER/admin/m365_oauth_setup.php)
3. Enter your Azure application credentials:
   • Application (Client) ID: From Step 1
   • Directory (Tenant) ID: From Step 1
4. Click Continue
5. You will see a device code and a URL. On any device with internet access (phone, laptop, etc.):
   • Open https://microsoft.com/devicelogin
   • Enter the code displayed on the VoIP Detective page
   • Sign in with the Microsoft 365 account that will send emails
   • Review the permissions and click Accept
6. The VoIP Detective page will automatically detect the successful authentication
7. Enter the email address you authenticated with and click Save Configuration

Note: The Device Code Flow allows you to authenticate even if your VoIP Detective server is not accessible from the internet. You can complete the Microsoft authentication step on any internet-connected device.

Step 7: Configure VoIP Detective Email Settings

1. In the VoIP Detective web interface, navigate to Settings → Email Configuration
2. Select Microsoft 365 (OAuth2) as the mail provider
3. Enter the Email Address (must match the account used in Step 6)
4. The OAuth2 tokens are managed automatically from the setup in Step 6
5. Click Save
6. Use the Send Test Email button to verify the configuration

Token Lifecycle and Maintenance

Understanding how OAuth2 tokens work will help you maintain your email configuration:

Key Points:

• Access tokens are refreshed automatically by VoIP Detective when sending emails
• Refresh tokens remain valid as long as your system sends at least one email every 90 days
• If no emails are sent for 90+ days, you will need to re-run the OAuth2 setup (Step 6)

Troubleshooting

Error: "Allow public client flows" not enabled

• Go to Azure Portal → App registrations → Your App → Authentication
• Set "Allow public client flows" to Yes
• Save and try again

Authentication unsuccessful (535 5.7.3)

• Verify SMTP AUTH is enabled for the mailbox (Step 4)
• Ensure admin consent was granted for API permissions (Step 3)
• Confirm the email address matches the account used during OAuth2 setup
• Re-run the OAuth2 setup (Step 6) to generate new tokens

Device code expired

• The device code is valid for approximately 15 minutes
• If it expires before you complete authentication, simply refresh the page and start again

Token refresh failed

• This typically occurs after 90+ days of inactivity
• Re-run the OAuth2 setup (Step 6) to generate new tokens

Permission denied / Unauthorized

• Verify the SMTP.Send permission is added and admin consent is granted
• Ensure you're using a licensed Microsoft 365 mailbox (not a shared mailbox without a license)
• Check that "Allow public client flows" is enabled

Tokens directory permission error

• Run deployment menu option 5.5.2 again to recreate the directory with correct permissions
• Or manually fix: sudo chown apache:apache /var/www/tokens && sudo chmod 750 /var/www/tokens

Security Notes

• OAuth2 tokens are stored securely outside the web root in /var/www/tokens/
• Token files are protected with restrictive permissions (640)
• No client secret is required with the Device Code Flow, reducing credential exposure
• Only the Apache web server process can read the token files

Important Dates

Additional Resources

• Microsoft Announcement: Basic Auth Retirement
• Microsoft Documentation: OAuth for SMTP
• Microsoft Device Code Flow Documentation