Configurar notificações de alteração que incluem dados de recursos (notificações avançadas)

O Microsoft Graph permite que as aplicações subscrevam e recebam notificações de alterações aos recursos em que estão interessadas. Embora possa subscrever notificações de alteração básicas, os recursos, como a mensagem de chat do Microsoft Teams e os recursos de presença, por exemplo, suportam notificações avançadas.

As notificações avançadas incluem os dados de recursos que foram alterados, permitindo que a sua aplicação execute lógica de negócio sem ter de fazer uma chamada à API separada para obter o recurso alterado. Este artigo orienta-o ao longo do processo de configuração de notificações avançadas na sua aplicação.

Recursos com suporte

Estão disponíveis notificações avançadas para os seguintes recursos.

Observação

As notificações avançadas para subscrições para pontos finais marcadas com um asterisco (*) só estão disponíveis no /beta ponto final.

Recurso	Caminhos de recursos suportados	Limitações
Evento do Outlook	Alterações a todos os eventos na caixa de correio de um utilizador: /users/{id}/events	$select É necessário devolver apenas um subconjunto de propriedades na notificação avançada. Para obter mais informações, veja Alterar notificações para recursos do Outlook.
Mensagem do Outlook	Alterações a todas as mensagens na caixa de correio de um utilizador: /users/{id}/messages Alterações às mensagens na caixa de entrada de um utilizador: /users/{id}/mailFolders/{id}/messages	$select É necessário devolver apenas um subconjunto de propriedades na notificação avançada. Para obter mais informações, veja Alterar notificações para recursos do Outlook.
Contato pessoal do Outlook	Alterações a todos os contactos pessoais na caixa de correio de um utilizador: /users/{id}/contacts Alterações a todos os contactos pessoais no contacto de um utilizadorPasta: /users/{id}/contactFolders/{id}/contacts	$select É necessário devolver apenas um subconjunto de propriedades na notificação avançada. Para obter mais informações, veja Alterar notificações para recursos do Outlook.
Chamada do TeamsRegisto	Todas as gravações numa organização: communications/onlineMeetings/getAllRecordings Todas as gravações para uma reunião específica: communications/onlineMeetings/{onlineMeetingId}/recordings Uma gravação de chamada que fica disponível numa reunião organizada por um utilizador específico: users/{id}/onlineMeetings/getAllRecordings Uma gravação de chamada que fica disponível numa reunião onde está instalada uma determinada aplicação do Teams: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings *	Cotas máximas de assinaturas: Combinação por aplicação e reunião online: 1 Combinação por aplicação e utilizador: 1 Por utilizador (para subscrições que monitorizam as gravações em todos os OnlineMeetings organizados pelo utilizador): 10 subscrições. Por organização: 10 000 subscrições totais.
Chamada do TeamsTranscript	Todas as transcrições numa organização: communications/onlineMeetings/getAllTranscripts Todas as transcrições de uma reunião específica: communications/onlineMeetings/{onlineMeetingId}/transcripts Uma transcrição de chamada que fica disponível numa reunião organizada por um utilizador específico: users/{id}/onlineMeetings/getAllTranscripts Uma transcrição de chamadas que fica disponível numa reunião onde está instalada uma determinada aplicação do Teams: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTrancripts *	Cotas máximas de assinaturas: Combinação por aplicação e reunião online: 1 Combinação por aplicação e utilizador: 1 Por utilizador (para subscrições que monitorizam transcrições em todos os OnlineMeetings organizados pelo utilizador): 10 subscrições. Por organização: 10 000 subscrições totais.
Canal do Teams	Alterações aos canais em todas as equipas: /teams/getAllChannels Alterações ao canal numa equipa específica: /teams/{id}/channels	-
Chat do Teams	Alterações a qualquer conversa no inquilino: /chats Alterações a um chat específico: /chats/{id}	-
Teams chatMessage	Alterações às mensagens de chat em todos os canais em todas as equipas: /teams/getAllMessages Alterações às mensagens de chat num canal específico: /teams/{id}/channels/{id}/messages Alterações às mensagens de chat em todas as conversas: /chats/getAllMessages Alterações às mensagens de chat num chat específico: /chats/{id}/messages As alterações às mensagens de chat em todas as conversas dos utilizadores específicos fazem parte: /users/{id}/chats/getAllMessages	Não suporta a utilização $select para devolver apenas as propriedades selecionadas. A notificação avançada consiste em todas as propriedades da instância alterada.
conversationMember do Teams	Alterações à associação numa equipa específica: /teams/{id}/members Alterações à associação num chat específico: /chats/{id}/members	-
Teams onlineMeeting *	Alterações a uma reunião online: /communications/onlineMeetings(joinWebUrl='{encodedJoinWebUrl}')/meetingCallEvents *	Não suporta a utilização $select para devolver apenas as propriedades selecionadas. A notificação avançada consiste em todas as propriedades da instância alterada. Uma subscrição permitida por aplicação por reunião online. Para obter mais informações, consulte Obter notificações de alteração para atualizações de eventos de chamada de reunião do Microsoft Teams.
Teams presença	Alterações à presença de um único utilizador: /communications/presences/{id} Alterações à presença de vários utilizadores: /communications/presences?$filter=id in ({id},{id}...)	A subscrição para a presença de vários utilizadores está limitada a 650 utilizadores distintos. Não suporta a utilização $select para devolver apenas as propriedades selecionadas. A notificação avançada consiste em todas as propriedades da instância alterada. Uma subscrição permitida por aplicação por utilizador delegado. Para obter mais informações, consulte Obter notificações de alteração para atualizações de presença no Microsoft Teams.
Equipe do Teams	Alterações a qualquer equipa no inquilino: /teams Alterações a uma equipa específica: /teams/{id}	-

