暗号化された Outlook アドインを作成する

Outlook アドインにカスタム暗号化および解読機能を実装して、メール通信をセキュリティで保護します。 OnMessageDecrypt イベントを使用すると、アドインは暗号化されたメッセージを自動的に識別し、復号化、コンテンツの表示、エラー通知を処理できます。

暗号化と暗号化解除のワークフローの概要

ヒント

  • 暗号化および復号化ワークフローでは、イベント ベースのアクティベーション機能が実装されます。 Outlook アドインでのイベント ベースのアクティブ化に慣れていない場合は、最初にこの機能とその実装について理解することをお勧めします。 詳細については、「 イベントを使用してアドインをアクティブ化する」を参照してください。
  • 最小要件セットとサポートされているプラットフォームは、このセクションで推奨される API ごとに異なる場合があります。 Outlook JavaScript API 要件セットに対して要件を確認し、特定の API に関するドキュメントで補足することをお勧めします。

次の表に、Outlook アドインの暗号化と解読のワークフローの概要を示します。 また、手順にカスタム ソリューションが必要かどうか、または Office JavaScript (Office.js) API ライブラリでサポートされているかどうかも識別します。

手順 実装
ユーザーがメッセージを作成し、アドインを使用して暗号化規則を適用する アドインがメッセージの内容とその添付ファイルをセキュリティで保護できるように、独自の暗号化プロトコルを実装する必要があります。
ユーザーがメッセージを送信します OnMessageSend イベントのハンドラーを実装して、ユーザーが [送信] を選択したときにアドインが暗号化プロトコルを自動的に実行できるようにします。

暗号化解除プロセス中にアドインを使用して暗号化されたメッセージを識別するには、 インターネット ヘッダー API を使用してメッセージにヘッダーを追加します。 ヘッダー キーは、アドインのマニフェスト内の OnMessageDecrypt イベントの <LaunchEvent> 要素の HeaderName 属性で指定された値と一致する必要があります。 詳細については、「 イベント ベースのアクティベーションを使用した復号化の実装」を参照してください。
受信者が暗号化されたメッセージを受信し、それを開きます Outlook でインストールされたメッセージの暗号化に使用したものと同じアドインを受信者が所有している場合、アドインは、メッセージに含まれるヘッダー キーが、マニフェストの OnMessageDecrypt イベントに指定された値と一致するかどうかを確認します。 この操作は、OnMessageDecrypt イベントを処理するアドインによって自動的に実行されるため、手動でチェックを実装する必要はありません。 ヘッダーが一致する場合、 OnMessageDecrypt イベントが発生し、そのハンドラーが実行されます。 詳細については、「 イベント ベースのアクティベーションを使用した復号化の実装」を参照してください。
アドインでメッセージの暗号化が解除されます OnMessageDecrypt イベント ハンドラーに独自の復号化プロトコルを実装する必要があります。 アドインがメッセージとその添付ファイルを復号化する際、メッセージがアドインによって処理されていることを知らせる通知がユーザーに表示されます。 この通知は、 OnMessageDecrypt イベントを処理するアドインによって自動的に表示されるため、手動で作成する必要はありません。
受信者が復号化されたメッセージとその添付ファイル (存在する場合) を表示する 暗号化解除操作が完了すると、アドインがメッセージの処理を完了したことを警告する通知が自動的にユーザーに表示されます。 OnMessageDecrypt ハンドラーで event.completed メソッドを呼び出し、MessageDecryptEventCompletedOptions オブジェクトを渡します。 MessageDecryptEventCompletedOptions オブジェクトを使用すると、復号化されたコンテンツを受信者に表示するかどうかを指定できます。 詳細については、「 イベント処理の実装」を参照してください。

完成したアドインを試す

完了した暗号化アドインの動作をすぐに確認するには、「 Outlook でメッセージを暗号化および復号化する」サンプルをお試しください。

イベントベースのアクティベーションを使用して暗号化解除を実装する

