Sicherheitsanforderungen für Nachrichten mit Aktionen in Office 365

  • Artikel

Das Schützen von E-Mails mit Aktionen gestaltet sich einfach und problemlos. Es gibt zwei Phasen innerhalb der End-to-End-Erfahrung, für die Sicherheitsanforderungen für Ihren Dienst vorgegeben sind, wenn Nachrichten mit Aktionen in Office 365 unterstützt werden. Die Phasen und die entsprechenden Anforderungen lauten wie folgt:

  1. Sendephase: Es gelten folgende Voraussetzungen für Ihren Dienst, um Nachrichten mit Aktionen zu senden:
    • Wenn Sie E-Mails mit Aktionen verwenden, müssen Sie die Absenderüberprüfung aktivieren. Beachten Sie, dass dies nicht für Connectornachrichten gilt.
    • Der Dienst muss bei Microsoft registriert sein.
    • Die Aktions-URL muss HTTPS unterstützen.
  2. Phase der Aktionsverarbeitung: Wenn Sie eine Aktion verarbeiten, sollte Ihr Dienst Folgendes:
    • Den Bearertoken (ein JSON-Web-Token) im Header der HTTP-POST-Anforderung prüfen. Überprüfung kann auch durch die Nutzung von Beispielbibliotheken erfolgen, die von Microsoft bereitgestellt werden.
    • Token für begrenzte Zwecke von Ihrem Dienst als Teil der Ziel-URL verwenden, welche von Ihrem Dienst zum Korrelieren der Dienst-URL mit der beabsichtigten Anforderung und dem Benutzer verwendet werden kann. Dies ist optional, wird jedoch dringend empfohlen.

Absenderüberprüfung

Office 365 erfordert die Absenderüberprüfung, um Aktionen erfordernde Nachrichten per E-Mail zu aktivieren. Ihre Aktionen erfordernden E-Mails müssen entweder von Servern stammen, die DomainKeys Identified Mail (DKIM) und Sender Policy Framework (SPF) implementieren, oder Sie müssen signierte Karten implementieren.

Während DKIM und SPF für einige Szenarien ausreichend sind, funktioniert diese Lösung in einigen Fällen nicht, in denen E-Mails über einen externen Anbieter gesendet werden. In diesen Fällen erhalten Empfänger die erweiterte Aktionen erfordernde Nachricht möglicherweise nicht. Aus diesem Grund empfehlen wir immer die Implementierung signierter Karten, die in allen Fällen funktionieren und grundsätzlich sicherer sind, da sie nicht auf DNS-Einträgen beruhen.

Implementieren von DKIM und SPF

DKIM und SPF sind Branchenstandard für die Überprüfung der Identität des Absenders beim Senden von E-Mails über SMTP. Viele Unternehmen implementieren bereits diese Standards, um die E-Mails zu sichern, die sie senden. Weitere Informationen zu SPF/DKIM und deren Implementierung finden Sie unter:

Signierte Kartennutzlasten

Für Aktionen erfordernde Nachrichten, die per E-Mail gesendet werden, gibt es eine alternative Überprüfungsmethode: Signieren der Kartennutzlast mit einem RSA-Schlüssel oder X509-Zertifikat. Diese Methode ist in den folgenden Szenarien erforderlich:

  • SPF-/DKIM-Fehler verursacht durch Absendereinrichtung, oder der Empfängermandant hat benutzerdefinierte Sicherheitsdienste vor Office 365-Diensten festgelegt.
  • Ihr Szenario für Aktionen erfordernde Nachrichten erfordert das Senden von mehreren E-Mail-Konten.

Um signierte Karten zu verwenden, müssen Sie Ihren öffentlichen Schlüssel beim E-Mail-Entwicklerdashboard registrieren und die Karte mit dem entsprechenden privaten Schlüssel signieren.

SignedCard

Signierte Aktionen erfordernde Nachrichtenkarten sind verfügbar, wenn Sie E-Mail senden. Verwenden Sie das folgende Format, um eine signierte Karte in den HTML-Textkörper einer E-Mail einzuschließen. Diese Nutzlast ist im Mikrodatenformat verfügbar, das am Ende des HTML-Textkörpers angefügt ist.

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

Hinweis: Partner, die lieber die ältere MessageCard-Entität verwenden, können anstelle einer SignedAdaptiveCard eine SignedMessageCard-Entität erstellen.

SignedCardPayload