Dados de recursos na carga de notificação

As notificações avançadas incluem os seguintes dados de recursos no payload:

• ID e tipo de instância de recurso alterado, retornados na propriedade resourceData.
• Todos os valores de propriedade da instância de recurso, criptografados conforme especificado na assinatura, retornados na propriedade encryptedContent.
• Or, dependendo do recurso, propriedades específicas retornadas na propriedade resourceData. Para obter somente propriedades específicas, especifique-as como parte da URL do recurso na assinatura, usando um parâmetro $select.

Criar uma assinatura

As notificações avançadas são configuradas da mesma forma que as notificações de alteração básicas, exceto que tem de especificar as seguintes propriedades:

• includeResourceData que deve ser definido como true para solicitar explicitamente os dados de recursos.
• encryptionCertificate , que contém apenas a chave pública que o Microsoft Graph utiliza para encriptar os dados de recursos devolvidos à sua aplicação. Por motivos de segurança, o Microsoft Graph encripta os dados de recursos devolvidos numa notificação avançada. Tem de fornecer uma chave de encriptação pública como parte da criação da subscrição. Para obter mais informações sobre como criar e gerir chaves de encriptação, veja Desencriptar dados de recursos a partir de notificações de alteração.
• encryptionCertificateId é o seu próprio identificador para o certificado. Use esse ID para corresponder a cada notificação de alteração cujo certificado foi utilizado para descriptografia.

Também tem de validar ambos os pontos finais, conforme descrito em Validação do ponto final de notificação. Se optar por utilizar o mesmo URL para ambos os pontos finais, receberá e deverá responder a dois pedidos de validação.

Exemplo de solicitação de assinatura

O exemplo a seguir assina as mensagens de canal que estão sendo criadas ou atualizadas no Microsoft Teams.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{id}/channels/{id}/messages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Resposta de assinatura

HTTP/1.1 201 Created
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{id}/channels/{id}/messages",
  "includeResourceData": true,
  "encryptionCertificateId": "{custom ID}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secret client state}"
}

Notificações do ciclo de vida da assinatura

