Exigences de sécurité pour les messages appelant une action dans Office 365Security requirements for actionable messages in Office 365

La sécurisation des e-mails appelant une action est très simple. Il existe deux phases au sein de l’expérience de bout en bout qui imposent des exigences de sécurité à votre service lors de la prise en charge de messages appelant une action avec Office 365. Les phases et leurs exigences respectives sont les suivantes :Securing actionable email is simple and easy. There are two phases within the end-to-end experience that impose security requirements on your service when supporting actionable messages with Office 365. The phases and their corresponding requirements are as follows.

  1. Phase d’envoi : Les composants requis pour que votre service envoie des messages appelant une action sont les suivants :Send phase: The pre-requisites for your service to send actionable messages are as follows:
    • Si vous utilisez les messages actionnables, vous devez activer la vérification de l’expéditeur.If you're using actionable email, you'll need to enable sender verification. Cela ne s’applique pas aux messages de connecteur.Note that this does not apply to connector messages.
    • Votre service doit être inscrit auprès de Microsoft.Your service must be registered with Microsoft.
    • L’URL d’action doit prendre en charge HTTPS.The Action URL must support HTTPS.
  2. Phase de traitement d’action : Lors du traitement d’une action, votre service doit :Action processing phase: When processing an action, your service should:
    • Vérifier le jeton du porteur (un jeton web JSON) inclus dans l’en-tête de la requête HTTP POST. La vérification peut également être réalisée à l’aide des exemples de bibliothèque fournis par Microsoft.Verify the bearer token (a JSON Web token) included in the header of the HTTP POST request. Verification can also be done leveraging the sample libraries provided by Microsoft.
    • Inclure un jeton limité provenant de votre service dans le cadre de l’URL cible, qui peut être utilisé par votre service pour faire correspondre l’URL de service avec la demande et l’utilisateur souhaités. Cela est facultatif, mais fortement recommandé.Include Limited Purpose Token from your service as part of the target URL, which can be used by your service to correlate the service URL with the intended request & user. This is optional, but highly recommended.

Vérification de l’expéditeurSender verification

Office 365 requiert la vérification de l’expéditeur pour pouvoir activer les messages actionnables via e-mail.Office 365 requires sender verification in order to enable actionable messages via email. Vos messages actionnables doivent provenir de serveurs qui implémentent DKIM (DomainKeys Identified Mail) et SPF (Sender Policy Framework), ou vous devez implémenter des cartes signées.Your actionable message emails must either originate from servers that implement DomainKeys Identified Mail (DKIM) and Sender Policy Framework (SPF), or you must implement signed cards.

DKIM et SPF sont suffisants pour certains scénarios, mais cette solution ne fonctionne pas dans certaines situations où les e-mails sont envoyés via un fournisseur externe car il se peut que les destinataires ne puissent pas utiliser pas la fonction de messages actionnables améliorée.While DKIM and SPF are sufficient for some scenarios, that solution will not work in some situations where emails are sent via an external provider, which can lead to recipients not experiencing the enhanced actionable message. Pour cette raison, nous vous recommandons de toujours implémenter des cartes signées qui fonctionnent dans tous les cas et sont fondamentalement plus sécurisées car elles ne dépendent pas des enregistrements DNS.For this reason, we recommend always implementing signed cards which work in all cases and are fundamentally more secure since they do not rely on DNS records.

Implémentation de DKIM et SPFImplementing DKIM and SPF

DKIM et SPF sont des normes industrielles permettant de prouver l’identité d’un expéditeur lors de l’envoi d’e-mails via SMTP.DKIM and SPF are industry standard ways to prove a sender's identity when sending emails over SMTP. De nombreuses entreprises implémentent déjà ces normes pour sécuriser les e-mails qu’elles envoient.Many companies already implement these standards to secure the emails they are already sending. Pour en savoir plus sur SPF ou DKIM et leur implémentation, reportez-vous à :To learn more about SPF/DKIM and how to implement them, see:

Charges utile de la carte signéeSigned card payloads

Les messages actionnables envoyés par e-mail prennent en charge une différente méthode de vérification : signature de la charge utile de la carte avec une clé RSA ou un certificat X509.Actionable messages sent via email support an alternative verification method: signing the card payload with an RSA key or X509 certificate. Cette méthode est requise dans les scénarios suivants :This method is required in the following scenarios:

  • Échec de SPF/DKIM provoqué par les paramètres expéditeur ou par les services de sécurité personnalisés du client destinataire en aval des services Office 365.SPF/DKIM failure caused by sender setup or recipient tenant set custom security services in front of Office 365 services.
  • Votre scénario relatif aux messages actionnables nécessite un envoi depuis plusieurs comptes de messagerie.Your scenario for actionable messages requires sending from multiple email accounts.

