SMTP via OAuth for Microsoft Office 365 Mailboxes

1. Register the EntraID app

• First go to the EntraID Admin Center https://entra.microsoft.com and log in to your tenant.
   
• In the Applications area, click on App registrations and then on New registration.
  
   
• In the next section, you only need to give the app a name; the default values for Supported Account types and Redirect URI can be retained.

2. Creating the client secret key

• Stay in the view of the created app and click on Certificates & secrets and then on New client secret.
  
   
• Give the client secret a name and select 24 months as the expire date. Remember the expire date, because you have to create a new client secret after the 24 months have expired so that the SMTP dispatch in DocuWare works without interruption.
   
• For the configuration in DocuWare we only need the Client Secret Key, i.e. the Value, we do not need the Secret ID. Please note that the value is only visible directly after the creation, as soon as you leave the page, you can no longer see the value.
  

3. Assign SMTP permissions

• Stay within the app and switch to the API permissions tab. There, click on Add a permission to give the app the necessary permissions for the SMTP functions.
  
   
• In the Request API permissions area, click on APIs my organization uses and then search for "Office 365 Exchange Online"
  
• Select the result, then click on Application permissions and select SMTP.SendAsApp from the list. Then click on Add permissions
  
   
• You or the EntraID Admin must now approve the authorization request.
  

4. Create the service principle for the EntraID app

• For this step, we need a PowerShell with admin access and a few IDs from the EntraID Admin Center.
   
• In the EntraID Admin Center, go to the Identity section and then to Overview. Copy the tenant ID there.
   
• Now switch back to the Applications area, but now to Enterprise applications and select the app you created earlier. Copy the Application ID and the Object ID.
  
       Important: To get the correct Object ID, you must switch the view from App registration to Enterprise applications, otherwise the wrong ObjectID will be displayed!
   
• Now open PowerShell and connect to your tenant with the following commands:
  Install-Module -Name ExchangeOnlineManagement
  Import-module ExchangeOnlineManagement 
  Connect-ExchangeOnline -Organization <tenantId>
   
• Now create a new service principle with the following command:
  New-ServicePrincipal -AppId [Your appID] -ObjectId [Ihre objectID]
  
   
• You can check your entry by displaying the service principal with Get-ServicePrincipal | fl
   
• Now add the mailbox with which you want to send emails in DocuWare:
  Add-MailboxPermission -Identity "invoices@example.com" -User [Your objectID] -AccessRights FullAccess
  

5. Configuration in DocuWare

The last step is to transfer the information from the EntraID to DocuWare.

• To do this, go to DocuWare Configuration -> Mail Services -> Sending and click on New SMTP Settings.
   
• Give the new configuration a name, select the display name and e-mail address with which the e-mails are to be sent. Next, select Use SMTP OAuth Authentication.
   
• The SMTP details are mandatory:
  • SMTP address: smtp-mail.outlook.com
  • User name: Your e-mail address that you entered in step 4
  • Encryption: STARTTLS
  • Port 587
     
• In the lower area, click on Microsoft and enter the application ID of the EntraID app and the corresponding client secret that you created previously.
  
   
• You can find the OAuth 2.0 token endpoint (v2) of your EntraID app in the EntraID Admin Center under Applications -> App registrations -> Name of your app -> Endpoints.
  
   
• Finally, please test your configuration with the Send test email button.