Certos eventos podem interferir no fluxo de notificação de alterações em uma assinatura existente. As notificações sobre o ciclo de vida da assinatura informam as ações a serem tomadas para manter um fluxo ininterrupto. Ao contrário de uma notificação de alteração de recursos que informa uma alteração a uma instância de recurso, uma notificação de ciclo de vida é sobre a própria subscrição e o estado atual no ciclo de vida.

Para obter mais informações sobre como receber e responder a notificações de ciclo de vida, veja Reduzir subscrições em falta e alterar notificações.

Validando a autenticidade das notificações

Antes de executar a lógica de negócio com base nos dados de recursos incluídos nas notificações de alteração, primeiro tem de verificar a autenticidade de cada notificação de alteração. Caso contrário, um terceiro pode falsificar a sua aplicação com notificações de alteração falsas e fazê-la executar a lógica de negócio incorretamente, o que pode levar a um incidente de segurança.

Para notificações de alteração básicas que não contêm dados de recursos, basta validá-las com base no valor clientState , conforme descrito em Processar a notificação de alteração. Esta validação é aceitável, uma vez que pode fazer chamadas fidedignas subsequentes do Microsoft Graph para obter acesso aos dados de recursos e, por conseguinte, o impacto de quaisquer tentativas de spoofing é limitado.

Para notificações avançadas, execute uma validação mais completa antes de processar os dados.

Nesta secção, vai explorar os seguintes conceitos de validação:

• Tokens de validação na notificação de alteração
• Como validar
• Exemplo de token JWT

Tokens de validação na notificação de alteração

Uma notificação de alteração com dados de recursos contém uma propriedade extra, validationTokens, que contém uma matriz de JSON Web Tokens (JWT) gerados pelo Microsoft Graph. O Microsoft Graph gera um único token para cada par de inquilinos e aplicações diferentes para os quais existe um item na matriz de valores . Tenha em atenção que as notificações de alteração podem conter uma combinação de itens para várias aplicações e inquilinos que subscreveram com o mesmo notificationUrl.

Observação

O Microsoft Graph não envia tokens de validação para notificações de alteração fornecidas através de Hubs de Eventos do Azure porque o serviço de subscrição não precisa de validar o notificationUrl para os Hubs de Eventos.

No exemplo a seguir, a notificação de alteração contém dois itens para o mesmo aplicativo e para dois locatários diferentes, portanto, o conjunto validationTokens contém dois tokens que precisam ser validados.

{
    "value": [
        {
            "subscriptionId": "76619225-ff6b-4489-96ca-4ef547e78b22",
            "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
            "changeType": "created",
            ...
        },
        {
            "subscriptionId": "5cfe2387-163c-4006-81bb-1b5e1e060afe",
            "tenantId": "bbbbcccc-1111-dddd-2222-eeee3333ffff",
            "changeType": "created",
            ...
        }
    ],
    "validationTokens": [
        "eyJ0eXAiOiJKV1QiLCJhb...",
        "cGlkYWNyIjoiMiIsImlkc..."
    ]
}

O objeto de notificação de alteração está na estrutura do tipo de recurso changeNotificationCollection.

Como validar

Utilize a Biblioteca de Autenticação da Microsoft (MSAL) para o ajudar a processar a validação de tokens ou uma biblioteca de terceiros para uma plataforma diferente.

Tenha em atenção os seguintes princípios:

• Certifique-se de sempre enviar um HTTP 202 Accepted código de status como parte da resposta à notificação de alteração.
• Responda antes de validar a notificação de alteração, mesmo que a validação falhe mais tarde. Ou seja, responda imediatamente ao receber a notificação de alteração, quer armazene notificações em filas para processamento posterior ou processe-as de imediato.
• A aceitação de uma notificação de alteração evita novas tentativas desnecessárias de entrega e também impede que possíveis atores invasores descubram se foram ou não aprovados na validação. Pode sempre optar por ignorar uma notificação de alteração inválida depois de a receber.

Especificamente, realize a validação em todos os tokens JWT na coleção validationTokens. Se algum token falhar, considere a notificação de alteração suspeita e investigue mais.