Pour utiliser des cartes signées, vous devez enregistrer votre clé publique dans le tableau de bord du développeur de courrier électronique, puis utiliser la clé privée correspondante pour signer la carte.To use signed cards, you must register your public key in the email developer dashboard, and use the corresponding private key to sign the card.

SignedCardSignedCard

Les cartes de message actionnable signées sont disponibles lors de l’envoi par e-mail.Signed actionable message cards are available when sending via email. Utilisez ce format pour inclure une carte signée dans le corps HTML d’un e-mail.Use this format to include a signed card in the HTML body of an email. Cette charge utile est sérialisée au format Microdata ajouté à la fin du corps HTML.This payload is serialized in Microdata format appended in the end of HTML body.

<section itemscope itemtype="http://schema.org/SignedAdaptiveCard">
    <meta itemprop="@context" content="http://schema.org/extensions" />
    <meta itemprop="@type" content="SignedAdaptiveCard" />
    <div itemprop="signedAdaptiveCard" style="mso-hide:all;display:none;max-height:0px;overflow:hidden;">[SignedCardPayload]</div>
</section>

Remarque : les partenaires qui préfèrent utiliser l’entité MessageCard héritée peuvent créer une entité SignedMessageCard à la place de l’entité SignedAdaptiveCard.Note: Partners who prefer to use the legacy MessageCard entity may create a SignedMessageCard entity in place of a SignedAdaptiveCard.

SignedCardPayloadSignedCardPayload

SignedCardPayload est une chaîne codée JSON Web Signature (JWS).SignedCardPayload is a string encoded by JSON Web Signature (JWS) standard. RFC7515 décrit JWS, et RFC7519 décrit JSON Web Token (JWT).RFC7515 describes JWS, and RFC7519 describes JSON Web Token (JWT). Étant donné qu'aucun claim n'est requis dans JWT, les bibliothèques JWT peuvent être utilisées pour construire la signature JWS.Given no claim is required in JWT, JWT libraries can be used to build JWS signature.

Remarque : le terme « JWT » peut être utilisé de manière interchangeable dans la pratique.Note: The term "JWT" can be used interchangeably in practice. Toutefois, nous préférons ici utiliser le terme « JWS ».However, we prefer the term "JWS" here.

Voici un exemple de SignedCardPayload.Here is an example of SignedCardPayload. La carte adaptative encodée s’affiche sous le format [en-tête].[charge utile].[signature] en respectant les spécifications JWS.The encoded Adaptive Card appears in the form of [header].[payload].[signature] as per JWS specification.

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZW5kZXIiOiJzZXJ2aWNlLWFjY291bnRAY29udG9zby5jb20iLCJvcmlnaW5hdG9yIjoiNjVjNjgwZWYtMzZhNi00YTFiLWI4NGMtYTdiNWM2MTk4NzkyIiwicmVjaXBpZW50c1NlcmlhbGl6ZWQiOiJbXCJqb2huQGNvbnRvc28uY29tXCIsXCJqYW5lQGNvbnRvc28uY29tXCJdIiwiYWRhcHRpdmVDYXJkU2VyaWFsaXplZCI6IntcIiRzY2hlbWFcIjpcImh0dHA6Ly9hZGFwdGl2ZWNhcmRzLmlvL3NjaGVtYXMvYWRhcHRpdmUtY2FyZC5qc29uXCIsXCJ0eXBlXCI6XCJBZGFwdGl2ZUNhcmRcIixcInZlcnNpb25cIjpcIjEuMFwiLFwiYm9keVwiOlt7XCJzaXplXCI6XCJsYXJnZVwiLFwidGV4dFwiOlwiSGVsbG8gQWN0aW9uYWJsZSBtZXNzYWdlXCIsXCJ3cmFwXCI6dHJ1ZSxcInR5cGVcIjpcIlRleHRCbG9ja1wifV0sXCJhY3Rpb25zXCI6W3tcInR5cGVcIjpcIkFjdGlvbi5JbnZva2VBZGRJbkNvbW1hbmRcIixcInRpdGxlXCI6XCJPcGVuIEFjdGlvbmFibGUgTWVzc2FnZXMgRGVidWdnZXJcIixcImFkZEluSWRcIjpcIjNkMTQwOGY2LWFmYjMtNGJhZi1hYWNkLTU1Y2Q4NjdiYjBmYVwiLFwiZGVza3RvcENvbW1hbmRJZFwiOlwiYW1EZWJ1Z2dlck9wZW5QYW5lQnV0dG9uXCJ9XX0iLCJpYXQiOjE1NDUzNDgxNTN9.BP9mK33S1VZyjtWZd-lNTTjvueyeeoitygw9bl17TeQFTUDh9Kg5cB3fB7BeZYQs6IiWa1VGRdiiR4q9EkAB1qDsmIcJnw6aYwDUZ1KY4lNoYgQCH__FxEPHViGidNGtq1vAC6ODw0oIfaTUWTa5cF5MfiRBIhpQ530mbRNnA0QSrBYtyB54EDJxjBF1vNSKOeVHAl2d4gqcGxsytQA0PA7XMbrZ8B7fEU2uNjSiLQpoh6A1tevpla2C7W6h-Wekgsmjpw2YToAOX67VZ1TcS5oZAHmjv2RhqsfX5DlN-ZsTRErU4Hs5d92NY9ijJPDunSLyUFNCw7HLNPFqqPmZsw

