Erstellen eines Outlook-Verschlüsselungs-Add-Ins (Vorschau)

Implementieren Sie benutzerdefinierte Verschlüsselungs- und Entschlüsselungsfunktionen in einem Outlook-Add-In, um die E-Mail-Kommunikation zu schützen. Das OnMessageRead -Ereignis ermöglicht es Ihrem Add-In, verschlüsselte Nachrichten automatisch zu identifizieren und Entschlüsselung, Inhaltsanzeige und Fehlerbenachrichtigungen zu verarbeiten.

Übersicht über die Verschlüsselungs- und Entschlüsselungsworkflows

Die folgende Tabelle enthält eine Übersicht über die Ver- und Entschlüsselungsworkflows eines Outlook-Add-Ins. Außerdem wird ermittelt, ob ein Schritt eine benutzerdefinierte Lösung erfordert oder von der Office JavaScript-API-Bibliothek (Office.js) unterstützt wird.

Implementieren der Entschlüsselung mithilfe der ereignisbasierten Aktivierung

Sie müssen Ihre eigenen Verschlüsselungs- und Entschlüsselungsprotokolle implementieren. Das Add-In muss auch für die Behandlung des OnMessageRead Ereignisses konfiguriert werden, um bequem zu bestimmen, wann Ihr Add-In eine Nachricht entschlüsseln und den entschlüsselten Inhalt anzeigen kann. Um das OnMessageRead Ereignis zu implementieren, müssen Sie:

1. Konfigurieren Sie das Manifest des Add-Ins.
2. Implementieren sie die Ereignisbehandlung.

Unterstützte Umgebungen

Das OnMessageRead Ereignis wird auf der Nachrichtenleseoberfläche unterstützt. Die Unterstützung variiert je nach Client- und Exchange-Umgebung, wie in der folgenden Tabelle gezeigt.

Vorschau der Entschlüsselungs-APIs im klassischen Outlook unter Windows

Um eine Vorschau der Entschlüsselungs-APIs im klassischen Outlook unter Windows anzuzeigen, treten Sie dem Microsoft 365 Insider-Programm bei, und wählen Sie dann den Betakanal im Outlook-Client aus. Ihr Client muss version 2510 (Build 19312.20000) oder höher aufweisen.

Das klassische Outlook unter Windows enthält eine lokale Kopie der Produktions- und Betaversionen von Office.js, anstatt aus dem Content Delivery Network (CDN) zu laden. Standardmäßig wird auf die lokale Produktionskopie der API verwiesen. Um auf die lokale Betakopie der API zu verweisen, müssen Sie die Registrierung Ihres Computers konfigurieren. Dadurch können Sie Vorschaufeatures in Ihren Ereignishandlern im klassischen Outlook unter Windows testen.

1. Navigieren Sie in der Registrierung zu HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer. Wenn der Schlüssel nicht vorhanden ist, erstellen Sie ihn.

2. Erstellen Sie einen Eintrag namens , EnableBetaAPIsInJavaScript und legen Sie dessen Wert auf fest 1.

   

Konfigurieren des Manifests

Um Ihr Add-In für das OnMessageRead Ereignis zu aktivieren, müssen Sie den <VersionOverridesV1_1> Knoten der manifest.xml-Datei Ihres Add-Ins wie folgt konfigurieren.

• Zum Ausführen eines ereignisbasierten Add-Ins im klassischen Outlook unter Windows müssen Sie die JavaScript-Datei angeben, die den Ereignishandler im <untergeordneten Element Außerkraftsetzung> des <Runtime-Elements> enthält.
• Geben Sie das OnMessageRead -Ereignis im Type -Attribut eines <LaunchEvent-Elements> an. Sie müssen dem -Attribut des -Elements den FunctionName Funktionsnamen des Ereignishandlers zuweisen. Um die Überprüfung zu erleichtern, ob die Nachricht vom Add-In verschlüsselt wurde, muss im HeaderName -Attribut ein Headerschlüssel angegeben werden. Derselbe Header wird einer Nachricht hinzugefügt, die vom Add-In verschlüsselt wird.

Es folgt ein Beispiel für einen <VersionOverrides> Knoten, der das OnMessageRead -Ereignis implementiert.

<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
    <Requirements>
      <bt:Sets DefaultMinVersion="1.15">
        <bt:Set Name="Mailbox"/>
      </bt:Sets>
    </Requirements>
    <Hosts>
      <Host xsi:type="MailHost">
        <Runtimes>
            <!-- References the HTML file that links to the event handler. -->
          <Runtime resid="WebViewRuntime.Url">
            <!-- References the JavaScript file that contains the event handler. This is used by classic Outlook on Windows. -->
            <Override type="javascript" resid="JSRuntime.Url"/>
          </Runtime>
        </Runtimes>
        <DesktopFormFactor>
          <FunctionFile resid="WebViewRuntime.Url"/>
          <!-- Implements event-based activation. -->
          <ExtensionPoint xsi:type="LaunchEvent">
            <LaunchEvents>
              <LaunchEvent Type="OnMessageSend" FunctionName="onMessageSendHandler" SendMode="SoftBlock"/>
              <LaunchEvent Type="OnMessageRead" FunctionName="onMessageReadHandler" HeaderName="contoso-encrypted"/>
            </LaunchEvents>
            <!-- Identifies the runtime to be used (also referenced by the Runtime element). -->
            <SourceLocation resid="WebViewRuntime.Url"/>
        </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      ...
      <bt:Urls>
        <bt:Url id="WebViewRuntime.Url" DefaultValue="https://www.contoso.com/launchevent.html"/>
        <bt:Url id="JSRuntime.Url" DefaultValue="https://www.contoso.com/launchevent.js"/>
      </bt:Urls>
      ...
    </Resources>
  </VersionOverrides>
