Configure Pleasanter to send mail using the SMTP server of M365

Overview¶

This page explains the settings needed to send mail from Pleasanter using OAuth 2.0 authentication with the SMTP server of Microsoft 365. Microsoft is migrating the authentication method of the SMTP server from basic authentication to OAuth 2.0 authentication; if you need to respond to this change, check the information below.

This manual explains the settings on the Microsoft 365 side and the settings on the Pleasanter side separately. For the settings on the Microsoft 365 side it gives only an outline. For details, check the Microsoft documents listed at the end of this manual.

Prerequisites¶

1. Administrator permission for the Microsoft 365 tenant is required.
2. Access permission to Entra ID (formerly Azure Active Directory) is required.
3. The mailbox used for sending (a shared mailbox or a user mailbox) needs to be created in advance.
4. Windows PowerShell that can be run with administrator permission is required.

1. Settings on the Microsoft 365 Side¶

1.1. Registering the application¶

Sign in to the Microsoft Azure Portal with an account that has administrator permission and register a new application. After registering it, note down the following information.

1.2. Creating a client secret¶

Create and add a "New client secret". Copy the "Value" that is displayed and save it somewhere safe. The value of the secret is displayed only once. Be sure to copy and save it. You set the value you saved in the parameter OAuthClientSecret later.

1.3. Setting the API permissions¶

Add the SMTP.SendAsApp permission for Office 365 Exchange Online.
Also grant admin consent for that tenant. This operation requires the permission of a global administrator of the tenant.

1.4. Tenant-wide SMTP AUTH settings¶

Using PowerShell, enable SMTP AUTH for the whole tenant.

This operation requires permission belonging to the Organization Management role group of Exchange Online.

1.5. Settings of Exchange Online¶

Using PowerShell, do the following.

1. Creating the shared mailbox used for sending
   Access the Exchange admin portal and create the shared mailbox used for sending.

2. Registering the service principal
   Connect to Exchange Online PowerShell and grant the application permission to send SMTP.
   This operation requires permission belonging to the Organization Management role group.

3. Granting access permission to the mailbox
   Grant access permission to the mailbox used for sending.
   This operation requires permission belonging to the Organization Management or the Recipient Management role group.

2. Settings on the Pleasanter Side¶

2.1. Settings of Mail.json¶

Set the parameters of the configuration file Mail.json as follows.

{
    "SmtpHost": "smtp.office365.com",
    "SmtpPort": 587,
    "SmtpUserName": "{{the mail address of the owner of the shared mailbox used for sending}}",
    "SmtpPassword": "",
    "SmtpEnableSsl": true,
    "SecureSocketOptions": "StartTls",
    "UseOAuth": true,
    "OAuthClientId": "{{the application (client) ID}}",
    "OAuthClientSecret": "{{the value of the client secret}}",
    "OAuthScope": "https://outlook.office365.com/.default",
    "OAuthGrantType": "client_credentials",
    "OAuthTokenEndpoint": "https://login.microsoftonline.com/{{the directory (tenant) ID}}/oauth2/v2.0/token",
    "Encoding": "UTF-8",
    "FixedFrom": "{{the mail address of the owner of the shared mailbox used for sending}}",
    "SupportFrom": "{{the mail address of the owner of the shared mailbox used for sending}}"
}

Description of the setting items¶

For the setting items marked [fixed value], set the value given.

2.2. Setting OAuthClientId and OAuthClientSecret with environment variables¶

For security reasons, we recommend that you set the following parameters with environment variables.

1. OAuthClientId
2. OAuthClientSecret

Linux/macOS Bash¶

export Pleasanter_Mail_OAuthClientId="{{the application (client) ID}}"
export Pleasanter_Mail_OAuthClientSecret="{{the value of the client secret}}"

Windows PowerShell¶

$env:Pleasanter_Mail_OAuthClientId = "{{the application (client) ID}}"
$env:Pleasanter_Mail_OAuthClientSecret = "{{the value of the client secret}}"

1. The prefix of the environment variable name has the form {EnvironmentName}Mail or {ServiceName}Mail.
2. The default ServiceName is Pleasanter.
3. When you set them with environment variables, leave OAuthClientId and OAuthClientSecret in Mail.json empty ("").

Once all the settings are done, restart Pleasanter.

3. What to Check When an Error Is Displayed¶

Error: "OAuth token acquisition failed" is displayed¶

1. Check the values of OAuthClientId, OAuthClientSecret and OAuthTokenEndpoint.
2. Check whether the API permissions of the Entra application are granted correctly.
3. Check whether admin consent has been granted.

Error: "Authentication failed" is displayed¶

1. Check whether SmtpUserName is the correct mail address.
2. Check whether the service principal is registered correctly in Exchange Online.
3. Check whether access permission to the mailbox has been granted.

Error: "5.7.3 Authentication unsuccessful" is displayed¶

1. Check whether OAuthScope is https://outlook.office365.com/.default.
2. Check whether SMTP AUTH is enabled for the mailbox.

4. Security Precautions¶

Supported Versions¶

Related Information¶

• Microsoft: Authenticate an IMAP, POP or SMTP connection using OAuth
• Microsoft: Register an application with the Microsoft identity platform
• Microsoft: SMTP AUTH clients submission