Requisitos de segurança para mensagens acionáveis no Office 365

Artigo
04/27/2024

Importante

A integração de novos provedores de Mensagens Acionáveis com um escopo Global está temporariamente pausada até 30 de junho de 2024 devido a atualizações de serviço. Os provedores de escopo global existentes e a integração de provedores de escopo de organização e teste não são afetados. Para obter mais detalhes, confira Perguntas frequentes para Mensagens Acionáveis.

Proteger emails acionáveis é simples e fácil. Há duas fases na experiência de ponta a ponta que impõem requisitos de segurança no seu serviço ao oferecer suporte a mensagens acionáveis com o Office 365. As fases e seus requisitos correspondentes são os seguintes.

Fase de envio: Os pré-requisitos para que seu serviço envie mensagens acionáveis são os seguintes:
- Se você estiver usando email acionável, precisará habilitar verificação de remetente. Observe que isso não se aplica às mensagens do conector.
- Seu serviço deve ser registrado na Microsoft.
- A URL de Ação deve oferecer suporte a HTTPS.
Fase de processamento de ação: Ao processar uma ação, seu serviço deve:
- Verificar o token de portador (um token Web JSON) incluído no cabeçalho da solicitação HTTP POST. A verificação também pode ser feita utilizando as bibliotecas de amostra fornecidas pela Microsoft.
- Incluir um token de finalidade limitado a partir de seu serviço como parte da URL de destino, que pode ser usado pelo seu serviço para correlacionar a URL de serviço com o usuário e a solicitação pretendidos. Isso é opcional, mas altamente recomendado.

Verificação de remetente

O Office 365 requer a verificação de remetente para habilitar as mensagens acionáveis por email. Os emails de mensagem acionáveis também devem se originar de servidores que implementam DKIM (DomainKeys Identified Mail) e SPF (Sender Policy Framework) ou você deve implementar cartões assinados.

Enquanto o DKIM e o SPF são suficientes em alguns cenários, essa solução não funciona em algumas situações em que os emails são enviados por um provedor externo, o que pode fazer com que os destinatários não experimentem a mensagem acionável aprimorada. Por esse motivo, recomendamos sempre implementar cartões assinados que funcionem em todos os casos e sejam essencialmente mais seguros porque não se baseiam em registros DNS.

Implementar o DKIM e o SPF

O DKIM e o SPF são maneiras padrão do setor para comprovar a identidade do remetente ao enviar emails via SMTP. Muitas empresas já implementam esses padrões para proteger os emails que estão enviando. Para saber mais sobre o SPF/DKIM e como implementá-los, confira:

Cargas de cartões assinados

As mensagens acionáveis enviadas por email são compatíveis com um método de verificação alternativo: assinar a carga de cartão com a uma chave RSA ou certificado X509. Esse método é necessário nos seguintes cenários:

Falha de SPF/DKIM causada por configuração de remetente ou conjunto de destinatário de locatário de serviços de segurança personalizado na frente de serviços do Office 365.
O cenário de mensagens acionáveis exige o envio para várias contas de email.

Para usar cartões assinados, você deve registrar sua chave pública no painel do desenvolvedor de email e usar a chave privada correspondente para assinar o cartão.

SignedCard

Os cartões assinados de mensagens acionáveis estão disponíveis ao enviar por email. Use este formato para incluir um cartão assinado no corpo HTML do email. Essa carga é serializada no formato Microdata acrescentado no final do corpo HTML.

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

Observação: Parceiros que preferem usar a entidade MessageCard herdada podem criar uma entidade SignedMessageCard no lugar de uma SignedAdaptiveCard.

SignedCardPayload

SignedCardPayload é uma cadeia de caracteres codificada por JSON Web assinatura (JWS) padrão. RFC7515 descreve JWS, e RFC7519 descreve JSON Token Web (JWT). Receber solicitação não é necessária JWT, JWT bibliotecas podem ser usadas para criar a assinatura JWS.

Observação: O termo "JWT" pode ser intercambiáveis prática. No entanto, Preferimos o termo "JWS" aqui.

Aqui está um exemplo de SignedCardPayload. O cartão adaptável codificado aparece na forma [cabeçalho]. [carga].[assinatura] de acordo com a especificação JWS.

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZW5kZXIiOiJzZXJ2aWNlLWFjY291bnRAY29udG9zby5jb20iLCJvcmlnaW5hdG9yIjoiNjVjNjgwZWYtMzZhNi00YTFiLWI4NGMtYTdiNWM2MTk4NzkyIiwicmVjaXBpZW50c1NlcmlhbGl6ZWQiOiJbXCJqb2huQGNvbnRvc28uY29tXCIsXCJqYW5lQGNvbnRvc28uY29tXCJdIiwiYWRhcHRpdmVDYXJkU2VyaWFsaXplZCI6IntcIiRzY2hlbWFcIjpcImh0dHA6Ly9hZGFwdGl2ZWNhcmRzLmlvL3NjaGVtYXMvYWRhcHRpdmUtY2FyZC5qc29uXCIsXCJ0eXBlXCI6XCJBZGFwdGl2ZUNhcmRcIixcInZlcnNpb25cIjpcIjEuMFwiLFwiYm9keVwiOlt7XCJzaXplXCI6XCJsYXJnZVwiLFwidGV4dFwiOlwiSGVsbG8gQWN0aW9uYWJsZSBtZXNzYWdlXCIsXCJ3cmFwXCI6dHJ1ZSxcInR5cGVcIjpcIlRleHRCbG9ja1wifV0sXCJhY3Rpb25zXCI6W3tcInR5cGVcIjpcIkFjdGlvbi5JbnZva2VBZGRJbkNvbW1hbmRcIixcInRpdGxlXCI6XCJPcGVuIEFjdGlvbmFibGUgTWVzc2FnZXMgRGVidWdnZXJcIixcImFkZEluSWRcIjpcIjNkMTQwOGY2LWFmYjMtNGJhZi1hYWNkLTU1Y2Q4NjdiYjBmYVwiLFwiZGVza3RvcENvbW1hbmRJZFwiOlwiYW1EZWJ1Z2dlck9wZW5QYW5lQnV0dG9uXCJ9XX0iLCJpYXQiOjE1NDUzNDgxNTN9.BP9mK33S1VZyjtWZd-lNTTjvueyeeoitygw9bl17TeQFTUDh9Kg5cB3fB7BeZYQs6IiWa1VGRdiiR4q9EkAB1qDsmIcJnw6aYwDUZ1KY4lNoYgQCH__FxEPHViGidNGtq1vAC6ODw0oIfaTUWTa5cF5MfiRBIhpQ530mbRNnA0QSrBYtyB54EDJxjBF1vNSKOeVHAl2d4gqcGxsytQA0PA7XMbrZ8B7fEU2uNjSiLQpoh6A1tevpla2C7W6h-Wekgsmjpw2YToAOX67VZ1TcS5oZAHmjv2RhqsfX5DlN-ZsTRErU4Hs5d92NY9ijJPDunSLyUFNCw7HLNPFqqPmZsw