SignedCardPayload ist eine vom JWS-Standard (JSON Web Signatur) codierte Zeichenfolge. RFC7515beschreibt JWS, und RFC7519 beschreibt JSON Web Token (JWT). Wenn kein Anspruch in JWT erforderlich ist, können JWT-Bibliotheken zum Erstellen einer JWS-Signatur verwendet werden.

Hinweis: Der Begriff „JWT“ ist synonym mit „JWS“. Wir bevorzugen hier aber den Begriff „JWS“.

Nachfolgend finden Sie ein Beispiel für SignedCardPayload. Die codierte adaptive Karte wird gemäß JWS-Spezifikation im Format [header].[payload].[signature] angezeigt.

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZW5kZXIiOiJzZXJ2aWNlLWFjY291bnRAY29udG9zby5jb20iLCJvcmlnaW5hdG9yIjoiNjVjNjgwZWYtMzZhNi00YTFiLWI4NGMtYTdiNWM2MTk4NzkyIiwicmVjaXBpZW50c1NlcmlhbGl6ZWQiOiJbXCJqb2huQGNvbnRvc28uY29tXCIsXCJqYW5lQGNvbnRvc28uY29tXCJdIiwiYWRhcHRpdmVDYXJkU2VyaWFsaXplZCI6IntcIiRzY2hlbWFcIjpcImh0dHA6Ly9hZGFwdGl2ZWNhcmRzLmlvL3NjaGVtYXMvYWRhcHRpdmUtY2FyZC5qc29uXCIsXCJ0eXBlXCI6XCJBZGFwdGl2ZUNhcmRcIixcInZlcnNpb25cIjpcIjEuMFwiLFwiYm9keVwiOlt7XCJzaXplXCI6XCJsYXJnZVwiLFwidGV4dFwiOlwiSGVsbG8gQWN0aW9uYWJsZSBtZXNzYWdlXCIsXCJ3cmFwXCI6dHJ1ZSxcInR5cGVcIjpcIlRleHRCbG9ja1wifV0sXCJhY3Rpb25zXCI6W3tcInR5cGVcIjpcIkFjdGlvbi5JbnZva2VBZGRJbkNvbW1hbmRcIixcInRpdGxlXCI6XCJPcGVuIEFjdGlvbmFibGUgTWVzc2FnZXMgRGVidWdnZXJcIixcImFkZEluSWRcIjpcIjNkMTQwOGY2LWFmYjMtNGJhZi1hYWNkLTU1Y2Q4NjdiYjBmYVwiLFwiZGVza3RvcENvbW1hbmRJZFwiOlwiYW1EZWJ1Z2dlck9wZW5QYW5lQnV0dG9uXCJ9XX0iLCJpYXQiOjE1NDUzNDgxNTN9.BP9mK33S1VZyjtWZd-lNTTjvueyeeoitygw9bl17TeQFTUDh9Kg5cB3fB7BeZYQs6IiWa1VGRdiiR4q9EkAB1qDsmIcJnw6aYwDUZ1KY4lNoYgQCH__FxEPHViGidNGtq1vAC6ODw0oIfaTUWTa5cF5MfiRBIhpQ530mbRNnA0QSrBYtyB54EDJxjBF1vNSKOeVHAl2d4gqcGxsytQA0PA7XMbrZ8B7fEU2uNjSiLQpoh6A1tevpla2C7W6h-Wekgsmjpw2YToAOX67VZ1TcS5oZAHmjv2RhqsfX5DlN-ZsTRErU4Hs5d92NY9ijJPDunSLyUFNCw7HLNPFqqPmZsw

Die Kopfzeile in JWS ist dabei:

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

Die Nutzlast in JWS ist dabei:

{
  "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
}
Erforderliche Ansprüche
Anspruch Beschreibung
originator MUSS auf die von Microsoft beim Onboarding bereitgestellte ID festgelegt werden.
iat Die Zeit, zu der die Nutzlast signiert wurde.
sender Die E-Mail-Adresse, mit der diese Aktion erfordernde Nachricht gesendet wurde.
recipientsSerialized Die als Zeichenfolge dargestellte Liste der Empfänger der E-Mail. Dazu zählen alle Empfänger der E-Mail in den Zeilen „An“ und „CC“.
adaptiveCardSerialized Die als Zeichenfolge dargestellte adaptive Karte.

Beispielcode zum Generieren der signierten Karte:

Überprüfen, ob Anfragen von Microsoft stammen

