Créer un complément Outlook de chiffrement (préversion)

Implémentez des fonctionnalités de chiffrement et de déchiffrement personnalisées dans un complément Outlook pour sécuriser les communications par e-mail. L’événement OnMessageRead permet à votre complément d’identifier automatiquement les messages chiffrés et de gérer le déchiffrement, l’affichage du contenu et les notifications d’erreur.

Remarque

Les OnMessageRead API d’événement et de déchiffrement sont en préversion. Les fonctionnalités en préversion ne doivent pas être utilisées dans les compléments de production, car elles peuvent changer en fonction des commentaires que nous recevons. Nous vous invitons à tester cette fonctionnalité dans des environnements de test ou de développement et à recevoir des commentaires sur votre expérience via GitHub (voir la section « Commentaires sur les compléments Office » à la fin de cette page).

Vue d’ensemble des workflows de chiffrement et de déchiffrement

Conseil

Les workflows de chiffrement et de déchiffrement implémentent la fonctionnalité d’activation basée sur les événements. Si vous n’êtes pas familiarisé avec l’activation basée sur les événements dans les compléments Outlook, nous vous recommandons d’en savoir plus sur la fonctionnalité et son implémentation. Pour plus d’informations, consultez Activer des compléments avec des événements.
L’ensemble minimal de conditions requises et les plateformes prises en charge peuvent varier pour chaque API recommandée dans cette section. Nous vous recommandons de vérifier toutes les exigences par rapport aux ensembles de conditions requises de l’API JavaScript Outlook et de les compléter avec la documentation de l’API spécifique.

Le tableau suivant fournit une vue d’ensemble des workflows de chiffrement et de déchiffrement d’un complément Outlook. Il identifie également si une étape nécessite une solution personnalisée ou est prise en charge par la bibliothèque d’API JavaScript (Office.js) Office.

Étape	Implémentation
L’utilisateur compose un message et utilise votre complément pour appliquer des règles de chiffrement	Vous devez implémenter votre propre protocole de chiffrement afin que le complément puisse sécuriser le contenu du message et ses pièces jointes.
L’utilisateur envoie le message	Implémentez un gestionnaire pour l’événement OnMessageSend afin que votre complément puisse exécuter automatiquement votre protocole de chiffrement lorsque l’utilisateur sélectionne Envoyer. Pour identifier un message chiffré à l’aide de votre complément pendant le processus de déchiffrement, utilisez les API d’en-têtes Internet pour ajouter un en-tête à un message. La clé d’en-tête doit correspondre à la valeur spécifiée dans l’attribut `HeaderName` de l’élément <LaunchEvent> pour l’événement OnMessageRead dans le manifeste du complément. Pour plus d’informations, consultez Implémenter le déchiffrement à l’aide de l’activation basée sur les événements.
Le destinataire reçoit le message chiffré et l’ouvre	Si le destinataire a le même complément que celui utilisé pour chiffrer le message installé dans Outlook, le complément vérifie si la clé d’en-tête incluse dans le message correspond à la valeur spécifiée pour l’événement `OnMessageRead` dans le manifeste. Cette opération est effectuée automatiquement par un complément qui gère l’événement`OnMessageRead`, afin que vous n’ayez pas à implémenter manuellement le case activée. Si les en-têtes correspondent, l’événement `OnMessageRead` se produit et son gestionnaire s’exécute. Pour plus d’informations, consultez Implémenter le déchiffrement à l’aide de l’activation basée sur les événements.
Le complément déchiffre le message	Vous devez implémenter votre propre protocole de déchiffrement dans le gestionnaire d’événements `OnMessageRead` . Pendant que votre complément déchiffre le message et ses pièces jointes, une notification est présentée à l’utilisateur pour l’avertir que son message est en cours de traitement par le complément. Cette notification est automatiquement affichée par un complément qui gère l’événement `OnMessageRead` , afin que vous n’ayez pas à en créer un manuellement.
Le destinataire affiche le message déchiffré et ses pièces jointes, le cas échéant	Une fois l’opération de déchiffrement terminée, une notification s’affiche automatiquement à l’utilisateur pour l’avertir que le complément a terminé le traitement du message. Dans votre `OnMessageRead` gestionnaire, appelez la méthode event.completed et passez-lui un objet MessageDecryptEventCompletedOptions . Avec l’objet `MessageDecryptEventCompletedOptions` , vous pouvez spécifier s’il faut afficher le contenu déchiffré au destinataire. Pour plus d’informations, consultez Implémenter la gestion des événements.

Implémenter le déchiffrement à l’aide de l’activation basée sur les événements

Vous devez implémenter vos propres protocoles de chiffrement et de déchiffrement. Le complément doit également être configuré pour gérer l’événement OnMessageRead afin de déterminer facilement quand votre complément peut déchiffrer un message et afficher le contenu déchiffré. Pour implémenter l’événement OnMessageRead , vous devez :