Use as etapas a seguir para validar tokens e aplicativos que geram tokens:

1. Confirme que o token não expirou.

2. Confirme que o plataforma de identidade da Microsoft emitiu o token e que o token não foi adulterado.

   • Obtenha as chaves de assinatura do ponto de extremidade de configuração comum: https://login.microsoftonline.com/common/.well-known/openid-configuration. A sua aplicação pode colocar esta configuração em cache durante algum tempo. A configuração é atualizada frequentemente à medida que as chaves de assinatura são rodadas diariamente.
   • Verifique a assinatura do token JWT usando essas chaves.

   Não aceite tokens emitidos por nenhuma outra autoridade.

3. Valide se o token foi emitido para o aplicativo que está inscrito para alterar as notificações.

   As etapas a seguir fazem parte da lógica de validação padrão nas bibliotecas de token JWT e podem ser tipicamente executadas como uma única chamada de função.

   • Valide a “audiência” no token que corresponde à ID do seu aplicativo.
   • Se você tiver mais de um aplicativo recebendo notificações de alterações, verifique a existencia de vários IDs.

4. Crítico: valide se o aplicativo que gerou o token representa o distribuidor de notificação de alteração do Microsoft Graph.

   • Verifique se a azp propriedade no token corresponde ao valor esperado de 0bf30f3b-4a52-48df-9a82-234910c4a086.
   • Este marcar garante que uma aplicação diferente que não seja o Microsoft Graph não enviou as notificações de alteração.

Exemplo de Token JWT

O exemplo seguinte mostra as propriedades incluídas no token JWT que são necessárias para validação.

{
  // aud is your app's id
  "aud": "925bff9f-f6e2-4a69-b858-f71ea2b9b6d0",
  "iss": "https://login.microsoftonline.com/9f4ebab6-520d-49c0-85cc-7b25c78d4a93/v2.0",
  "iat": 1624649764,
  "nbf": 1624649764,
  "exp": 1624736464,
  "aio": "E2ZgYGjnuFglnX7mtjJzwR5lYaWvAA==",
  // azp represents the notification publisher and must always be the same value of 0bf30f3b-4a52-48df-9a82-234910c4a086
  "azp": "0bf30f3b-4a52-48df-9a82-234910c4a086",
  "azpacr": "2",
  "oid": "1e7d79fa-7893-4d50-bdde-164260d9c5ba",
  "rh": "0.AX0AtrpOnw1SwEmFzHslx41KkzsP8wtSSt9ImoIjSRDEoIZ9AAA.",
  "sub": "1e7d79fa-7893-4d50-bdde-164260d9c5ba",
  "tid": "9f4ebab6-520d-49c0-85cc-7b25c78d4a93",
  "uti": "mIB4QKCeZE6hK71XUHJ3AA",
  "ver": "2.0"
}

Exemplo: verificação de tokens de validação

C#

// add Microsoft.IdentityModel.Protocols.OpenIdConnect and System.IdentityModel.Tokens.Jwt nuget packages to your project
public async Task<bool> ValidateToken(string token, string tenantId, IEnumerable<string> appIds)
{
    var configurationManager = new ConfigurationManager<OpenIdConnectConfiguration>(
        "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",
        new OpenIdConnectConfigurationRetriever());
    var openIdConfig = await configurationManager.GetConfigurationAsync();
    var handler = new JwtSecurityTokenHandler();
    try
    {
    handler.ValidateToken(token, new TokenValidationParameters
    {
        ValidateIssuer = true,
        ValidateAudience = true,
        ValidateIssuerSigningKey = true,
        ValidateLifetime = true,
        ValidIssuer = $"https://sts.windows.net/{tenantId}/",
        ValidAudiences = appIds,
        IssuerSigningKeys = openIdConfig.SigningKeys
    }, out _);
    return true;
    }
    catch (Exception ex)
    {
    Trace.TraceError($"{ex.Message}:{ex.StackTrace}");
    return false;
    }
}

Java