L’en-tête dans le code JWS ci-dessus est :The header in above JWS is:

{
  "alg": "RS256",
  "typ": "JWT"
}

La charge utile dans le code JWS ci-dessus est :The payload in above JWS is:

{
  "sender": "service-account@contoso.com",
  "originator": "65c680ef-36a6-4a1b-b84c-a7b5c6198792",
  "recipientsSerialized": "[\"john@contoso.com\",\"jane@contoso.com\"]",
  "adaptiveCardSerialized": "{\"$schema\":\"http://adaptivecards.io/schemas/adaptive-card.json\",\"type\":\"AdaptiveCard\",\"version\":\"1.0\",\"body\":[{\"size\":\"large\",\"text\":\"Hello Actionable message\",\"wrap\":true,\"type\":\"TextBlock\"}],\"actions\":[{\"type\":\"Action.InvokeAddInCommand\",\"title\":\"Open Actionable Messages Debugger\",\"addInId\":\"3d1408f6-afb3-4baf-aacd-55cd867bb0fa\",\"desktopCommandId\":\"amDebuggerOpenPaneButton\"}]}",
  "iat": 1545348153
}
Claims requisRequired Claims
ClaimClaim DescriptionDescription
originator DOIT être défini sur l’ID fourni par Microsoft pendant l’intégration.MUST be set to the ID provided by Microsoft during onboarding.
iat Heure de signature de la charge utile.The time that the payload was signed.
sender Adresse e-mail utilisée pour envoyer ce message actionnable.The email address used to send this actionable message.
recipientsSerialized Liste stringified des destinataires du message électronique.The stringified list of the recipients of the email. Cela doit inclure tous les destinataires (À/CC) du message.This should include all the To/CC recipients of the email.
adaptiveCardSerialized Carte adaptative stringfied.The stringfied Adaptive Card.

Exemple de code générant une carte signée :Sample code generating signed card:

Vérification que les demandes proviennent de MicrosoftVerifying that requests come from Microsoft

Toutes les demandes d’action de Microsoft comportent un jeton du porteur dans l’en-tête Authorization HTTP. Il s’agit d’un jeton web JSON (JWT) signé par Microsoft qui inclut des revendications importantes, qu’il est vivement recommandé de faire vérifier par le service gérant la demande associée.All action requests from Microsoft have a bearer token in the HTTP Authorization header. This token is a JSON Web Token (JWT) token signed by Microsoft, and it includes important claims that we strongly recommend should be verified by the service handling the associated request.

Nom de la revendicationClaim name ValeurValue
aud URL de base du service cible, par exemple, https://api.contoso.com.The base URL of the target service, e.g. https://api.contoso.com
sub Identité de l’utilisateur ayant effectué l’action. Pour les messages appelant une action envoyés par courrier électronique, sub correspondrait à l’adresse e-mail de l’utilisateur. Pour les connecteurs, sub correspond à l’ID d’objet de l’utilisateur ayant effectué l’action.The identity of the user who took the action. For Actionable Messages sent over email, sub would be the email address of the user. For connectors, sub will be the objectID of the user who took the action.
sender Identité de l’expéditeur du message contenant l’action.The identity of sender of the message containing the action.

En règle générale, un service effectue les vérifications suivantes.Typically, a service will perform the following verifications.

  1. Le jeton est signé par Microsoft.The token is signed by Microsoft.
  2. La revendication aud correspond à l’URL de base du service.The aud claim corresponds to the service's base URL.