</VersionOverrides>

Implementieren der Ereignisbehandlung

Der OnMessageRead Ereignishandler wird verwendet, um den Entschlüsselungsvorgang auszuführen und zu bestimmen, ob der entschlüsselte Inhalt einer Nachricht angezeigt werden soll.

• Um sicherzustellen, dass der Handler ausgeführt wird, wenn das OnMessageRead Ereignis auftritt, rufen Sie Office.actions.associate in der JavaScript-Datei auf, in der der Handler implementiert ist. Dadurch wird der im -Attribut des <LaunchEvent> -Elements im FunctionName Manifest angegebene Handlername dem JavaScript-Gegenstück zugeordnet.
• Sobald der Entschlüsselungsvorgang abgeschlossen ist, müssen Sie aufrufen event.completed , um dem Client zu signalisieren, dass das Add-In die Verarbeitung des OnMessageRead Ereignisses abgeschlossen hat. Um den entschlüsselten Inhalt einer Nachricht und ihrer Anlagen anzuzeigen, übergeben Sie ein MessageDecryptEventCompletedOptions-Objekt an den event.completed Aufruf, und legen Sie dessen allowEvent-Eigenschaft auf fest true. Geben Sie dann den entschlüsselten Inhalt der Nachricht in den Eigenschaften emailBody und attachments des Objekts an. Sie können auch alle Daten angeben, die Ihr Add-In für die Verarbeitung in der contextData-Eigenschaft benötigt. Beispielsweise können Sie benutzerdefinierte Internetheader speichern, um Nachrichten in Antwort- und Weiterleitungsszenarien zu entschlüsseln.

Es folgt ein Beispiel für einen OnMessageRead Ereignishandler.

function onMessageReadHandler(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 content and properties of a mail item.
    const decryptedEmailFile = "VGhpcyBpcyBhIHRleHQgZmlsZS4=...";
    const emailFileName = "Fabrikam_Report_202508.eml";

    // 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.Item,
            content: decryptedEmailFile,
            isInline: false,
            name: emailFileName
        },
        {
            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("onMessageReadHandler", onMessageReadHandler);

Verhalten und Einschränkungen

• Beachten Sie das Verhalten und die Einschränkungen ereignisbasierter Add-Ins. Weitere Informationen finden Sie unter Aktivieren von Add-Ins mit Ereignissen.

• Da jedes Add-In ein eigenes Verschlüsselungsprotokoll verwendet, kann eine Nachricht nur von demselben Add-In entschlüsselt werden, das sie verschlüsselt hat. Wenn ein Benutzer nicht das erforderliche Add-In zum Entschlüsseln einer Nachricht installiert hat, wird er in einer Benachrichtigung darüber benachrichtigt, dass die Nachricht verschlüsselt ist. Um den Benutzer durch den Entschlüsselungsprozess zu führen, passen Sie eine Platzhalternachricht für den Text der verschlüsselten Nachricht an. Die Platzhaltermeldung kann Informationen zur Installation des Add-Ins enthalten. Um den Nachrichtentext während des Verschlüsselungsvorgangs festzulegen, rufen Sie Office.context.mailbox.item.body.setAsync auf.

  

• Um Datensicherheit und Vertraulichkeit sicherzustellen, werden entschlüsselte Inhalte nicht auf dem Outlook-Client gespeichert. Der Inhalt einer verschlüsselten Nachricht wird jedes Mal entschlüsselt, wenn ein Benutzer sie öffnet.

• Eine verschlüsselte Nachricht muss zuerst entschlüsselt werden, bevor ein Benutzer sie beantworten oder weiterleiten kann. Ein Benutzer kann eine verschlüsselte Nachricht nicht beantworten oder weiterleiten, während sie entschlüsselt wird.

• Wenn ein Benutzer zu einem anderen E-Mail-Element navigiert, während eine verschlüsselte Nachricht entschlüsselt wird, wird der Entschlüsselungsprozess beendet. Der Benutzer muss die Nachricht erneut auswählen oder öffnen, um den Entschlüsselungsprozess zu aktivieren.

• Beim Beantworten oder Weiterleiten verschlüsselter Nachrichten werden Entwürfe unverschlüsselt im Ordner Entwürfe gespeichert.

Entschlüsselungsbenachrichtigungen

Add-Ins, die das OnMessageRead Ereignis behandeln, zeigen automatisch Benachrichtigungen in bestimmten Entschlüsselungsszenarien an, wie in der folgenden Tabelle beschrieben.

Siehe auch

• Datenschutz und Sicherheit für Office-Add-Ins
• Aktivieren von Add-Ins mit Ereignissen
• Problembehandlung bei ereignisbasierten Add-Ins und Spam-Berichts-Add-Ins
• Abrufen und Festlegen von Internetheadern für eine Nachricht in einem Outlook-Add-In
• Verwalten der Vertraulichkeitsbezeichnung Ihrer Nachricht oder Ihres Termins im Verfassenmodus