private boolean IsValidationTokenValid(String[] appIds, String tenantId, String serializedToken) {
    try {
        JwkKeyResolver jwksResolver = new JwkKeyResolver();
        Jws<Claims> token = Jwts.parserBuilder()
        .setSigningKeyResolver(jwksResolver)
        .build()
        .parseClaimsJws(serializedToken);
        Claims body = token.getBody();
        String audience = body.getAudience();
        boolean isAudienceValid = false;
        for(String appId : appIds) {
        isAudienceValid = isAudienceValid || appId.equals(audience);
        }
        boolean isTenantValid = body.getIssuer().endsWith(tenantId + "/");
        return isAudienceValid  && isTenantValid; //nbf,exp and signature are already validated by library
    } catch (Exception e) {
        LOGGER.error("could not validate token");
        LOGGER.error(e.getMessage());
        return false;
    }
}

Para que o exemplo de Java funcione, também tem de implementar o JwkKeyResolver.

package com.example.restservice;

import com.auth0.jwk.JwkProvider;
import com.auth0.jwk.UrlJwkProvider;
import com.auth0.jwk.Jwk;
import io.jsonwebtoken.Claims;
import io.jsonwebtoken.JwsHeader;
import io.jsonwebtoken.SigningKeyResolverAdapter;
import java.security.Key;
import java.net.URI;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class JwkKeyResolver extends SigningKeyResolverAdapter {
    private JwkProvider keyStore;
    private final Logger LOGGER = LoggerFactory.getLogger(this.getClass());
    public JwkKeyResolver() throws java.net.URISyntaxException, java.net.MalformedURLException {
        this.keyStore = new UrlJwkProvider((new URI("https://login.microsoftonline.com/common/discovery/keys").toURL()));
    }
    @Override
    public Key resolveSigningKey(JwsHeader jwsHeader, Claims claims) {
        try {
            String keyId = jwsHeader.getKeyId();
            Jwk pub = keyStore.get(keyId);
            return pub.getPublicKey();
        } catch (Exception e) {
            LOGGER.error(e.getMessage());
            return null;
        }
    }
}

JavaScript

import jwt from 'jsonwebtoken';
import jwksClient from 'jwks-rsa';

const client = jwksClient({
  jwksUri: 'https://login.microsoftonline.com/common/discovery/v2.0/keys'
});

export function getKey(header, callback) {
  client.getSigningKey(header.kid, (err, key) => {
    var signingKey = key.publicKey || key.rsaPublicKey;
    callback(null, signingKey);
  });
}

export function isTokenValid(token, appId, tenantId) {
  return new Promise((resolve) => {
    const options = {
      audience: [appId],
      issuer: [`https://sts.windows.net/${tenantId}/`]
    };
    jwt.verify(token, getKey, options, (err) => {
      if (err) {
        // eslint-disable-next-line no-console
        console.error(err);
        resolve(false);
      } else {
        resolve(true);
      }
    });
  });
}

Descriptografar os dados de recursos de notificações de alteração

A propriedade resourceData de uma notificação de alteração inclui apenas o ID básico e as informações do tipo de uma instância de recurso. A propriedade encryptedData contém os dados de recursos completos, criptografados pelo Microsoft Graph usando a chave pública fornecida na assinatura. A propriedade também contém valores necessários para verificação e descriptografia. Esta encriptação é feita para aumentar a segurança dos dados dos clientes acedidos através de notificações de alteração. É da sua responsabilidade proteger a chave privada para garantir que terceiros não conseguem desencriptar os dados do cliente, mesmo que consigam intercetar as notificações de alteração originais.

Nesta secção, irá aprender os seguintes conceitos:

• Gerenciar as chaves de criptografia
• Descriptografar os dados de recursos
• Exemplo: descriptografar uma notificação com dados de recursos criptografados

Gerenciar as chaves de criptografia