独自の暗号化および復号化プロトコルを実装する必要があります。 また、アドインがメッセージを復号化して復号化された内容を表示できるタイミングを簡単に判断できるように、 OnMessageDecrypt イベントを処理するようにアドインを構成する必要もあります。 OnMessageDecrypt イベントを実装するには、次の手順を実行する必要があります。

  1. アドインのマニフェストを構成します。
  2. イベント処理を実装します。

サポートされている環境

OnMessageDecrypt イベントは、メッセージ読み取りサーフェスでサポートされています。 次の表に示すように、サポートはクライアントおよび Exchange 環境によって異なります。

クライアント Exchange Online Exchange サブスクリプション エディション (SE) Exchange Server 2019 Exchange Server 2016
Web ブラウザー サポート 使用不可 使用不可 使用不可
Windows (新規) サポート 使用不可 使用不可 使用不可
Windows (クラシック)
バージョン 2602 (ビルド 19725.20126) 以降		 サポート 使用不可 使用不可 使用不可
Mac 使用不可 使用不可 使用不可 使用不可
Android 使用不可 使用不可 使用不可 使用不可
iOS 使用不可 使用不可 使用不可 使用不可

マニフェストを構成する

注:

OnMessageDecrypt イベントと "extensions.autoRunEvents.events.options.headerName" プロパティは、統合マニフェストでプレビュー段階です。 運用アドインの統合マニフェストで暗号化解除機能を使用しないでください。

アドインの manifest.json ファイルで、アドインでイベント ベースのアクティベーションを有効にするには、 "extensions.runtimes" 配列を構成し、 "extensions.autoRunEvents" 配列を追加する必要があります。

  1. "extensions.runtimes" 配列に次のオブジェクトを追加します。 このマークアップについて、次の情報にご注意ください。

    • ランタイムの "id" は、わかりやすい名前 "autorun_runtime" に設定されます。
    • "code" プロパティには、HTML ファイルに設定された子 "page" プロパティと、JavaScript ファイルに設定された子 "script" プロパティがあります。 Office では、プラットフォームに応じてこれらのいずれかの値を使用します。
      • Outlook on the web と新しい Outlook on Windows では、ブラウザー ランタイムでハンドラーが実行され、HTML ファイルが読み込まれます。 このファイルには、JavaScript ファイルを読み込む <script> タグが含まれています。
      • 従来の Outlook on Windows では、JavaScript ファイルを直接読み込む JavaScript のみのランタイムでイベント ハンドラーを実行します。 詳細については、「 Office アドインのランタイム」を参照してください。
    • "lifetime" プロパティは "short" に設定されています。つまり、ランタイムはイベントがトリガーされたときに起動し、ハンドラーが完了するとシャットダウンします。
    • アクションは 、JavaScript ハンドラーを OnMessageSend イベントと OnMessageDecrypt イベントにマップします。
    "runtimes": [
    {
        "requirements": {
            "capabilities": [
                {
                    "name": "Mailbox",
                    "minVersion": "1.16"
                }
            ]
        },
        "id": "autorun_runtime",
        "type": "general",
        "code": {
            "page": "https://localhost:3000/launchevents.html",
            "script": "https://localhost:3000/launchevents.js"
        },
        "lifetime": "short",
        "actions": [
            {
                "id": "onMessageSendHandler",
                "type": "executeFunction"
            },
            {
                "id": "onMessageDecryptHandler",
                "type": "executeFunction"
            }
        ]
    }
],

  2. "extensions"配列内のオブジェクトのプロパティとして、次の "autoRunEvents" 配列を追加します。 このマークアップについて、次の情報にご注意ください。

    • イベント オブジェクトは、アドインが処理するイベントごとに作成されます。 このサンプルでは、 OnMessageSend 用に 1 つ、 OnMessageDecrypt用にもう 1 つのイベント オブジェクトが作成されます。 どちらのイベントも、サポートされているイベントの表で説明されているように、統合されたマニフェスト イベント名 "messageSending" と "messageDecrypt" を使用します。
    • イベント発生時に適切なハンドラーが実行されるようにするには、"actionId" で指定された関数名が、前の手順の "runtimes.actions" 配列内の該当するオブジェクトの "id" プロパティで使用されている名前と一致する必要があります。
    • "options" プロパティは、OnMessageSend イベントとOnMessageDecrypt イベントの追加構成を提供します。
      • OnMessageSend の場合、"sendMode" オプションは、アドインの条件を満たさない場合にユーザーがメッセージを送信できるかどうかを指定します。 このサンプルでは、 "softBlock" オプションが指定されています。 送信モード オプションの詳細については、「 スマート アラートを使用して Outlook アドインで OnMessageSend イベントと OnAppointmentSend イベントを処理する」の「利用可能な送信モード オプション」セクションを参照してください。
      • OnMessageDecryptでは、"headerName" オプションは、メッセージがアドインによって暗号化されたかどうかを識別するために使用するインターネット ヘッダー名を指定します。 アドインによって暗号化されたメッセージに同じヘッダーが追加される。
    "autoRunEvents": [
    {
        "events": [
          {
              "type": "messageSending",
              "actionId": "onMessageSendHandler",
              "options": {
                  "sendMode": "softBlock"
              }
          },
          {
              "type": "messageDecrypt",
              "actionId": "onMessageDecryptHandler",
              "options": {
                  "headerName": "contoso-encrypted"
              }
          }
        ]
    }
]