O cabeçalho acima JWS é:

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

A carga acima JWS é:

{
  "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
}

Reclamações necessárias

Solicitação	Descrição
`originator`	DEVE ser definido como a ID fornecido pela Microsoft durante a integração.
`iat`	A hora em que a carga foi assinada.
`sender`	O endereço de email usado para enviar esta mensagem acionável.
`recipientsSerialized`	Lista stringified de destinatários do email. Este deve incluir todos os destinatários Para/CC do email.
`adaptiveCardSerialized`	O Cartão Adaptável stringified.

Exemplo de código gerando cartão assinado:

Verificar se as solicitações vêm da Microsoft

Todas as solicitações de ação da Microsoft tem um token de portador no cabeçalho HTTP Authorization. Esse token é um Token Web JSON (JWT) assinado pela Microsoft e inclui declarações importantes que recomendamos fortemente que sejam verificadas pelo serviço que está lidando com a solicitação associada.

Nome da declaração	Valor
`aud`	A URL de base do serviço de destino, por exemplo `https://api.contoso.com`
`iss`	O emissor do token. Isto deve ser `https://substrate.office.com/sts/`
`sub`	A identidade do usuário que realizou a ação. Para as mensagens acionáveis enviadas por email, `sub` seria o endereço de email do usuário. Para os conectores, `sub` será a objectID do usuário que realizou a ação.
`sender`	A identidade do remetente da mensagem contendo a ação. Este valor só está presente se a mensagem acionável foi enviada por email. Mensagens acionáveis enviadas por meio de conectores não incluem esta solicitação em seu token de portador.

Normalmente, um serviço executará as verificações a seguir.

O token é assinado pela Microsoft. OpenID metadata is located at https://substrate.office.com/sts/common/.well-known/openid-configuration, which includes information regarding signing keys.
A declaração aud corresponde à URL de base do serviço.

Com todas as verificações acima concluídas, o serviço pode confiar nas declarações sender e sub como sendo a identidade do remetente e do usuário executando a ação. O serviço pode validar que as sender declarações e sub correspondem ao remetente e ao usuário que ele está esperando.

Confira os exemplos de código da Microsoft fornecidos abaixo, que mostram como fazer essas validações no token JWT.

Cabeçalho Action-Authorization

O uso do cabeçalho Authorization por mensagens acionáveis pode interferir no mecanismo de autenticação/autorização existente para o ponto de extremidade de destino. Nesse caso, os desenvolvedores podem definir o Authorization cabeçalho como uma cadeia de caracteres vazia na headers propriedade de uma Action.Http ação. As mensagens acionáveis enviarão, então, o mesmo token de portador por meio do cabeçalho Action-Authorization em vez de usar o cabeçalho Authorization.

Dica

O serviço do Aplicativo Lógico do Azure retorna HTTP 401 Unauthorized se o cabeçalho Authorization contiver o token de portador configurado por mensagens acionáveis.

Exemplo Action.Http com cabeçalho Action-Authorization

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

Verificar a identidade do usuário

O token de portador que acompanha todas as solicitações inclui a identidade do Azure Active Directory do usuário do Office 365 que executou a ação. Se necessário, você pode incluir um token específico para o serviço nas URLs das ações HTTP para representar a identidade do usuário no sistema. A Microsoft não estabelece como os tokens de acesso limitado devem ser desenvolvidos ou usados pelo serviço. Esse token é opaco para a Microsoft e é simplesmente reproduzido no serviço.

Os tokens específicos de serviços podem ser usados para correlacionar as URLs de serviço com mensagens e usuários específicos. A Microsoft recomenda que, caso você use seu token específico do serviço, o inclua como parte da URL de destino da ação ou no corpo da solicitação que retorna ao serviço. Por exemplo:

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

Os tokens específicos de serviços agem como IDs de correlação (por exemplo, um token no formato hash usando userID, requestID e salt). Isso permite que o provedor de serviços controle as URLs de ação que ele gera, envia e corresponde com as novas solicitações de ação. Além da correlação, o provedor de serviços pode usar o token específico de serviço para se proteger contra ataques de repetição. Por exemplo, o provedor de serviços pode optar por rejeitar a solicitação, se a ação já tiver sido executada anteriormente com o mesmo token.

Share via