1. Obtenha um certificado com um par de chaves assimétricas.

   • Pode utilizar um certificado autoassinado, uma vez que o Microsoft Graph não verifica o emissor do certificado e utiliza a chave pública apenas para encriptação.

   • Utilize o Azure Key Vault para criar, rodar e gerir certificados de forma segura. Cerifique-se de que as chaves atendem aos seguintes critérios:

     • A chave tem de ser do tipo RSA.
     • O tamanho da chave tem de estar entre 2048 bits e 4096 bits.

2. Exporte o certificado no formato X.509 codificado com Base64 e inclua apenas a chave pública.

3. Ao criar uma assinatura:

   • Forneça o certificado na propriedade encryptionCertificate , utilizando o conteúdo codificado em Base64 no qual o certificado foi exportado.

   • Forneça seu próprio identificador na propriedade encryptionCertificateId.

     Esse identificador permite corresponder seus certificados às notificações de alterações recebidas e recuperar certificados do seu repositório de certificados. O identificador pode ter no máximo 128 caracteres.

4. Gerencie com segurança a chave privada com para que seu código de processamento de notificação de alteração acesse a chave privada para decriptar os dados do recurso.

Chaves de rotação

Para minimizar o risco de uma chave privada ser comprometida, altere periodicamente suas chaves assimétricas. Siga estas etapas para introduzir um novo par de chaves:

1. Obtenha um novo certificado com um novo par de chaves assimétricas. Use-o para todas as novas assinaturas sendo criadas.

2. Atualize as assinaturas existentes com a nova chave de certificado.

   • Faça desta atualização parte da renovação regular da subscrição.
   • Ou enumere todas as assinaturas e forneça a chave. Use a operação PATCH na assinatura e atualize as propriedades encryptionCertificate e encryptionCertificateId.

3. Tenha em atenção os seguintes princípios:

   • Durante algum tempo, o certificado antigo ainda pode ser utilizado para encriptação. Seu aplicativo deve ter acesso a certificados novos e antigos para poder descriptografar o conteúdo.
   • Use a propriedade encryptionCertificateId em cada notificação de alteração para identificar a chave correta a ser utilizada.
   • Elimine o certificado antigo apenas quando não vir notificações de alteração recentes a referenciá-lo.

Descriptografar dados de recursos

Para otimizar o desempenho, o Microsoft Graph usa um processo de criptografia de duas etapas:

• Gera uma chave simétrica de utilização única e utiliza-a para encriptar dados de recursos.
• Ele usa a chave pública assimétrica (que você forneceu ao fazer a assinatura) para criptografar a chave simétrica e a incluir em cada notificação de alteração desta assinatura.

Sempre assuma que a chave simétrica é diferente para cada item na notificação de alteração.

Para decriptar os dados de recursos, o seu aplicativo deve executar as etapas inversas, usando as propriedades encryptedContent em cada notificação de alteração:

1. Use a propriedade encryptionCertificateId para identificar o certificado a ser usado.

2. Inicialize um componente criptográfico RSA com a chave privada. Uma forma fácil de inicializar um componente RSA é utilizar o Método RSACertificateExtensions.GetRSAPrivateKey(X509Certificate2) com uma instância X509Certificate2 , que contém a chave privada descrita em Gerir chaves de encriptação.

3. Decripte a chave simétrica entregue na propriedade dataKey de cada item na notificação de alteração.

   Use o Preenchimento de Criptografia Assimétrica Ideal (OAEP) para o algoritmo de descriptografia.

4. Use a chave simétrica para calcular a assinatura HMAC-SHA256 do valor em dados.

   Compare-o com o valor em dataSignature. Se não corresponderem, suponha que o payload foi adulterado e não o desencripte.

5. Utilize a chave simétrica com uma Norma de Encriptação Avançada (AES) (como os .NET Aes) para desencriptar o conteúdo nos dados.

   • Use os seguintes parâmetros de descriptografia para o algoritmo AES:

     • Preenchimento: PKCS7
     • Modo de criptografia: CBC

   • Defina o “vetor de inicialização” copiando os primeiros 16 bytes da chave simétrica usada para descriptografia.

