Pular para o conteúdo principal

Visão Geral

O OneSignal oferece um recurso de segurança aprimorado chamado Verificação de Identidade para ajudar a prevenir personificação de usuário. Este recurso utiliza JSON Web Tokens – ou JWTs, gerados com segurança em seu servidor. Para verificar informações de assinatura, esses tokens são passados para seu aplicativo e API do OneSignal. Habilite a Verificação de Identidade para proteger:
  • Fazer login de usuários
  • Adicionar assinaturas de email
  • Adicionar assinaturas de SMS
  • Modificar identidades de usuário
A Verificação de Identidade está atualmente em beta. Contate support@onesignal.com para habilitá-la em sua conta. Depois que o suporte habilitá-la, você a ativa no painel (veja Etapa 5).

Pré-requisitos

Suporte a wrapper SDK (Flutter, React Native, Unity, etc.) em breve.

Configuração

1

Gerar novas chaves

Faça login em sua conta OneSignal e navegue até Settings > Keys & IDs > Identity Verification.
Settings page showing Keys and IDs with Identity Verification section
Clique em Generate New Keys para criar um novo par de chaves.
Generate New Keys button in the Identity Verification section
Baixe o arquivo PEM ou copie a chave privada, certificando-se de armazenar a chave privada com segurança.
Identity Verification key pair with private key and PEM download
Sempre armazene suas chaves privadas em um ambiente seguro, como um sistema de gerenciamento de chaves. Nunca exponha chaves privadas em código do lado do cliente, repositórios públicos ou logs.
2

Gerar JWT de verificação em seu backend

A verificação de identidade requer autenticar o usuário final com seu servidor de autenticação antes de fazer login no OneSignal. Quando o usuário final autentica com seu backend, gere o token e inclua-o na resposta de autenticação para o dispositivo. Se seu aplicativo não executar um servidor backend, considere configurar um servidor leve para verificar usuários e gerar esses tokens.

Payload do JWT

O JWT pode ter as seguintes propriedades:
iss
obrigatório
Seu OneSignal App ID
exp
obrigatório
A data de expiração do token.
identity
obrigatório
O alias do usuário.
subscriptions
Obrigatório apenas ao adicionar assinaturas de Email e SMS a um usuário.

Assinar o JWT

Assine o JWT usando o algoritmo ES256. Certifique-se de que seu backend está configurado para usar este método de assinatura para evitar problemas de verificação ao enviar o JWT para o OneSignal. Recomendamos uma Biblioteca JWT para fazer isso.Exemplo usando jsonwebtoken:
import jwt from 'jsonwebtoken';

const APP_ID = process.env['ONESIGNAL_APP_ID']
const IDENTITY_VERIFICATION_SECRET = process.env['ONESIGNAL_IDENTITY_VERIFICATION_SECRET_KEY']

// Generates JWT, potentially with subscription claims, for the user identified by the External ID
function signOneSignalJWT(externalId, subscriptions) {
return jwt.sign({
iss: APP_ID,
exp: Math.floor(Date.now() / 1000) + 3600, // 1-hour expiration
identity: {
'external_id': externalId,
},
subscriptions
},
IDENTITY_VERIFICATION_SECRET,
{ algorithm: 'ES256' });
}

// Pass this token to your mobile app to use with the `login` SDK method
const onesignalJWT = signOneSignalJWT('EXTERNAL_ID');

A chave privada está no arquivo da etapa anterior que baixamos do Painel.

Verificar seu JWT

Antes de integrar com o SDK, verifique se seu JWT está sendo gerado corretamente iniciando seu servidor e chamando o endpoint:
  node server.js
  curl http://localhost:3000/generate-jwt/your-external-id