イベント処理の実装

OnMessageDecrypt イベント ハンドラーは、復号化操作を実行し、メッセージの復号化された内容を表示するかどうかを決定するために使用されます。

  • OnMessageDecrypt イベントが発生したときにハンドラーが確実に実行されるようにするには、ハンドラーが実装されている JavaScript ファイルで Office.actions.associate を呼び出します。 これにより、マニフェスト内の <LaunchEvent> 要素の FunctionName 属性で指定されたハンドラー名が、それに対応する JavaScript にマップされます。
  • 暗号化解除操作が完了したら、 event.completed を呼び出して、アドインが OnMessageDecrypt イベントの処理を完了したことをクライアントに通知する必要があります。 メッセージとその添付ファイルの復号化された内容を表示するには、 MessageDecryptEventCompletedOptions オブジェクトを event.completed 呼び出しに渡し、その allowEvent プロパティを true に設定します。 次に、オブジェクトの emailBody プロパティと添 付ファイル プロパティで、メッセージの暗号化解除された内容を指定します。 アドインの処理に必要なデータを contextData プロパティで指定することもできます。 たとえば、返信および転送のシナリオでメッセージを復号化するために、カスタム インターネット ヘッダーを保存できます。

注:

従来の Outlook on Windows 用のイベント ベースのアドインを作成するときは、次の点に注意してください。

  • イベント ハンドラーを含む JavaScript ファイルでは、現在インポートはサポートされていません。
  • イベントを処理するためにマニフェストで指定された JavaScript 関数が実行されても、 Office.onReady() と Office.initialize のコードは実行されません。 ユーザーの Outlook バージョンの確認など、イベント ハンドラーに必要なスタートアップ ロジックを代わりにイベント ハンドラーに追加することをお勧めします。

OnMessageDecrypt イベント ハンドラーの例を次に示します。

function onMessageDecryptHandler(event) {
    // Your code to decrypt the contents of a message would appear here.
    ...

    // Use the results from your decryption process to display the decrypted contents of the message body and attachments.
    const decryptedBodyContent = "<p>Please find attached the recent report and its supporting documentation.</p>";
    const decryptedBody = {
        coercionType: Office.CoercionType.Html,
        content: decryptedBodyContent
    };

    // Decrypted content and properties of a file attachment.
    const decryptedPdfFile = "JVBERi0xLjQKJeLjz9MKNCAwIG9i...";
    const pdfFileName = "Fabrikam_Report_202509";

    // Decrypted properties of a cloud attachment.
    const cloudFilePath = "https://contosostorage.com/reports/weekly_forecast.xlsx";
    const cloudFileName = "weekly_forecast.xlsx";

    // Decrypted content and properties of an inline image.
    const decryptedImageFile = "iVBORw0KGgoAAAANSUhEUgAA...";
    const imageFileName = "banner.png";
    const imageContentId = "image001.png@01DC1DD9.1A4AA300";

    const decryptedAttachments = [
        {
            attachmentType: Office.MailboxEnums.AttachmentType.File,
            content: decryptedPdfFile,
            isInline: false,
            name: pdfFileName
        },
        {
            attachmentType: Office.MailboxEnums.AttachmentType.Cloud,
            isInline: false,
            name: cloudFileName,
            path: cloudFilePath
        },
        {
            attachmentType: Office.MailboxEnums.AttachmentType.File,
            content: decryptedImageFile,
            contentId: imageContentId,
            isInline: true,
            name: imageFileName
        }
    ];

    event.completed({
        allowEvent: true,
        emailBody: decryptedBody,
        attachments: decryptedAttachments,
        contextData: { messageType: "ReplyFromDecryptedMessage" }
    });
}