Configurez le manifeste du complément.
Implémenter la gestion des événements.

Environnements pris en charge

L’événement OnMessageRead est pris en charge sur la surface de lecture du message. La prise en charge varie selon le client et l’environnement Exchange, comme indiqué dans le tableau suivant.

Client	Exchange Online	Exchange Subscription Edition (SE)	Exchange Server 2019	Exchange Server 2016
Navigateur Web	Non disponible	Non disponible	Non disponible	Non disponible
Windows (nouveau)	Non disponible	Non disponible	Non disponible	Non disponible
Windows (classique) Version 2510 (build 19312.20000) et versions ultérieures	Dans la préversion	Non disponible	Non disponible	Non disponible
Mac	Non disponible	Non disponible	Non disponible	Non disponible
Android	Non disponible	Non disponible	Non disponible	Non disponible
iOS	Non disponible	Non disponible	Non disponible	Non disponible

Afficher un aperçu des API de déchiffrement dans Outlook classique sur Windows

Pour afficher un aperçu des API de déchiffrement dans Outlook classique sur Windows, rejoignez le programme Microsoft 365 Insider, puis choisissez le canal bêta dans le client Outlook. Votre client doit être sur la version 2510 (build 19312.20000) ou ultérieure.

Outlook classique sur Windows inclut une copie locale des versions de production et bêta de Office.js au lieu de charger à partir du réseau de distribution de contenu (CDN). Par défaut, la copie de production locale de l’API est référencée. Pour référencer la copie bêta locale de l’API, vous devez configurer le registre de votre ordinateur. Cela vous permet de tester les fonctionnalités en préversion dans vos gestionnaires d’événements dans outlook classique sur Windows.

Dans le Registre, accédez à HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer. Si la clé n’existe pas, créez-la.
Créez une entrée nommée EnableBetaAPIsInJavaScript et définissez sa valeur sur 1.

Configurer le manifeste

Remarque

L’événement OnMessageRead ne peut actuellement être implémenté qu’avec un manifeste de complément uniquement.

Pour activer votre complément sur l’événement OnMessageRead , vous devez configurer le <nœud VersionOverridesV1_1> du fichier manifest.xml de votre complément comme suit.

Pour exécuter un complément basé sur des événements dans Outlook classique sur Windows, vous devez spécifier le fichier JavaScript qui contient le gestionnaire d’événements dans l’élément <enfant Override> de l’élément <Runtime> .
Spécifiez l’événement OnMessageRead dans l’attribut Type d’un <élément LaunchEvent> . Vous devez affecter le nom de fonction du gestionnaire d’événements à l’attribut FunctionName de l’élément . Pour faciliter la vérification si le message a été chiffré par le complément, une clé d’en-tête doit être spécifiée dans l’attribut HeaderName . Le même en-tête est ajouté à un message chiffré par le complément.

Voici un exemple de <VersionOverrides> nœud qui implémente l’événement OnMessageRead .

<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>

Implémenter la gestion des événements

Le OnMessageRead gestionnaire d’événements est utilisé pour exécuter l’opération de déchiffrement et déterminer s’il faut afficher le contenu déchiffré d’un message.

Pour vous assurer que votre gestionnaire s’exécute lorsque l’événement OnMessageRead se produit, appelez Office.actions.associate dans le fichier JavaScript où le gestionnaire est implémenté. Cela mappe le nom du gestionnaire spécifié dans l’attribut FunctionName de l’élément <LaunchEvent> dans le manifeste à son équivalent JavaScript.
Une fois l’opération de déchiffrement terminée, vous devez appeler pour signaler event.completed au client que votre complément a terminé le traitement de l’événement OnMessageRead . Pour afficher le contenu déchiffré d’un message et de ses pièces jointes, passez un objet MessageDecryptEventCompletedOptions à l’appel event.completed et définissez sa propriété allowEvent sur true. Ensuite, spécifiez le contenu déchiffré du message dans les propriétés emailBody et pièces jointes de l’objet. Vous pouvez également spécifier toutes les données dont votre complément peut avoir besoin pour le traitement dans la propriété contextData . Par exemple, vous pouvez stocker des en-têtes Internet personnalisés pour déchiffrer les messages dans les scénarios de réponse et de transfert.

Remarque

Tenez compte des points suivants lors de la création d’un complément basé sur des événements pour Outlook classique sur Windows.

Les importations ne sont actuellement pas prises en charge dans le fichier JavaScript contenant le gestionnaire d’événements.
Lorsque la fonction JavaScript spécifiée dans le manifeste pour gérer un événement s’exécute, le code dans Office.onReady() et Office.initialize n’est pas exécuté. Nous vous recommandons d’ajouter au gestionnaire d’événements toute logique de démarrage requise par le gestionnaire d’événements, telle que la vérification de la version d’Outlook de l’utilisateur.

Voici un exemple de gestionnaire d’événements OnMessageRead .

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);

Conseil

