Setting Up eTASK SMTP Email Sending with OAuth 2.0

In this article

1. Purpose of this guide

2. Prerequisites

3. Overview of setup steps

4. Step 1: Create an app registration in Azure

5. Step 2: Create a client secret

6. Step 3: Configure API permissions

7. Step 4: Determine the Enterprise Application ID

8. Step 5: Configure Exchange Online via PowerShell

9. Step 6: Configure the eTASK portal

10. Step 7: Enable OAuth authentication

11. Step 8: Send a test email

12. Troubleshooting

13. Additional Important Information

14. Summary of Required Values

15. Additional resources

Purpose of this guide

This guide shows you how to switch email sending in eTASK to OAuth 2.0 authentication. This is necessary because Microsoft is phasing out Basic SMTP authentication (username/password).

Prerequisites

Before you begin the setup, make sure that:

• ✅ You have administrator rights in the eTASK FM portal

• ✅ You have access to the Azure Portal (Microsoft Entra ID)

• ✅ You have global administrator rights in Microsoft 365

• ✅ PowerShell with the Exchange Online Management Module is available

• ✅ A dedicated email address for SMTP sending exists (e.g., smtp@ihredomain.de)

Overview of the setup steps

Setup is divided into three main areas:

1. Azure App Registration: Create an application registration for OAuth

2. Exchange Online configuration: Assigning permissions via PowerShell

3. eTASK Portal configuration: Storing the OAuth parameters

Step 1: Create an app registration in Azure

Objective: Create an application registration in Microsoft Entra ID (Azure AD) that can issue OAuth tokens for SMTP sending.

Procedure:

1. Sign in to the Azure Portal: https://portal.azure.com

2. Navigate to Microsoft Entra ID (formerly Azure Active Directory)

3. Select App registrations from the menu

4. Click + New registration

5. Fill out the form:

   • Name: e.g., "eTASK SMTP OAuth"

   • Supported account types: Only accounts in this organizational directory

   • Redirect URI: Leave blank

6. Click Register

Note the important values:

On the overview page of the newly created app, you will find:

• Application ID (Client) → You will need this later as <AnwendungsID>

• Directory ID (Tenant) → You will need this later as <VerzeichnisID>

Result: The app registration has been created, and you have noted down the Client ID and Tenant ID.

Step 2: Create a Client Secret

Goal: Create a secret that eTASK can use to authenticate with Azure.

Procedure:

1. Stay in your app registration

2. Navigate to Certificates & Secrets in the menu

3. Click on + New client secret

4. Enter a description: e.g., "eTASK SMTP Secret"

5. Select a validity period (recommended: 24 months or longer)

6. Click Add

Important: Immediately copy the secret value and store it securely.

• Value → This is your <ClientSecret>

• ⚠️ This value is displayed only once and cannot be retrieved again!

Result: You have created a client secret and stored it securely.

Step 3: Configure API permissions

Goal: Grant the app permission to send emails on behalf of mailboxes.

Procedure:

1. Stay in your app registration

2. Navigate to API Permissions

3. Click + Add permission

4. Select APIs used by my organization

5. Search for Office 365 Exchange Online and select it

6. Select Application permissions (non-delegated permissions)

7. Search for SMTP and enable SMTP.SendAsApp

8. Click Add permissions

9. Important: Click Grant administrator consent for [your organization]

10. Confirm by clicking Yes

Verification: A green checkmark should now appear under "Status" for the "SMTP.SendAsApp" permission.

Result: The app has permission to send emails via SMTP.

Step 4: Determine the object ID of the enterprise application

Objective: Determine the object ID of the Enterprise Application required for the Exchange configuration.

Procedure:

1. Stay in your app registration

2. On the overview page, you will find a link under the app name:
   "Managed application in local directory"

3. Click this link (this will take you to the Enterprise Application)

4. On the Enterprise Application overview page, you will find the object ID

5. Copy this object ID → This is your <ObjektID>

Note: The object ID of the Enterprise Application is not the same as the application ID from Step 1!

Result: You have noted down the object ID of the Enterprise Application.

Step 5: Exchange Online Configuration via PowerShell

Goal: Link the app registration to Exchange Online and grant permissions to the SMTP mailbox.

Check prerequisites:

Check whether the Exchange Online Management Module is installed:

Get-Module -ListAvailable -Name ExchangeOnlineManagement

If not installed, run the following as an administrator:

Install-Module -Name ExchangeOnlineManagement

Procedure:

1. Open PowerShell as an administrator

2. Connect to Exchange Online:

Connect-ExchangeOnline

You will be prompted to sign in with a global administrator account.

3. Create the service principal for your app:

New-ServicePrincipal -AppId "<AnwendungsID>" -ServiceId "<ObjektID>"

Replace:

• <AnwendungsID> with the application ID from step 1

• <ObjektID> with the object ID from step 4

Example:

New-ServicePrincipal -AppId "12345678-1234-1234-1234-123456789abc" -ServiceId "87654321-4321-4321-4321-abcdef123456"