// IMPORTANT: To ensure your add-in is supported in Outlook, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
Office.actions.associate("onMessageDecryptHandler", onMessageDecryptHandler);

ヒント

画像がインライン添付ファイルとしてメッセージに追加されると、コンテンツ ID が自動的に割り当てられます。 メッセージの本文では、次の例のように、インライン添付ファイルのコンテンツ ID を <img> 要素の src 属性で指定します。

<img width=96 height=96 id="Picture_1" src="cid:image001.png@01DC1E6F.FC7C7410">

復号化中にこれらのインライン添付ファイルを簡単に識別して提供できるように、暗号化中にインライン添付ファイルのコンテンツ ID をメッセージ ヘッダーに保存することをお勧めします。 Office.context.mailbox.item.getAttachmentsAsync を呼び出して、インライン添付ファイルのコンテンツ ID を取得します。 次に、 Office.context.mailbox.item.internetHeaders.setAsync を呼び出して、ID をメッセージのヘッダーに保存します。

Outlook アイテムの添付ファイルの暗号化を解除する (プレビュー)

Outlook アイテムの添付ファイル (Office.MailboxEnums.AttachmentType.Item、特にメールの添付ファイル) の復号化のサポートは、Outlook on the web と Windows (新規およびクラシック) でプレビューで利用できます。 従来の Outlook on Windows でこの機能をプレビューするには、バージョン 2606 (ビルド 20114.15110) 以降をインストールする必要があります。 次に、 Microsoft 365 Insider プログラム に参加し、 ベータ チャネル オプションを選択して Office ベータ ビルドにアクセスします。 この記事のサンプル コードを使用してこの機能をテストするには、次のコードで onMessageDecryptHandler 関数を更新します。

    // Decrypted content and properties of an email attachment.
    const decryptedEmailFile = "VGhpcyBpcyBhIHRleHQgZmlsZS4=...";
    const emailFileName = "Fabrikam_Report_202508.eml";

    const decryptedAttachments = [
        ...
        {
            attachmentType: Office.MailboxEnums.AttachmentType.Item,
            content: decryptedEmailFile,
            name: emailFileName
        }
    ];
    ...

暗号化解除操作のエラー メッセージをカスタマイズする (プレビュー)

暗号化解除操作が失敗した場合のカスタム エラー メッセージは、Outlook on the web および Windows (新規およびクラシック) でプレビューできます。 従来の Outlook on Windows でこの機能をプレビューするには、バージョン 2606 (ビルド 20114.15110) 以降をインストールする必要があります。 次に、 Microsoft 365 Insider プログラム に参加し、 ベータ チャネル オプションを選択して Office ベータ ビルドにアクセスします。

暗号化解除操作が失敗した場合、event.completed呼び出しの allowEvent プロパティは false に設定され、Outlook はユーザーに「<アドイン名> メッセージを処理できませんでした」という既定の通知を表示します。カスタム エラー メッセージを指定するには、アドインの event.completed 呼び出しの errorMessage プロパティを設定します。 カスタム メッセージには、" <アドイン名からのエラー>:"というプレフィックスが付きます。 カスタム メッセージを表示できない場合は、代わりに既定の通知が表示されます。

