Detectar compartilhamento de conta

Um conjunto de credenciais, usado por mais pessoas do que pagaram por ele: a assinatura compartilhada, os dois assentos que silenciosamente atendem oito pessoas, a conta revendida. Nada disso parece incomum nos seus próprios logs, porque cada acesso é um login bem-sucedido com a senha certa.

O Device Intelligence adiciona o que falta aos logs: uma identidade de dispositivo em cada sessão. Marque a sua telemetria com a conta que está logando, e o veredito chega ao seu backend durante o próprio login. No painel você também vê a forma disso: quais dispositivos, logando de onde, se as sessões se sobrepuseram e se a conta pulou de região mais rápido do que qualquer pessoa consegue viajar.

O mesmo mecanismo aplica limites de licenças. Defina o limite para o número de assentos vendidos, e a regra avisa quando um cliente silenciosamente os ultrapassou.

Como a cside detecta o compartilhamento de conta

Marque a sua telemetria com o id da conta de quem está logado. A cside conta os dispositivos distintos vistos para aquela conta dentro de uma janela deslizante, e quando essa contagem ultrapassa o limite do seu site, a regra dispara.

Isso acontece em duas metades, e elas rodam em lugares diferentes:

• O seu navegador chama sendClientTelemetry({ userId }) e recebe um token de volta.
• O seu servidor envia esse token para a cside e lê o veredito.

Mantenha a checagem do veredito no seu servidor. A sua chave de API de Device Intelligence não pode chegar perto do código do navegador, e um veredito que o navegador pudesse ler seria um veredito que o navegador poderia forjar.

O que você vai precisar

• Device Intelligence ativado no domínio
• O script instalado e sendClientTelemetry sendo chamado: veja Configurar Device Intelligence
• Uma chave de API de Device Intelligence de backend: veja Events API
• A regra ativada para o seu domínio. A ativação self-serve ainda não existe, então peça à cside para ativá-la

No navegador: envie o id da conta

import { initDeviceIntelligence } from "@cside.dev/device-intelligence";

const { sendClientTelemetry } = await initDeviceIntelligence({
  teamID: "[your-team-id]",
});

// Call this at sign-in, and anywhere else you want to refresh the reading:
// long-running sessions benefit from a periodic call.
async function onSignIn(userId) {
  const { token, errors } = await sendClientTelemetry({ userId });

  if (errors) {
    console.error(errors);
    return;
  }

  // Your own backend route, not a cside endpoint. It does the actual
  // verdict check server-side; see the next section.
  await fetch("/api/account-sharing-check", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ token }),
  });
}

No seu servidor: leia o veredito

Esta é a rota /api/account-sharing-check do passo anterior. Ela troca o token pela avaliação completa e decide o que fazer, tudo no servidor, com a sua chave de API de Device Intelligence.

curl https://api.cside.com/token/v2/verify \
  --request POST \
  --header "Authorization: Bearer $CSIDE_FINGERPRINT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"token":"'"$CSIDE_FINGERPRINT_SESSION_TOKEN"'"}'

O endpoint retorna 202 Accepted com { "status": "pending" } enquanto a avaliação ainda está rodando, e depois 200 OK quando termina. Faça polling até cerca de 3 vezes, com um intervalo de aproximadamente 3 segundos como limite superior seguro: o motor de regras roda de forma síncrona como parte de armazenar o resultado, então o veredito costuma estar pronto já na primeira consulta. E ele está pronto por completo: rule_evaluations_v2 é preenchido no exato momento em que status se torna "completed", nunca depois, então, uma vez que você veja "completed", uma entrada ausente está genuinamente ausente, não a caminho ainda. Se você esgotar as tentativas e ainda estiver pendente, trate como se não houvesse veredito para esse login, em vez de bloquear a pessoa: o próximo login produz uma nova avaliação.

Aqui está tudo montado: troque o token, verifique se ele pertence à conta que está de fato logada, depois encontre a entrada de compartilhamento de conta e decida com base nela. Verifique tanto outcome quanto evaluated_as no próprio código, não apenas o slug da regra: outras regras, incluindo o experimento shadow de outra pessoa, podem viajar no mesmo array.

// apps/api-style illustrative route handler. Adjust to your own framework.
// The wire sends these as integers. Naming them keeps the check readable;
// the full set of values is in the tables below.
const OUTCOME_TRUE = 1;
const LIFECYCLE_ACTIVE = 3;

