Standalone SMTP - Microsoft 365 (OAuth 2.0)

Standalone SMTP Setup - Microsoft 365 (OAuth 2.0)

This article covers the process of preparing Microsoft 365 for SMTP email sending from Humly Control Panel using OAuth 2.0. During the process you will configure the following:

1. Register an application in Azure AD
   • Add API permissions
   • Create a client secret
2. Configure Standalone SMTP Credentials in HCP
   • Generate and run the Exchange Online PowerShell script

Table of Contents

• Common Use Cases
• Register an Application in MS Entra
• Configure Standalone SMTP Credentials in HCP
• Run the Exchange Online PowerShell Script
• Best Practices
• Troubleshooting

Common Use Cases

• Setting up Standalone SMTP email sending in HCP for the first time with a Microsoft 365 tenant.
• Migrating an existing Basic Authentication SMTP setup to OAuth 2.0 before the Microsoft deprecation deadline.
• Updating a client secret that has expired or been revoked.

Register an Application in MS Entra

These steps are performed by the customer's Entra administrator in the MS Entra.

Create the app registration

1. Navigate to Microsoft Entra ID > App registrations and click New registration.
2. Fill in the following fields:
   • Name: A descriptive name, for example Humly SMTP Relay
   • Supported account types: Accounts in this organizational directory only (Single tenant)
   • Redirect URI: Leave blank
3. Click Register.
4. On the Overview page of the newly created app registration, note down the following values — they will be needed when configuring HCP:
   • Application (client) ID
   • Directory (tenant) ID

Add API permissions

1. In the app registration, go to API permissions > Add a permission.
2. Select APIs my organization uses and search for Office 365 Exchange Online.
3. Select Application permissions, then add the permission SMTP.SendAsApp.
4. Click Add permissions.
5. Click Grant admin consent for [organization name] and confirm.

Create a client secret

1. Go to Certificates & secrets > Client secrets and click New client secret.
2. Enter a description (for example HCP SMTP) and select an expiry period, then click Add.
3. Copy the Value of the newly created secret immediately.

Note the Enterprise Application Object ID

1. Navigate to Microsoft Entra ID > Enterprise applications.
2. Search for the application name created in step 1 and open it.
3. On the Overview page, copy the Object ID.

Configure Standalone SMTP Credentials in HCP

1. Open the HCP setup wizard and navigate to the Standalone SMTP Credentials step.
2. Enter the sender mailbox address in the Standalone Admin email field (for example noreply@company.com). This is the mailbox HCP will send email from.
3. In the Authentication dropdown, select Microsoft 365 (OAuth 2.0). The SMTP Server field will automatically populate with smtp.office365.com, TLS Options will be set to STARTTLS, and SMTP Port will be set to 587.
4. Fill in the remaining fields using the values collected during the Azure AD setup:

   Field	Value
   Tenant ID	Directory (tenant) ID step 4
   Application Client ID	Application (client) ID step 4
   Client Secret	Secret value step 3
   Enterprise App Object ID	Object ID step 3

   
5. Click Generate PowerShell Script. The Exchange Online Setup dialog will appear with the script required for the next section.

Run the Exchange Online PowerShell Script

Before clicking Next in HCP, the generated PowerShell script must be run by the customer's Exchange administrator.

What the script does

The script performs the following actions in Exchange Online:

• Installs the ExchangeOnlineManagement PowerShell module if not already present
• Connects to the customer's Exchange Online tenant
• Registers the Azure AD application as a service principal in Exchange Online
• Grants the service principal FullAccess permission on the sender mailbox
• Enables SMTP AUTH for the sender mailbox

Running the script

1. In the Exchange Online Setup dialog in HCP, click Copy to Clipboard.
2. Open a PowerShell session and paste the script.
3. The script will prompt for credentials when connecting to Exchange Online. Sign in with a Global Administrator or Exchange Administrator account.
4. Verify that all commands complete without errors.
5. Return to HCP, close the Exchange Online Setup dialog, and click Next.
6. HCP will authenticate with Exchange Online using the OAuth 2.0 credentials and send a test email to the Standalone Admin email address entered in the wizard.
7. Confirm that the test email is received. If successful, the wizard will proceed to the next step.

Best Practices

• Use a dedicated sender mailbox. Avoid using a personal or admin account as the sender mailbox. A dedicated mailbox such as noreply@company.com is easier to manage and reduces risk if the account changes.
• Set an appropriate expiry for the client secret. Choose an expiry period that aligns with your organisation's security policy. Make a note of the expiry date and plan for renewal before it lapses to avoid email sending failures.
• Store the client secret securely. The client secret grants access to send email on behalf of the sender mailbox. Store it in a secure location and restrict access accordingly.
• Run the PowerShell script before clicking Next in HCP. The Exchange Online service principal and mailbox permissions must be in place before HCP attempts to verify the connection. Running the script after clicking Next will result in a failed verification.
• Grant admin consent before saving. Ensure admin consent has been granted for the SMTP.SendAsApp permission in Azure AD before attempting to verify the connection in HCP. Without consent, token requests will fail.

Troubleshooting

Authentication fails when verifying the connection in HCP

• Confirm that admin consent has been granted for the SMTP.SendAsApp permission in Azure AD. Go to App registrations > API permissions and verify the status shows Granted.
• Verify that the Tenant ID, Application Client ID, Client Secret and Enterprise App Object ID have been entered correctly in HCP.
• Check that the client secret has not expired. If it has, create a new secret in Azure AD and update HCP.

535 5.7.3 Authentication unsuccessful

• Confirm that the Set-CASMailbox command in the PowerShell script completed without errors. SMTP AUTH must be explicitly enabled on the sender mailbox.
• Verify that SmtpClientAuthenticationDisabled is set to $false for the mailbox by running the following in Exchange Online PowerShell:

Get-CASMailbox -Identity "sender@company.com" | Select SmtpClientAuthenticationDisabled

Service principal not found or New-ServicePrincipal fails

• Verify that the Enterprise App Object ID entered in HCP matches the Object ID from Enterprise applications in Azure AD, not the App registrations page.
• Confirm that the application has been consented to in the tenant. If admin consent was not granted, the enterprise application may not have been created. Grant admin consent and retry.

The client secret has expired

• Go to Azure AD > App registrations, select the app, navigate to Certificates & secrets and create a new client secret.
• Update the Client Secret field in HCP under Global Settings > Standalone SMTP Credentials.