次のコード サンプルは、暗号化解除アドインのカスタム エラー メッセージを指定する方法を示しています。

event.completed({
    allowEvent: false,
    errorMessage: "This message couldn't be decrypted. Contact the Contoso IT team for further assistance."
});

復号化されたコンテンツの配布を管理する (プレビュー)

復号化されたコンテンツの不正配布を防ぐために、アクセス制御オプションは、Outlook on the web と Windows (新旧) でプレビューできます。 従来の Outlook on Windows でこの機能をプレビューするには、バージョン 2606 (ビルド 20114.15110) 以降をインストールする必要があります。 次に、 Microsoft 365 Insider プログラム に参加し、 ベータ チャネル オプションを選択して Office ベータ ビルドにアクセスします。

復号化されたコンテンツの印刷、コピー、または保存を制限するには、event.completed呼び出しの accessControls プロパティを含めます。 次に、 allowPrint、 allowCopyPaste、および allowSave プロパティを false に設定します。 accessControls プロパティが指定されていない場合、アクセス制御は既定で true になります。

この記事のサンプル コードを使用してこの機能をテストするには、onMessageDecryptHandler 関数のevent.completed呼び出しを次のコードで更新します。

    event.completed({
        allowEvent: true,
        emailBody: decryptedBody,
        attachments: decryptedAttachments,
        contextData: { messageType: "ReplyFromDecryptedMessage" },
        accessControls: {
            allowPrint: false,
            allowCopyPaste: false,
            allowSave: false
        }
    });

注:

  • Outlook on the web では、allowCopyPaste プロパティを false に設定すると、ユーザーがスクリーンショットや録画の形で画面をキャプチャできなくなります。 画面キャプチャ ポリシーは、ユーザーが Outlook ブラウザーのタブを再度読み込むまで有効です。
  • Outlook on the web および新しい Outlook on Windows では、allowPrint プロパティを false に設定すると、コンテキスト メニュー (コピー、すべて選択、印刷などのオプションが提供されます) が無効になります。 allowCopyPaste プロパティが true に設定されている場合でも、ユーザーは Ctrl+C キーを押してコンテンツをコピーできますが、コンテキスト メニューの [コピー] オプションは使用できません。

動作と制限事項

  • イベント ベースのアドインの動作と制限事項に注意してください。詳細については、「 イベントを使用してアドインをアクティブ化する」を参照してください。

  • 各アドインは独自の暗号化プロトコルを使用するため、メッセージを暗号化した同じアドインによってのみメッセージを復号化できます。 メッセージの暗号化を解除するために必要なアドインをユーザーがインストールしていない場合、メッセージが暗号化されていることを通知します。 ユーザーに暗号化解除プロセスをガイドするには、暗号化されたメッセージの本文のプレースホルダー メッセージをカスタマイズします。 プレースホルダー メッセージには、アドインをインストールする方法に関する情報を含めることができます。 暗号化処理中にメッセージ本文を設定するには、 Office.context.mailbox.item.body.setAsync を呼び出します。

    暗号化されたメッセージのプレースホルダー メッセージのサンプル。

  • データのセキュリティと機密性を確保するため、復号化されたコンテンツは Outlook クライアントに保存されません。 暗号化されたメッセージの内容は、ユーザーが開くたびに復号化されます。

  • 暗号化されたメッセージは、ユーザーが返信または転送する前に、最初に復号化する必要があります。 暗号化されたメッセージの復号化中は、そのメッセージに返信または転送することはできません。

  • 暗号化されたメッセージの復号化中にユーザーが別のメール アイテムに移動すると、復号化プロセスの実行が停止します。 復号化プロセスをアクティブにするには、ユーザーが再度メッセージを選択するか開く必要があります。

  • 暗号化されたメッセージに返信または転送するとき、下書きは暗号化されずに 下書きフォルダー に保存されます。

  • event.completed メソッドの attachments プロパティは、Outlook on the web および Windows (新旧およびクラシック) のプレビューを除き、種類 Office.MailboxEnums.AttachmentType.Item の添付ファイルをサポートしません。 詳細については、「 Outlook アイテムの添付ファイルの暗号化を解除する (プレビュー)」を参照してください。

  • カスタム暗号化アドインでは、DRM または S/MIME によって既に保護されているメッセージを暗号化することはできません。

  • Outlook on the web と新しい Outlook on Windows では、暗号化されたメッセージが会話ごとにグループ化されると、会話スレッドから現在選択されているメッセージのみが復号化されます。 スレッド内の他のメッセージは、選択されるまで暗号化されたままになります。

  • Outlook on the web と新しい Outlook on Windows では、ユーザーは EML 形式の復号化されたメッセージのみをダウンロードできます。 MSG 形式でダウンロードするオプションは利用できません。