app.post("/api/account-sharing-check", async (req, res) => {
  const { token } = req.body;
  const evaluation = await verifyToken(token);

  // Trust your own session, never the browser. The userId on the telemetry is
  // whatever the page chose to send, so bind it to the signed-in account
  // before you act on anything.
  if (evaluation.fingerprint?.external_ids?.userId !== req.session.userId) {
    return res.sendStatus(409);
  }

  const sharing = findAccountSharing(evaluation);

  if (sharing !== undefined) {
    // This account is over your site's device limit right now.
    // Step up auth, cap sessions, flag for review: see "Decide what to do" below.
  }

  res.sendStatus(204);
});

async function verifyToken(token, attempt = 0) {
  const response = await fetch("https://api.cside.com/token/v2/verify", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CSIDE_FINGERPRINT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ token }),
  });

  if (!response.ok) {
    // An expired key, a bad token, a rate limit. Never fall through: a failed
    // request is an outage, not a verdict of "nobody is sharing this account".
    throw new Error(`Device Intelligence verify failed: ${response.status}`);
  }

  const data = await response.json();

  if (data.status === "pending" && attempt < 3) {
    await new Promise((resolve) => setTimeout(resolve, 3000));
    return verifyToken(token, attempt + 1);
  }

  if (data.status === "failed") {
    // Evaluation itself failed. Don't treat this the same as "no entry":
    // a failure isn't the healthy case.
    throw new Error("Device Intelligence evaluation failed");
  }

  return data;
}

function findAccountSharing(data) {
  // An absent entry means the rule wasn't evaluated, not that it
  // evaluated to false.
  return data.rule_evaluations_v2?.values?.find(
    (v) =>
      v.evaluation.rule_slug === "account_shared_detected" &&
      v.evaluation.outcome === OUTCOME_TRUE &&
      // Shadow rules ride in the same array. Acting on one would enforce
      // an experiment that isn't live for your site.
      v.evaluation.evaluated_as === LIFECYCLE_ACTIVE,
  );
}

outcome e evaluated_as são inteiros, não strings. Toda regra avaliada e publicada relata uma entrada em cada evento, seja qual for o resultado em que ela cai: 1, 2 e 3 são estados estáveis que você vai ver continuamente, não ocorrências pontuais. 4 é a exceção, e significa algo mais específico do que parece: a regra precisa de uma medição que existe mas ainda não esquentou. Isso é diferente de um status de "pending", que significa que a própria avaliação ainda não terminou, e é para isso que serve o loop de polling acima. Fazer polling do mesmo token com mais insistência não vai transformar um 4 em um veredito; ele se resolve em avaliações posteriores conforme os dados se acumulam para aquela conta.

Mesmo enum da referência de rule_evaluations_v2; aqui está o que cada valor significa especificamente para esta regra:

Uma observação sobre transition, útil se você preferir agir uma vez em vez de a cada requisição: uma vez que você já verificou outcome: 1, transition: 3 significa que a conta acabou de ultrapassar o limite nesta avaliação, e transition: 2 significa que ela já está acima dele desde uma avaliação anterior.

A conta que disparou a regra está em fingerprint.external_ids na mesma resposta, não em evaluation.key. key é um hash do que a regra usou como chave e nunca carrega o id da conta em texto plano. Note também que key.key_hash é uma string JSON, não um número, e que este corpo de resposta mistura dois formatos de timestamp: created_at e updated_at no nível superior são números em milissegundos, enquanto evaluated_at e event_time dentro da avaliação são objetos { seconds, nanos }.

Exemplo de resposta reduzido, capturado de uma avaliação real, com outros campos omitidos. Repare na segunda entrada: outras regras realmente viajam no mesmo array, e é por isso que o código acima combina o slug, outcome e evaluated_as juntos, não apenas o slug.