6. O valor decriptado é uma sequência JSON que representa a instância do recurso na notificação de alteração.

Exemplo: decriptando uma notificação com dados de recurso criptografados

O exemplo JSON seguinte mostra uma notificação de alteração que inclui valores de propriedade encriptadas de uma instância chatMessage numa mensagem de canal. O @odata.id valor especifica a instância.

{
  "value": [
    {
      "subscriptionId": "76222963-cc7b-42d2-882d-8aaa69cb2ba3",
      "changeType": "created",
      // Other properties typical in a resource change notification
      "resource": "teams('d29828b8-c04d-4e2a-b2f6-07da6982f0f0')/channels('19:f127a8c55ad949d1a238464d22f0f99e@thread.skype')/messages('1565045424600')/replies('1565047490246')",
      "resourceData": {
        "id": "1565293727947",
        "@odata.type": "#Microsoft.Graph.ChatMessage",
        "@odata.id": "teams('88cbc8fc-164b-44f0-b6a6-b59b4a1559d3')/channels('19:8d9da062ec7647d4bb1976126e788b47@thread.tacv2')/messages('1565293727947')/replies('1565293727947')"
      },
      "encryptedContent": {
        "data": "{encrypted data that produces a full resource}",
        "dataSignature": "<HMAC-SHA256 hash>",
        "dataKey": "{encrypted symmetric key from Microsoft Graph}",
        "encryptionCertificateId": "MySelfSignedCert/DDC9651A-D7BC-4D74-86BC-A8923584B0AB",
        "encryptionCertificateThumbprint": "07293748CC064953A3052FB978C735FB89E61C3D"
      }
    }
  ],
  "validationTokens": [
    "eyJ0eXAiOiJKV1QiLCJhbGciOiJSU..."
  ]
}

Para obter uma descrição completa dos dados enviados quando as notificações de alteração são entregues, veja changeNotificationCollection resource type (Tipo de recurso changeNotificationCollection).

Descriptografar a chave simétrica

A seção contém alguns trechos de código úteis que usam C# e .NET em cada etapa da descriptografia.

C#

// Initialize with the private key that matches the encryptionCertificateId.
X509Certificate2 certificate = <instance of X509Certificate2 matching the encryptionCertificateId property>;
RSA rsa = certificate.GetRSAPrivateKey();
byte[] encryptedSymmetricKey = Convert.FromBase64String(<value from dataKey property>);

// Decrypt using OAEP padding.
byte[] decryptedSymmetricKey = rsa.Decrypt(encryptedSymmetricKey, fOAEP: true);

// Can now use decryptedSymmetricKey with the AES algorithm.

Java

String storename = ""; //name/path of the jks store
String storepass = ""; //password used to open the jks store
String alias = ""; //alias of the certificate when store in the jks store, should be passed as encryptionCertificateId when subscribing and retrieved from the notification
KeyStore ks = KeyStore.getInstance("JKS");
ks.load(new FileInputStream(storename), storepass.toCharArray());
Key asymmetricKey = ks.getKey(alias, storepass.toCharArray());
byte[] encryptedSymmetricKey = Base64.decodeBase64("<value from dataKey property>");
Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA1AndMGF1Padding");
cipher.init(Cipher.DECRYPT_MODE, asymmetricKey);
byte[] decryptedSymmetricKey = cipher.doFinal(encryptedSymmetricKey);
// Can now use decryptedSymmetricKey with the AES algorithm.

JavaScript

const base64encodedKey = 'base 64 encoded dataKey value';
const asymmetricPrivateKey = 'pem encoded private key';
const decodedKey = Buffer.from(base64encodedKey, 'base64');
const decryptedSymmetricKey = crypto.privateDecrypt(asymmetricPrivateKey, decodedKey);
// Can now use decryptedSymmetricKey with the AES algorithm.

Comparar assinatura de dados usando HMAC-SHA256

C#