Você deve receber uma resposta como:
{
  "jwt": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Cole o valor do JWT em jwt.io e confirme que o payload decodificado contém os seguintes parâmetros:
{
  "iss": "your-onesignal-app-id",
  "exp": 1234567890,
  "identity": {
    "external_id": "your-external-id"
  }
}
Confirme o seguinte antes de passar para a próxima etapa:
  • iss corresponde ao seu ID de Aplicativo OneSignal em Settings > Keys & IDs
  • identity.external_id está presente e corresponde ao valor que você passará para OneSignal.login()
  • exp é um timestamp futuro — um token expirado será rejeitado pelo OneSignal

Incluindo assinaturas

Idealmente, detalhes de assinatura, como email ou número de telefone, são incluídos no payload do JWT ao fazer login de um usuário. Se esses detalhes não estiverem disponíveis antecipadamente, seu servidor de verificação deve fornecer um endpoint para gerar tokens dinamicamente conforme as informações de assinatura ficam disponíveis.Exemplo: Gerar JWT para adicionar assinaturas
const subscriptions = [
  {
      "type": "Email",
      "token": "[email protected]"
  },
  {
      "type": "SMS",
      "token": "+12345678"
  }
]
const onesignalJWT = signOneSignalJWT('EXTERNAL_ID', subscriptions)
3

Passar JWT para o método `login`

Depois que seu backend gerar o JWT, chame o método login com ele. Este token garante que a identidade do usuário seja verificada antes que quaisquer alterações, como adicionar uma assinatura de email ou SMS, possam ser feitas.Exemplo de fazer login:
String externalId = "YOUR_EXTERNAL_ID";
String onesignalJWT = "YOUR_JWT_TOKEN";

OneSignal.login(externalId, onesignalJWT);
4

Manipular eventos do ciclo de vida do JWT

Você precisará implementar um endpoint dedicado em seu backend para lidar com cenários como invalidação de token. Este endpoint deve fornecer um JWT atualizado quando o OneSignal solicitar uma atualização.Exemplo de lidar com invalidação de token e atualizar o JWT:
OneSignal.addUserJwtInvalidatedListener(event -> {
  // Get the expired user's External ID
  String externalId = event.getExternalId();

  // Fetch a new JWT from your backend for the user
  String onesignalJWT = "yourUpdatedToken";

  // Provide the new JWT to the SDK
  OneSignal.updateUserJwt(externalId, onesignalJWT);
});
Isso garante que quando o JWT de um usuário for invalidado, um novo possa ser buscado do seu backend e passado para o OneSignal. Você também pode usar esta função para gerar um token com email e número de telefone, permitindo que você gerencie assinaturas de email e SMS se o token criado durante a autenticação não os contiver.
5

Habilitar verificação de identidade de token no painel

Em Settings > Keys & IDs, alterne Token Identity Verification para habilitar.
Token Identity Verification toggle enabled in dashboard settings
Uma vez habilitado, seu aplicativo deve enviar JWTs do OneSignal para verificar a autenticidade da assinatura. Além disso, seu aplicativo é obrigado a chamar o método login usando um JWT gerado pelo seu servidor de token de verificação de identidade.

Adicionar assinaturas

Você não precisa realizar etapas extras para adicionar assinaturas do seu aplicativo móvel; chamar o método de login lida automaticamente com isso para você.
OneSignal.getUser().addEmail(emailAddress);

API REST

Quando a Verificação de Identidade de Token está habilitada, todas as solicitações para as seguintes APIs devem incluir um JWT gerado pelo servidor nos cabeçalhos como um token de portador, por exemplo, Authorization: Bearer <JWT>.

FAQ

A verificação de identidade é obrigatória?

Não, mas é fortemente recomendada. Sem ela, qualquer cliente que conheça o ID de Usuário Externo de um usuário pode se passar por esse usuário e modificar suas assinaturas ou dados.

O que acontece se o JWT expirar durante uma sessão?

O SDK dispara um evento de invalidação de JWT. Implemente o addUserJwtInvalidatedListener (veja Manipular eventos do ciclo de vida do JWT) para buscar um token atualizado do seu backend e passá-lo para updateUserJwt.

Quais SDKs suportam verificação de identidade?

Atualmente, o SDK Android nativo (5.2.0+) e o SDK iOS (5.3.0+). Suporte a wrapper SDK (Flutter, React Native, Unity, etc.) em breve.

Preciso de verificação de identidade para a API REST?

Quando a Verificação de Identidade de Token está habilitada, todas as solicitações para as APIs suportadas devem incluir um JWT gerado pelo servidor como token de portador no cabeçalho Authorization. O JWT é gerado da mesma forma que para uso do SDK.

Qual algoritmo o JWT usa?

A Verificação de Identidade requer JWTs assinados com o algoritmo ES256 (ECDSA usando P-256 e SHA-256). Outros algoritmos serão rejeitados.