暗号化解除通知

次の表に示すように、 OnMessageDecrypt イベントを処理するアドインは、特定の復号化シナリオで自動的に通知を表示します。

Notification シナリオ
<アドイン名> は利用できず、現在メッセージを処理できません。 従来の Outlook on Windows にのみ適用されます。 この通知は、エラーによってアドインの読み込みに失敗した場合、またはユーザーのクライアントまたはコンピューターがオフラインの場合に表示されます。
<アドイン名> メッセージを処理できませんでした。 アドインがメッセージを解読しているときにエラーが発生しました。 暗号化解除操作を再試行するには、受信者が別のメッセージに切り替え、暗号化されたメッセージを再度開いて OnMessageDecrypt イベントを呼び出す必要があります。
<アドイン名> アドインがメッセージを復号化しています。 アドインは、メッセージを復号化するために OnMessageDecrypt イベントを処理しています。
このメッセージは、 <アドイン名> アドインで暗号化されます。 この通知は、必要な暗号化アドインをインストールしていない受信者に表示されます。 メッセージの暗号化を解除する方法に関するガイダンスを提供するために、暗号化されたメッセージの本文にプレースホルダー メッセージを含めます。 詳細については、「 動作と制限事項」を参照してください。
<アドイン名> アドインによってメッセージが復号化されました。 アドインによってメッセージの内容の暗号化が正常に解除されました。 これで、ユーザーはメッセージとその添付ファイルを表示できるようになります。
<アドイン名> メッセージの処理に予想以上に時間がかかる。 アドインが実行されている時間が 5 秒を超えているが、5 分未満である。
<アドイン名> タイムアウトしました。もう一度試すには、別のメールを選択してから、このメッセージに戻ります。 アドインは 5 分間実行された後にタイムアウトします。 暗号化解除操作を再試行するには、受信者が別のメッセージに切り替え、暗号化されたメッセージを再度開いて OnMessageDecrypt イベントを呼び出す必要があります。
<アドイン名> タイムアウトしました。(プレビュー) アドインは 5 分間実行された後にタイムアウトします。 この通知には再 試行 アクションが含まれ、受信者は別のメッセージに切り替えずに復号化操作を再試行できます。 この再試行機能は、Outlook on the web と Windows (新旧) でプレビューできます。 従来の Outlook on Windows でこの機能をプレビューするには、バージョン 2606 (ビルド 20114.15110) 以降をインストールする必要があります。 次に、 Microsoft 365 Insider プログラム に参加し、 ベータ チャネル オプションを選択して Office ベータ ビルドにアクセスします。
<アドイン名> は、組み込みのセキュリティ機能によって保護されているため、このメッセージを処理できません。 アドインが、DRM または S/MIME によって既に保護されているメッセージを処理しようとします。
カスタム エラー メッセージ (プレビュー) アドインがメッセージを解読しているときにエラーが発生しました。 暗号化解除操作を再試行するには、受信者が別のメッセージに切り替え、暗号化されたメッセージを再度開いて OnMessageDecrypt イベントを呼び出す必要があります。 暗号化解除操作のエラー メッセージをカスタマイズする方法のガイダンスについては、「 暗号化解除操作のエラー メッセージをカスタマイズする (プレビュー)」を参照してください。

関連項目

  • Last updated on