Dans Outlook classique sur Windows, lorsque des images sont ajoutées à un message en tant que pièces jointes inline, un ID de contenu leur est automatiquement attribué. Dans le corps d’un message, l’ID de contenu d’une pièce jointe inline est spécifié dans l’attribut src de l’élément <img> , comme dans l’exemple suivant.

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

Pour identifier et fournir facilement ces pièces jointes inline lors du déchiffrement, nous vous recommandons d’enregistrer les ID de contenu des pièces jointes inline dans l’en-tête du message pendant le chiffrement. Appelez Office.context.mailbox.item.getAttachmentsAsync pour obtenir l’ID de contenu d’une pièce jointe inline. Ensuite, appelez Office.context.mailbox.item.internetHeaders.setAsync pour enregistrer l’ID dans l’en-tête du message.

Comportement et limitations

Tenez compte des comportements et des limitations des compléments basés sur les événements. Pour plus d’informations, consultez Activer des compléments avec des événements.
Étant donné que chaque complément utilise son propre protocole de chiffrement, un message ne peut être déchiffré que par le même complément que celui qui l’a chiffré. Lorsqu’un utilisateur n’a pas installé le complément requis pour déchiffrer un message, une notification l’avertit que le message est chiffré. Pour guider l’utilisateur tout au long du processus de déchiffrement, personnalisez un message d’espace réservé pour le corps du message chiffré. Le message d’espace réservé peut inclure des informations sur l’installation de votre complément. Pour définir le corps du message pendant le processus de chiffrement, appelez Office.context.mailbox.item.body.setAsync.
Pour garantir la sécurité et la confidentialité des données, le contenu déchiffré n’est pas stocké sur le client Outlook. Le contenu d’un message chiffré est déchiffré chaque fois qu’un utilisateur l’ouvre.
Un message chiffré doit d’abord être déchiffré avant qu’un utilisateur puisse y répondre ou le transférer. Un utilisateur ne peut pas répondre ou transférer un message chiffré pendant qu’il est déchiffré.
Si un utilisateur accède à un autre élément de courrier pendant qu’un message chiffré est déchiffré, le processus de déchiffrement cesse de s’exécuter. L’utilisateur doit sélectionner ou ouvrir à nouveau le message pour activer le processus de déchiffrement.
Lors de la réponse ou du transfert de messages chiffrés, les brouillons sont enregistrés non chiffrés dans le dossier Brouillons .

Notifications de déchiffrement

Les compléments qui gèrent l’événement OnMessageRead affichent automatiquement des notifications dans certains scénarios de déchiffrement, comme décrit dans le tableau suivant.

Notification	Scénario
<Le nom> du complément n’est pas disponible et ne peut pas traiter votre message pour l’instant.	S’applique uniquement à Outlook classique sur Windows. Cette notification s’affiche lorsque le chargement du complément échoue, car une erreur a empêché le chargement du complément ou parce que le client ou l’ordinateur de l’utilisateur est hors connexion.
<Le nom> du complément n’a pas pu traiter votre message.	Une erreur s’est produite lors du déchiffrement du message par le complément. Pour réessayer l’opération de déchiffrement, le destinataire doit basculer vers un autre message, puis ouvrir à nouveau le message chiffré pour appeler l’événement `OnMessageRead` .
<Le nom> du complément déchiffre votre message.	Le complément gère l’événement `OnMessageRead` pour déchiffrer le message.
Ce message est chiffré par <le nom du complément> .	Cette notification s’affiche pour les destinataires qui n’ont pas le complément de chiffrement nécessaire installé. Pour fournir des conseils sur la façon de déchiffrer le message, incluez un message d’espace réservé dans le corps du message chiffré. Pour plus d’informations, consultez Comportement et limitations.
<Le nom> du complément a déchiffré votre message.	Le complément a correctement déchiffré le contenu du message. L’utilisateur peut désormais afficher le message et ses pièces jointes.
<Le nom> du complément prend plus de temps que prévu pour traiter votre message.	Le complément s’exécute depuis plus de cinq secondes, mais moins de cinq minutes.
<Le nom> du complément a expiré. Pour réessayer, sélectionnez un autre e-mail, puis revenez à ce message.	Le complément expire après une exécution de cinq minutes. Pour réessayer l’opération de déchiffrement, le destinataire doit basculer vers un autre message, puis ouvrir à nouveau le message chiffré pour appeler l’événement `OnMessageRead` .

Voir aussi

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-10-23

Partager via

Créer un complément Outlook de chiffrement (préversion)

Vue d’ensemble des workflows de chiffrement et de déchiffrement

Implémenter le déchiffrement à l’aide de l’activation basée sur les événements

Environnements pris en charge

Afficher un aperçu des API de déchiffrement dans Outlook classique sur Windows

Configurer le manifeste

Implémenter la gestion des événements

Comportement et limitations

Notifications de déchiffrement

Voir aussi

Commentaires

Ressources supplémentaires