Grâce à toutes les vérifications effectuées ci-dessus, le service peut nommer les réclamations sender et sub comme identité de l’émetteur et de l’utilisateur prenant l’action. Le service peut valider que les réclamations sender et sub correspondent à l’émetteur et à l’utilisateur comme prévu.With all the above verifications done, the service can trust the sender and sub claims to be the identity of the sender and the user taking the action. The service can validate that the sender and sub claims match the sender and user it is expecting.

Reportez-vous aux exemples de code Microsoft fournis ci-dessous, qui montrent comment effectuer ces validations sur le jeton JWT.Please refer to the Microsoft code samples provided below, which show how to do these validations on the JWT token.

En-tête Action-AuthorizationAction-Authorization header

L’utilisation de l’en-tête Authorization par les messages actionnables peut interférer avec le mécanisme d’authentification/autorisation existant pour le point de terminaison cible.The use of Authorization header by Actionable messages may interfere with existing authentication/authorization mechanism for the target endpoint. Dans ce cas, les développeurs peuvent définir l’Authorizationen-tête sur null ou sur une chaîne vide dans la propriété headers d’une action Action.Http.In this case, developers can set the Authorization header to null or an empty string in the headers property of an Action.Http action. Les messages actionnables enverront alors le même jeton du porteur via l’en-tête Action-Authorization au lieu d’utiliser l’en-tête Authorization.Actionable messages will then send the same bearer token via Action-Authorization header instead of using Authorization header.

Conseil

Le service Azure Logic App renvoie HTTP 401 Unauthorized si l’en-tête Authorization contient le jeton du porteur défini par les messages actionnables.The Azure Logic App service returns HTTP 401 Unauthorized if the Authorization header contains the bearer token set by actionable messages.

Exemple d’en-tête Action.Http avec Action-AuthorizationExample Action.Http with Action-Authorization header

{
  "type": "Action.Http",
  "title": "Say hello",
  "method": "POST",
  "url": "https://api.contoso.com/sayhello",
  "body": "{{nameInput.value}}",
  "headers": [
    { "name": "Authorization", "value": "" }
  ]
}

Vérification de l’identité de l’utilisateurVerifying the identity of the user

Le jeton du porteur inclus avec toutes les demandes inclut l’identité Azure AD de l’utilisateur d’Office 365 qui a entreprise l’action.The bearer token included with all requests includes the Azure AD identity of the Office 365 user who took the action. Si nécessaire, vous pouvez inclure votre propre jeton, propre à votre service, dans les URL de vos actions HTTP pour représenter l’identité de l’utilisateur dans votre système.If necessary, you can include your own token, specific to your service, in the URLs of your HTTP actions to represent the identity of the user in your system. Microsoft n’impose pas la façon dont les jetons limités doivent être conçus ou utilisés par le service.Microsoft does not prescribe how the limited-access tokens should be designed or used by the service. Ce jeton est opaque pour Microsoft, et est simplement renvoyé au service.This token is opaque to Microsoft, and is simply echoed back to the service.

Les jetons spécifiques au service peuvent permettre de corréler les URL de service avec des utilisateurs et des messages spécifiques.Service-specific tokens can be used to correlate service URLs with specific messages and users. Si vous utilisez votre propre jeton spécifique au service, Microsoft recommande de l’inclure dans le cadre de l’URL cible d’action ou dans le corps de la demande renvoyée au service.Microsoft recommends that if you use your own service-specific token, youinclude it as part of the action target URL, or in the body of the request coming back to the service. Par exemple :For example:

https://contoso.com/approve?requestId=abc&serviceToken=a1b2c3d4e5...

Les jetons spécifiques au service agissent en tant qu’ID de corrélation (par exemple, un jeton haché utilisant l’ID utilisateur, l’ID de demande et salt).Service-specific tokens act as correlation IDs (for e.g. a hashed token using the userID, requestID, and salt). Cela permet au fournisseur de services d’effectuer le suivi des URL d’action qu’il génère et envoie, et de les mettre en correspondance avec les demandes d’action entrantes.This allows the service provider to keep track of the action URLs it generates and sends out and match it with action requests coming in. En plus de la corrélation, le fournisseur de services peut utiliser le jeton spécifique au service pour se protéger contre les attaques de relecture.In addition to correlation, the service provider may use the service-specific token to protect itself from replay attacks. Par exemple, le fournisseur de services peut choisir de refuser la demande, si l’action a déjà été effectuée précédemment avec le même jeton.For example, the service provider may choose to reject the request, if the action was already performed previously with the same token.