{
  "status": "completed",
  "created_at": 1789731723590,
  "updated_at": 1789731723590,
  "fingerprint": {
    "device_id": "dev_3f8a21c9",
    "external_ids": {
      "userId": "acct_9f2a1c"
    }
  },
  "rule_evaluations_v2": {
    "values": [
      {
        "evaluation": {
          "rule_slug": "account_shared_detected",
          "outcome": 1,
          "evaluated_as": 3,
          "transition": 3,
          "key": { "key_hash": "16386830586737169487" },
          "event_time": { "seconds": 1789731723, "nanos": 590000000 },
          "evaluated_at": { "seconds": 1789731723, "nanos": 605000000 }
        }
      },
      {
        "evaluation": {
          "rule_slug": "multi_account_detected",
          "outcome": 2,
          "evaluated_as": 3,
          "transition": 2,
          "key": { "key_hash": "261153104274697293" },
          "event_time": { "seconds": 1789731723, "nanos": 590000000 },
          "evaluated_at": { "seconds": 1789731723, "nanos": 605000000 }
        }
      }
    ]
  }
}

Não mostrado acima: alguns objetos aninhados na resposta completa usam nomes de campo em camelCase em vez de snake_case, onde compartilham um formato de transmissão com o designer de regras do painel (dentro de explanation, e key.components[].dimension). Se você imprimir a sua própria resposta completa e ver uma mistura dos dois, isso é esperado, não um bug na sua integração.

Veja a referência completa de campos de rule_evaluations_v2 para o restante dos campos.

Decida o que fazer a respeito

A cside relata, não bloqueia. O que você faz com uma regra disparada é decisão sua: escalar a autenticação, limitar sessões simultâneas para a conta, ou marcar para revisão manual.

Confirme que está funcionando

Primeiro, confirme que o id está realmente chegando: troque um token e verifique se fingerprint.external_ids contém o valor que você espera sob userId.

Depois verifique a própria regra, antes que alguém compartilhe qualquer coisa. Como toda regra avaliada e publicada relata em cada evento, você não precisa disparar um compartilhamento para ver se o pipeline funciona:

• outcome: 2 na entrada account_shared_detected é como se parece uma integração saudável e corretamente configurada: a regra está rodando, lendo a chave certa, e ninguém está acima do limite. Esta é a sua confirmação negativa, e você vai vê-la continuamente, não só uma vez.
• outcome: 3 significa que você está enviando a chave errada. Corrija agora, antes de testar mais; veja Já envia um id diferente?.
• Nenhuma entrada para account_shared_detected significa que a regra ainda não foi ativada para este domínio, é uma regra apenas de medição que não publica, ou a avaliação não rodou para este evento. Pergunte à cside.

curl https://api.cside.com/token/v2/verify \
  --request POST \
  --header "Authorization: Bearer $CSIDE_FINGERPRINT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"token":"'"$CSIDE_FINGERPRINT_SESSION_TOKEN"'"}'

# rule_evaluations_v2 carries the rule outcomes, account_shared_detected among them.
# If "status" is "pending", wait a few seconds and retry, up to about 3 times.

Depois de confirmar isso na API, abra essa sessão no painel da cside: sua página de detalhes da sessão tem uma aba Identity graph que mostra a mesma coisa visualmente, uma conta se ramificando em vários nós de dispositivo.

Se o seu time tem acesso à página do caso de uso de compartilhamento de conta no painel, o seu tile de cobertura é a forma mais direta de pegar uma chave errada: ele mede que fração dos seus eventos realmente carrega o id que a regra lê. Essa página ainda está em acesso antecipado, então pode não estar ativada para você.

Próximos passos

• Configurar Device Intelligence
• Events API
• Revisar uma sessão no painel
• Casos de uso

Solução de problemas

Quase toda integração que não vê nada tem a mesma causa: o id externo que você envia não é o que a regra lê. userId é o padrão em vez de uma exigência, então a cside pode reconfigurar a regra para qualquer um dos outros campos que podem servir de chave. A sua telemetria e a regra só precisam concordar sobre um deles.

1. Verifique o que chegou. Troque um token e olhe fingerprint.external_ids. Se o id da sua conta não estiver lá, sendClientTelemetry rodou sem ele, ou rodou antes de você saber quem estava logando.
2. Verifique se a regra conseguiu lê-lo. Um outcome de 3 na entrada account_shared_detected significa que a regra rodou e não conseguiu encontrar a sua chave.
3. Verifique se o valor é estável. Um id de sessão ou um token rotativo faz cada login parecer uma conta nova, então nada nunca se acumula em uma só.
4. Reconfigure em vez de reescrever. Peça à cside para apontar a regra para a sua chave. Veja Já envia um id diferente?.