4. Grant permission to the SMTP mailbox:

Add-MailboxPermission -Identity "<SMTPUSER>" -User "<ObjektID>" -AccessRights FullAccess

Replace:

• <SMTPUSER> with the email address to be used for SMTP sending (e.g. smtp@etask.de)

• <ObjektID> with the object ID from step 4

Example:

Add-MailboxPermission -Identity "smtp@ihredomain.de" -User "87654321-4321-4321-4321-abcdef123456" -AccessRights FullAccess

5. Close the PowerShell session:

Disconnect-ExchangeOnline

Result: The app registration is linked to Exchange Online and has access to the SMTP mailbox.

Step 6: eTASK Portal Configuration

Objective: Enter the OAuth parameters in the eTASK Portal.

Procedure:

1. Log in to the eTASK FM Portal as an administrator

2. Navigate to System Configuration (Control Panel → Portal Options → System Configuration)

3. Search for the following parameters and set them:

4. Save the configuration

Important:

• The parameters SMTPOAUTHCLIENTID, SMTPOAUTHCLIENTSECRET and SMTPOAUTHTENANTID are new parameters and may need to be created as new system parameters

• Make sure that the parameter SMTPPASSWORD remains empty or is removed, as it is no longer required for OAuth

Result: The OAuth configuration is stored in the portal.

Step 7: Enable OAuth authentication

Goal: Enable OAuth mode for SMTP sending.

Procedure:

1. In the system configuration, search for the parameter SMTPUSEOAUTH

2. If the parameter does not exist, create it

3. Set the value to 1 (enabled) or true

4. Save the configuration

Note:

• For SMTPUSEOAUTH = 1 or true → OAuth is used

• For SMTPUSEOAUTH = 0 or false → Basic Authentication (username/password) is used

Result: OAuth authentication for SMTP is enabled.

Step 8: Send a test email

Goal: Verify that email sending with OAuth works.

Procedure:

1. In the portal, navigate to Control Panel → Portal Options → Portal Management → Portal Control → Test Settings

2. Click Send Test Email

3. Enter a valid email address

4. Click Send

5. Check whether the email arrives

If successful:

• ✅ You should see a confirmation message

• ✅ The test email should arrive in your inbox

• ✅ OAuth should be listed as the authentication method in the email headers

If there is an error:

• ❌ Check the error message in the portal

• ❌ Check all parameters in the system configuration

• ❌ Check the permissions in Azure and Exchange Online

• ❌ See the "Troubleshooting" section below

Result: SMTP sending with OAuth works.

Troubleshooting

Problem: Test email is not being sent

Possible causes and solutions:

1. Error message: "Authentication failed"

   • Check whether the client secret was copied correctly

   • Check whether the client secret has expired

   • If necessary, create a new client secret in Azure

2. Error message: "Access denied" or "Permission denied"

   • Check whether the "SMTP.SendAsApp" API permission has been granted

   • Check whether administrator consent has been granted

   • Check whether the service principal has been created in Exchange Online

   • Check whether the mailbox permission has been set correctly

3. Error message: "Invalid tenant"

   • Check whether the tenant ID (directory ID) is correct

   • Ensure that you are using the correct Azure AD organization

4. Error message: "Invalid client"

   • Check whether the client ID (application ID) is correct

   • Make sure the app registration has not been deleted

5. No error message, but email is not arriving

   • Check the recipient's spam folder

   • Check the email logs in the Exchange Online Admin Center

   • Check whether the sender address (MAILFROMADDRESS) is correct

Check the logs

If available, check the eTASK logs for detailed error messages:

• Windows Event Log

• eTASK Application Logs

• IIS logs

Additional Important Information

Client Secret Expiration

Important: The client secret has an expiration date. Plan for renewal in advance:

1. Create a new client secret in Azure approximately 1 month before expiration

2. Update the parameter SMTPOAUTHCLIENTSECRET in the portal

3. Test email delivery

4. Do not delete the old secret until the migration is complete

Security Notes

• ⚠️ Store the client secret securely (e.g., in a password manager or key vault)

• ⚠️ Never share the client secret via unsecure channels

• ⚠️ Document who has access to the Azure App Registration

• ⚠️ Regularly review permissions in Azure

Differences from Basic Authentication

With OAuth 2.0:

• ✅ No more passwords stored in the portal

• ✅ Greater security through token-based authentication

• ✅ Centralized management of permissions in Azure

• ✅ Compliance with Microsoft security policies

• ✅ No deactivation by Microsoft during security updates

Technical Details

The OAuth token is retrieved using the OAuth 2.0 Client Credentials Grant method via MSAL (Microsoft Authentication Library). Internally, eTASK uses the MailKit library for SMTP sending with OAuth support.

Summary of required values

For quick reference, here are all required values:

Additional resources

• Microsoft Documentation: Authenticate an IMAP, POP, or SMTP connection using OAuth

• Microsoft documentation: App-only authentication for unattended applications

• Jira Ticket: FM-27208

Good luck with the OAuth setup!

If you have any questions, please contact eTASK Support.