Alle Aktionsanforderungen von Microsoft verfügen über ein Bearertoken im HTTP-Authorization-Header. Dieses Token ist ein von Microsoft signiertes JSON-Web-Token (JWT), das wichtige Ansprüche enthält, die dringend von dem Dienst zu überprüfen sind, der die entsprechende Anforderung verarbeitet.

Anspruchsname Wert
aud Die Basis-URL des Zieldiensts, z. B.https://api.contoso.com
iss Der Aussteller des Tokens. Dies sollte https://substrate.office.com/sts/ sein.
sub Die Identität des Benutzers, der die Aktion ausgeführt hat. Für per E-Mail gesendete Nachrichten mit Aktionen wäre sub die E-Mail-Adresse des Benutzers. Für Connectors wäre sub objectID des Benutzers, der die Aktion ausgeführt hat.
sender Die Identität der Absender der Nachricht mit der Aktion. Dieser Wert ist nur vorhanden, wenn die eine Aktion erfordernde Nachricht über E-Mail gesendet wurde. Aktionen erfordernde Nachrichten, die über Connectors gesendet wurden, enthalten diesen Anspruch in ihren Bearertoken nicht.

In der Regel führt ein Dienst die folgenden Überprüfungen durch.

  1. Das Token ist von Microsoft signiert. OpenID-Metadaten befinden sich unter https://substrate.office.com/sts/common/.well-known/openid-configuration, und schließen Informationen bezüglich Signierschlüsseln ein.
  2. Der aud-Anspruch entspricht der Basis-URL des Diensts.

Für alle oben genannten Überprüfungen kann der Dienst den sender- und sub-Anforderungen vertrauen, dass sie die Identität des Absenders und des Benutzers sind, die die Aktionen ausführen. Der Dienst kann überprüfen, ob die sender Ansprüche und sub mit dem erwarteten Absender und Benutzer übereinstimmen.

Informationen zu den Überprüfungen des JWT-Tokens finden Sie in den Microsoft-Codebeispielen weiter unten.

Action-Authorization-Header

Die Verwendung des Authorization-Headers durch Aktion erfordernde Nachrichten kann zu Konflikten mit vorhandenen Authentifizierungs-/Autorisierungsmechanismen für den Zielendpunkt führen. In diesem Fall können Entwickler den Header in headers der Authorization -Eigenschaft einer Action.Http Aktion auf eine leere Zeichenfolge festlegen. Aktion erfordernde Nachrichten senden dasselbe Bearertoken über den Action-Authorization-Header, statt den Authorization-Header dazu zu verwenden.

Tipp

Der Azure Logic App-Dienst gibt HTTP 401 Unauthorized zurück, wenn der Authorization-Header das von Aktion erfordernden Nachrichten festgelegte Bearertoken enthält.

Beispiel für Action.Http mit Action-Authorization-Header

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

Überprüfen der Identität des Benutzers

Das in allen Anforderungen enthaltene Bearertoken enthält die Azure AD-Identität des Office 365-Benutzers, der die Aktion ausgeführt hat. Gegebenenfalls können Sie Ihr eigenes Token, das spezifisch für Ihren Dienst ist, in die URLs Ihrer HTTP-Aktionen einschließen, um die Identität des Benutzers in Ihrem System darzustellen. Microsoft schreibt nicht vor, wie Token für begrenzte Zwecke zu entwerfen oder vom Dienst zu verwenden sind. Dieses Token ist für Microsoft nicht transparent und wird einfach an den Dienst zurückgesendet.

Dienstspezifische Token können zum Korrelieren von Dienst-URLs mit bestimmten Nachrichten und Benutzern verwendet werden. Microsoft empfiehlt bei Verwendung Ihres eigenen dienstspezifischen Tokens dieses als Teil der Aktionsziel-URL oder im Text der Anforderung einzufügen, die zum Dienst zurückkommt. Beispiel:

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

Dienstspezifische Token dienen als Korrelations-IDs (z. B. für Hash-Token unter Verwendung von userID, requestID und salt). Dies ermöglicht dem Dienstanbieter das Nachverfolgen der Aktions-URLs, die er generiert und versendet, und den Abgleich dieser mit eingehenden Aktionsanforderungen. Neben der Korrelation kann der Dienstanbieter das dienstspezifische Token zum Schutz vor Replay-Angriffen verwenden. Beispielsweise kann der Dienstanbieter die Anforderung ablehnen, wenn die Aktion bereits mit demselben Token durchgeführt wurde.