byte[] decryptedSymmetricKey = <the aes key decrypted in the previous step>;
byte[] encryptedPayload = <the value from the data property, still encrypted>;
byte[] expectedSignature = <the value from the dataSignature property>;
byte[] actualSignature;

using (HMACSHA256 hmac = new HMACSHA256(decryptedSymmetricKey))
{
    actualSignature = hmac.ComputeHash(encryptedPayload);
}
if (actualSignature.SequenceEqual(expectedSignature))
{
    // Continue with decryption of the encryptedPayload.
}
else
{
    // Do not attempt to decrypt encryptedPayload. Assume notification payload has been tampered with and investigate.
}

Java

byte[] decryptedSymmetricKey = "<the aes key decrypted in the previous step>";
byte[] decodedEncryptedData = Base64.decodeBase64("data property from encryptedContent object");
Mac mac = Mac.getInstance("HMACSHA256");
SecretKey skey = new SecretKeySpec(decryptedSymmetricKey, "HMACSHA256");
mac.init(skey);
byte[] hashedData = mac.doFinal(decodedEncryptedData);
String encodedHashedData = new String(Base64.encodeBase64(hashedData));
if (comparisonSignature.equals(encodedHashedData))
{
    // Continue with decryption of the encryptedPayload.
}
else
{
    // Do not attempt to decrypt encryptedPayload. Assume notification payload has been tampered with and investigate.
}

JavaScript

const decryptedSymmetricKey = []; //Buffer provided by previous step
const base64encodedSignature = 'base64 encoded value from the dataSignature property';
const hmac = crypto.createHmac('sha256', decryptedSymmetricKey);
hmac.write(base64encodedPayload, 'base64');
if(base64encodedSignature === hmac.digest('base64'))
{
    // Continue with decryption of the encryptedPayload.
}
else
{
    // Do not attempt to decrypt encryptedPayload. Assume notification payload has been tampered with and investigate.
}

Descriptografar o conteúdo dos dados de recursos

C#

Aes aesProvider = Aes.Create();
aesProvider.Key = decryptedSymmetricKey;
aesProvider.Padding = PaddingMode.PKCS7;
aesProvider.Mode = CipherMode.CBC;

// Obtain the initialization vector from the symmetric key itself.
int vectorSize = 16;
byte[] iv = new byte[vectorSize];
Array.Copy(decryptedSymmetricKey, iv, vectorSize);
aesProvider.IV = iv;

byte[] encryptedPayload = Convert.FromBase64String(<value from data property>);

string decryptedResourceData;
// Decrypt the resource data content.
using (var decryptor = aesProvider.CreateDecryptor())
{
  using (MemoryStream msDecrypt = new MemoryStream(encryptedPayload))
  {
      using (CryptoStream csDecrypt = new CryptoStream(msDecrypt, decryptor, CryptoStreamMode.Read))
      {
          using (StreamReader srDecrypt = new StreamReader(csDecrypt))
          {
              decryptedResourceData = srDecrypt.ReadToEnd();
          }
      }
  }
}

// decryptedResourceData now contains a JSON string that represents the resource.

Java

SecretKey skey = new SecretKeySpec(decryptedSymmetricKey, "AES");
IvParameterSpec ivspec = new IvParameterSpec(Arrays.copyOf(decryptedSymmetricKey, 16));
Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5PADDING");
cipher.init(Cipher.DECRYPT_MODE, skey, ivspec);
String decryptedResourceData = new String(cipher.doFinal(Base64.decodeBase64(encryptedData)));

JavaScript

const base64encodedPayload = 'base64 encoded value from data property';
const decryptedSymmetricKey = []; //Buffer provided by previous step
const iv = Buffer.alloc(16, 0);
decryptedSymmetricKey.copy(iv, 0, 0, 16);
const decipher = crypto.createDecipheriv('aes-256-cbc', decryptedSymmetricKey, iv);
let decryptedPayload = decipher.update(base64encodedPayload, 'base64', 'utf8');
decryptedPayload += decipher.final('utf8');

Conteúdo relacionado

• Tipo de recurso de assinatura