プリザンターからM365のSMTPサーバでメールを送信できるように設定する
## 概要
プリザンターからMicrosoft 365のSMTPサーバでOAuth 2.0認証を使い、メールを送信するために必要な設定について説明します。マイクロソフト社はSMTPサーバの認証方式を[ベーシック認証からOAuth 2.0認証へ移行](https://jpmessaging.github.io/blog/Updated-Exchange-Online-SMTP-AUTH-Basic-Authentication-Deprecation-Timeline/)させており、この変更に伴う対応が必要な場合は、以下の情報を確認してください。
本マニュアルでは、Microsoft 365側の設定と、プリザンター側の設定とに分けて説明します。Microsoft 365側の設定については概略を示すにとどめます。詳細は本マニュアルの末尾にまとめたマイクロソフト社のドキュメントを確認してください。
## 注意事項
1. <span style="color:red; font-weight:bold">バージョン1.5.5.0以降、Providerパラメータの追加に伴い設定方式が変更されています。既存環境からの移行については[メール送信プロバイダー設定の移行について](/ja/manual/mail-provider-migration)を参照してください。
1. パラメータ変更時は[パラメータ変更時の確認事項](/ja/manual/parameter-edit)をご確認ください。
1. セキュリティ上の理由から、OAuthClientIdおよびOAuthClientSecretは[Mail.json](/ja/manual/mail.json)に直接記述せず、環境変数で設定することを推奨します。詳細は「2.3. 環境変数による設定（推奨）」を参照してください。
1. [Mail.json](/ja/manual/mail.json)の設定変更後はプリザンターの再起動が必要です。再起動を行うまで変更は反映されません。
## 前提条件
1. Microsoft 365 テナントの管理者権限が必要です。
1. Entra ID（旧Azure Active Directory）へのアクセス権限が必要です。
1.事前に送信に使用するメールボックス（共有メールボックスまたはユーザメールボックス）の作成が必要です。
1.管理者権限で実行できるWindows PowerShellが必要です。
## 操作手順
### 1. Microsoft 365側の設定
#### 1.1.アプリケーションの登録
管理者権限を持つアカウントで[Microsoft Azure Portal](https://portal.azure.com)にサインインし、アプリケーションを新規登録してください。登録後、以下の情報をメモしてください。
| 項目 | 説明 |
| ---------------------------------- | ---------------------------------------------------------------- |
| アプリケーション (クライアント) ID | パラメータOAuthClientIdに設定します。 |
| ディレクトリ (テナント) ID | パラメータOAuthTokenEndpointに設定する値の一部として使用します。 |
#### 1.2.クライアントシークレットの作成
「新しいクライアント シークレット」を作成・追加してください。表示された「値」をコピーして安全な場所に保存してください。<span style="color:red">シークレットの値は一度しか表示されません。必ずコピーして保存してください。</span>保存した値は、後ほどパラメータOAuthClientSecretに設定します。
| 項目 | 説明 |
| ---- | -------------------------------------------------------------------------------------------------------- |
| 値 | <span style="color:red">作成時に一度しか表示されません。</span>パラメータOAuthClientSecretに設定します。 |
#### 1.3. APIアクセス許可の設定
Office 365 Exchange Onlineに対し、SMTP.SendAsAppの許可を追加してください。また、当該テナントへ管理者の同意を付与してください。<span style="color:red">この操作は、テナントの全体管理者の権限が必要です。</span>
#### 1.4. テナント全体のSMTP AUTH設定
PowerShellを使い、テナント全体に対してSMTP AUTHを有効化してください。
この操作には、Exchange OnlineのOrganization Management（組織管理）ロールグループに属する権限が必要です。
#### 1.5. Exchange Onlineの設定
PowerShellを使い、以下を実施してください。
1. **送信用共有メールボックスの作成**
[Exchangeの管理ポータル](https://admin.cloud.microsoft/#/homepage)にアクセスし、送信用の共有メールボックスを作成してください。
2. **サービスプリンシパルの登録**
Exchange Online PowerShellに接続して、アプリケーションにSMTP送信権限を付与してください。
この操作には、Organization Management（組織管理）ロールグループに属する権限が必要です。
3. **メールボックスへのアクセス許可を付与**
送信に使用するメールボックスに対してアクセス許可を付与してください。
この操作には、Organization Management（組織管理）またはRecipient Management（受信者管理）ロールグループに属する権限が必要です。
### 2. プリザンター側の設定
#### 2.1. Mail.jsonの設定
設定ファイル[Mail.json](/ja/manual/mail.json)のパラメータを以下のように設定してください。
```json
{
"Provider": "Smtp",
"SmtpHost": "smtp.office365.com",
"SmtpPort": 587,
"SmtpUserName": "《送信用共有メールボックスの所有者のメールアドレス》",
"SmtpPassword": "",
"SmtpEnableSsl": true,
"SecureSocketOptions": "StartTls",
"UseOAuth": true,
"OAuthClientId": "《アプリケーション (クライアント) ID》",
"OAuthClientSecret": "《クライアントシークレットの値》",
"OAuthScope": "https://outlook.office365.com/.default",
"OAuthGrantType": "client_credentials",
"OAuthTokenEndpoint": "https://login.microsoftonline.com/《ディレクトリ (テナント) ID》/oauth2/v2.0/token",
"Encoding": "UTF-8",
"FixedFrom": "《送信用共有メールボックスの所有者のメールアドレス》",
"SupportFrom": "《送信用共有メールボックスの所有者のメールアドレス》"
}
```
#### 2.2. 設定項目の説明
【固定値】とある設定項目には、既定の値を設定してください。
| パラメータ | 値 | 説明 |
| :------------------ | :--------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------- |
| Provider | "Smtp" | SMTPを使用する場合はSmtpを指定します。【固定値】 |
| SmtpHost | smtp.office365.com | M365のSMTPサーバ【固定値】 |
| SmtpPort | 587 | SMTP送信ポート【固定値】 |
| SmtpUserName | 《送信用共有メールボックスの所有者のメールアドレス》 | SMTP-AUTHのユーザ名を指定。 |
| SmtpPassword | 空欄 | OAuth使用時は不要【固定値】 |
| SmtpEnableSsl | true | SSL/TLS有効化【固定値】 |
| SecureSocketOptions | StartTls | STARTTLS使用【固定値】 |
| UseOAuth | true | OAuth認証を有効化【固定値】 |
| OAuthClientId | 《アプリケーション (クライアント) ID》（空欄""を推奨） | Azure Portalで取得したクライアントID<br><span style="color:red">※下記参照</span> |
| OAuthClientSecret | 《クライアントシークレットの値》（空欄""を推奨） | Azure Portalで作成したクライアントシークレットの「値」<br><span style="color:red">※下記参照</span> |
| OAuthScope | https://outlook.office365.com/.default | M365 SMTPのスコープ【固定値】 |
| OAuthGrantType | client_credentials | クライアント資格情報フロー【固定値】 |
| OAuthTokenEndpoint | https://login.microsoftonline.com/《ディレクトリ (テナント) ID》/oauth2/v2.0/token | トークンエンドポイント（《ディレクトリ (テナント) ID》をAzure Portalで取得した実際の値に置換） |
| Encoding | UTF-8 | メール本文のエンコーディング形式【固定値】 |
| FixedFrom | 《送信用共有メールボックスの所有者のメールアドレス》 | メール送信時のfromアドレス。OAuth 2.0認証時には送信用共有メールボックスの所有者のメールアドレスを設定 |
| SupportFrom | 《送信用共有メールボックスの所有者のメールアドレス》 | サポート用メールアドレスを指定。OAuth 2.0認証時には送信用共有メールボックスの所有者のメールアドレスを設定 |
#### 2.3. 環境変数による設定（推奨）
アプリケーション (クライアント) IDとクライアントシークレットの値は、Mail.jsonの代わりに環境変数へ登録できます。[Mail.json](/ja/manual/mail.json)で値を設定している場合は、そちらが優先されます。
プリザンターは[Mail.json](/ja/manual/mail.json)の値が空（""）またはnullの場合にのみ、環境変数から取得します。
##### 対応する環境変数
| 対象パラメータ | 環境変数名（EnvironmentName形式） | 環境変数名（ServiceName形式） |
| :---------------- | :--------------------------------------- | :----------------------------------- |
| OAuthClientId | {EnvironmentName}_Mail_OAuthClientId | {ServiceName}_Mail_OAuthClientId |
| OAuthClientSecret | {EnvironmentName}_Mail_OAuthClientSecret | {ServiceName}_Mail_OAuthClientSecret |
{EnvironmentName}と{ServiceName}は[Service.json](/ja/manual/service-json)のパラメータEnvironmentName、ServiceNameの各設定値に対応します。デフォルトのServiceNameはPleasanterです。
##### PowerShell（Windows）での設定方法
```ps1
$env:Pleasanter_Mail_OAuthClientId = "《アプリケーション (クライアント) ID》"
$env:Pleasanter_Mail_OAuthClientSecret = "《クライアントシークレットの値》"
```
##### bash（LinuxまたはmacOSでの設定方法）
```sh
export Pleasanter_Mail_OAuthClientId="《アプリケーション (クライアント) ID》"
export Pleasanter_Mail_OAuthClientSecret="《クライアントシークレットの値》"
```
### 3. プリザンターの再起動
設定変更を反映するため、プリザンターを再起動してください。
Windows環境の場合は、IISを再起動してください。
Linux環境の場合は、以下のコマンドでサービスを再起動してください。
```bash
sudo systemctl restart pleasanter
```
Microsoft Azure環境の場合は、App Serviceを再起動してください。
### 4. エラーが表示された場合の確認事項
##### エラー: "OAuth token acquisition failed"が表示される
1. OAuthClientId、OAuthClientSecret、OAuthTokenEndpointの値を確認してください。
1. EntraアプリケーションのAPI許可が正しく付与されているかを確認してください。
1.管理者の同意が付与されているかを確認してください。
##### エラー: "Authentication failed"が表示される
1. SmtpUserNameが正しいメールアドレスかを確認してください。
1. Exchange Onlineでサービスプリンシパルが正しく登録されているかを確認してください。
1. メールボックスへのアクセス許可が付与されているかを確認してください。
##### エラー: "5.7.3 Authentication unsuccessful"が表示される
1. OAuthScopeがhttps://outlook.office365.com/.defaultになっているかを確認してください。
1. SMTP AUTHがメールボックスで有効になっているかを確認してください。
### 5. セキュリティに関する注意事項
| セキュリティ項目 | 推奨事項 |
| :----------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |
| クライアントシークレットの管理 | シークレットは定期的にローテーションしてください。<br>有効期限が切れる前に新しいシークレットを作成し、設定を更新してください。 |
| 最小権限の原則の遵守 | 必要最小限のAPI許可のみを付与してください。<br>特定のメールボックスのみにアクセス許可を限定してください。 |
| 監査ログの確認 | Entra IDのサインインログを定期的に確認してください。<br>不審なアクティビティがないかを監視してください。 |
## 対応バージョン
| 対応バージョン | 内容 |
| :------------- | :----------------------- |
| 1.5.1.0以降 | 機能追加 |
| 1.5.5.0以降 | Providerパラメータを追加 |
## 関連情報
- [Microsoft: Authenticate an IMAP, POP or SMTP connection using OAuth](https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth)
- [Microsoft: Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)
- [Microsoft: SMTP AUTH clients submission](https://learn.microsoft.com/en-us/exchange/clients-and-mobile-in-exchange-online/authenticated-client-smtp-submission)
