Pular para o conteúdo principal
Gere um JWT no seu servidor e passe-o para OneSignal.login para que um cliente não possa se passar por outro External ID. O mesmo token pode autorizar a adição de assinaturas de e-mail e SMS e determinadas chamadas à User REST API. A verificação de identidade está disponível para todos nos SDKs nativos para Android e iOS e no SDK Web. Ela ainda não é compatível com SDKs multiplataforma (por exemplo, Flutter, React Native etc.).

SDKs compatíveis \

SDKs não compatíveis não têm como passar um JWT para login. O suporte a eles chegará em breve. Ative a verificação de identidade para proteger:
  • O login de usuários
  • A adição de assinaturas de e-mail
  • A adição de assinaturas de SMS
  • A modificação de identidades e aliases de usuários
O painel permite ativar o Token Identity Verification em qualquer aplicativo, mesmo que seu aplicativo use um SDK que não consegue enviar um JWT. A chave se aplica ao aplicativo inteiro, em todas as plataformas.Se algum cliente do aplicativo usar um SDK multiplataforma ou uma versão do SDK Web anterior à v16, não ative a chave. Depois que ela é ativada, o OneSignal rejeita as solicitações desses clientes que criam ou atualizam usuários e assinaturas. login, addEmail e addSms falham, e novos dispositivos nesses clientes não conseguem registrar uma assinatura push.Você ainda pode gerar chaves e implementar a assinatura de JWTs no seu servidor agora. Somente a chave aplica a verificação.

Pré-requisitos \

  • Um aplicativo OneSignal existente com uma plataforma push configurada.
  • Todo cliente que chama login usa um SDK compatível: o SDK nativo para Android 5.9.0+, o SDK nativo para iOS 5.8.0+ ou o SDK Web 160900+.
  • Um backend que autentica seus usuários e pode assinar JWTs.
  • Acesso a Settings > Keys & IDs no painel do OneSignal. A seção Identity Verification está disponível para todos os aplicativos. Você não precisa entrar em contato com o suporte.

Gerar chaves \

Conclua estas etapas em ordem: gere as chaves, crie o JWT e depois adicione-o ao seu aplicativo. Não ative a chave Token Identity Verification até que seu backend consiga emitir JWTs e seu aplicativo consiga passá-los para login. Faça login na sua conta do OneSignal e acesse Settings > Keys & IDs > Identity Verification.
Página de configurações mostrando a seção Identity Verification

Configuração da verificação de identidade

Clique em Generate New Keys para criar um novo par de chaves.
Botão Generate New Keys na seção Identity Verification

Criação de um novo par de chaves

Baixe o arquivo PEM ou copie a chave privada e armazene-a com segurança. Essa chave privada não é uma App API key. Use-a somente para assinar JWTs de verificação de identidade.
Par de chaves de verificação de identidade com a chave privada e o download do PEM

Par de chaves de verificação de identidade

Sempre armazene 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.
Agora você tem uma chave privada armazenada no seu servidor e uma chave pública mantida pelo OneSignal.

Criar o JWT \

Autentique o usuário com seu próprio servidor antes de assinar um token. Quando essa autenticação for bem-sucedida, assine um JWT ES256 com as claims abaixo e retorne-o ao dispositivo na sua resposta de autenticação. Se o seu aplicativo não tiver backend, configure um pequeno servidor cuja única função seja verificar usuários e assinar esses tokens. Nunca assine JWTs no dispositivo.

Payload do JWT \

Assinar o JWT \

Assine o JWT com o algoritmo ES256 (ECDSA usando P-256 e SHA-256). Outros algoritmos são rejeitados. Use uma biblioteca de JWT em vez de montar o token manualmente. Exemplo usando jsonwebtoken. Passe a chave privada PEM que você baixou na etapa anterior:
Node.js
Armazene a chave privada PEM com as quebras de linha intactas. Muitos sistemas de variáveis de ambiente removem quebras de linha, o que faz a assinatura ES256 falhar. Preserve os caracteres \n literais ou codifique a chave em base64 e decodifique-a em tempo de execução.

Verificar seu JWT \

Registre ou retorne a string de signOneSignalJWT() e depois decodifique-a para confirmar o payload. O jwt.io decodifica tokens no seu navegador, mas trate o token de um usuário real como um segredo e use um token de teste ao colá-lo em ferramentas de terceiros. O payload decodificado deve ter esta aparência:
Confirme todos os itens a seguir antes de chamar login:
  • iss corresponde ao seu App ID do OneSignal em Settings > Keys & IDs
  • identity.external_id corresponde ao valor que você passará para OneSignal.login()
  • exp está no futuro e expresso em segundos

Incluir assinaturas \

Inclua o e-mail e o SMS no JWT no login quando você já tiver esses valores. Se eles chegarem depois, emita um novo JWT que inclua a claim subscriptions e passe-o para updateUserJwt antes de chamar addEmail ou addSms. Consulte Adicionar assinaturas.
Node.js
Os números de telefone devem usar o formato E.164.

Adicionar o JWT ao seu aplicativo \

Conclua estas etapas no seu aplicativo ou site.
1

Passe o JWT para o método login

Chame login com o External ID e o JWT. Até que o Token Identity Verification seja ativado no painel, o SDK não envia o JWT, então você pode publicar esta atualização do aplicativo antes de ativar a chave. Depois de ativar a chave, login sem um JWT válido falha.
Em caso de sucesso, o OneSignal associa a assinatura do dispositivo ao seu External ID e o usuário passa a ser um usuário identificado.Android 5.11.0 e posteriores: para definir o e-mail, o número de telefone, as tags e os aliases do usuário na mesma solicitação, passe o JWT como terceiro argumento para login(external_id, profile). Inclua o e-mail e o número de telefone do perfil na claim subscriptions do JWT. Consulte Adicionar assinaturas.
Se o OneSignal rejeitar o JWT, loginResult falha com BACKEND_ERROR e o status HTTP 401, e o SDK dispara o evento de JWT invalidado descrito na próxima etapa. O SDK mantém o login na fila e tenta novamente depois que você chama updateUserJwt.
2

Trate os eventos do ciclo de vida do JWT

Quando o OneSignal rejeita um JWT (por exemplo, porque ele expirou), o SDK dispara um evento de JWT invalidado. Busque um novo token no seu backend e passe-o para updateUserJwt. As solicitações que precisam do token aguardam até que você o forneça. Você pode usar o mesmo endpoint para emitir um token que inclua o e-mail ou o SMS se o token de login original não os incluía.Adicione o listener na inicialização do aplicativo, antes de chamar login:
  • Android: adicione-o em Application.onCreate. O listener só recebe eventos disparados depois de ser adicionado e é chamado em uma thread em segundo plano.
  • iOS: o SDK mantém uma referência fraca ao listener, então mantenha uma referência forte a ele. Ele é chamado na thread principal, então busque o token de forma assíncrona. Se um evento foi disparado antes de você adicionar o listener, o SDK o entrega quando você adiciona o listener.
  • Web: adicione-o com OneSignal.User.addEventListener("userJwtInvalidated", listener) dentro de OneSignalDeferred.push, antes de chamar login. O listener só recebe eventos disparados depois de ser adicionado. O SDK chama cada listener de forma assíncrona, e um listener que lança uma exceção não impede os outros listeners.
Substitua fetchOneSignalJwt por uma chamada ao seu backend. Não assine JWTs no dispositivo.Com esse listener implementado, um token expirado é substituído automaticamente e a sessão continua sem forçar o usuário a fazer login novamente.
3

Ative o Token Identity Verification no painel

Em Settings > Keys & IDs, ative Token Identity Verification.
Chave Token Identity Verification ativada nas configurações do painel

Ativação do Token Identity Verification

Antes de ativá-la, confirme:
  • Nenhum cliente deste aplicativo usa um SDK multiplataforma. Consulte SDKs compatíveis.
  • A maioria dos seus usuários está em uma versão do aplicativo que passa um JWT para login. Versões antigas do aplicativo ainda instaladas nos dispositivos não conseguem enviar um JWT, então as solicitações delas também falham.
  • Seu servidor envia um JWT para as User REST APIs que ele chama.
A partir de então, o OneSignal rejeita qualquer chamada a login ou a uma REST API protegida que não inclua um JWT válido. Consulte O que muda quando a chave está ativada.

O que muda quando a chave está ativada \

  • Login: login exige um JWT válido cujo identity.external_id corresponda ao External ID.
  • Dispositivos desconectados: o SDK não cria usuários anônimos no OneSignal. Em uma nova instalação, o dispositivo não registra uma assinatura push até que o aplicativo chame login com um JWT válido, então ele não pode receber notificações push antes disso. Se você envia push para usuários antes de eles fazerem login, planeje isso antes de ativar a chave.
  • Logout: logout() desativa a assinatura push do dispositivo. Chamar login com um JWT a restaura. Consulte as perguntas frequentes.
  • E-mail e SMS: addEmail e addSms exigem um JWT que inclua o endereço na claim subscriptions. Consulte Adicionar assinaturas.
  • REST API: os endpoints de User e Subscription exigem Authorization: Bearer YOUR_ONESIGNAL_JWT. Consulte REST API.

Adicionar assinaturas \

Se o JWT de login já incluir o e-mail ou o número de telefone em subscriptions, login associa essas assinaturas ao usuário. Você não precisa de uma segunda chamada. No Android 5.11.0 e posteriores, login(external_id, profile) envia o e-mail e o número de telefone do perfil na solicitação de login. Inclua cada um desses endereços na claim subscriptions do JWT de login. Se o endereço ainda não estiver no JWT, emita um novo token que o inclua, chame updateUserJwt e depois chame addEmail ou addSms. Faça isso em todas as plataformas. addEmail / addSms sozinhos não bastam depois que o Token Identity Verification estiver ativado. fetchOneSignalJwtWithEmail e fetchOneSignalJwtWithSms são marcadores para a sua própria chamada ao backend que emite um JWT com a claim subscriptions.

REST API \

JWTs de verificação de identidade não são App API keys. Outros endpoints (por exemplo, Create message) continuam usando Authorization: Key YOUR_APP_API_KEY. Consulte Keys & IDs. Quando o Token Identity Verification está ativado, os endpoints de User e Subscription abaixo se autenticam com o JWT de identidade:
Emita esse JWT da mesma forma que para o login do SDK. O identity.external_id do token deve corresponder ao usuário sobre o qual a solicitação opera. Exemplo:

Solução de problemas \


Perguntas frequentes \

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

Não, mas ela é altamente recomendada para aplicativos em produção. Sem ela, qualquer cliente que conheça o External ID de um usuário pode se passar por esse usuário e modificar as assinaturas ou os dados dele.

O que é a chave “Identity Verification for email + external_id”? \

Página de configurações mostrando a chave legada Identity Verification

Chave legada Identity Verification em Keys & IDs

Essa chave é uma configuração legada e separada para os SDKs v3/v4 do OneSignal. Ela não é a verificação de identidade baseada em JWT desta página e não protege aplicativos no SDK v5. Para o SDK v5, use Generate New Keys na seção Identity Verification em Settings > Keys & IDs. Consulte Gerar chaves.

Quais SDKs são compatíveis com a verificação de identidade? \

O SDK nativo para Android 5.9.0+, o SDK nativo para iOS 5.8.0+ e o SDK Web 160900+. SDKs multiplataforma (React Native, Expo, Flutter, Unity, Cordova, Ionic, Capacitor e .NET MAUI) ainda não são compatíveis. Consulte SDKs compatíveis.

Meu aplicativo usa um SDK multiplataforma. Posso ativar a verificação de identidade? \

Ainda não. O painel permite ativar a chave, mas seus clientes não conseguem enviar um JWT, então os logins e as atualizações de assinaturas deles falham. Você pode gerar chaves e implementar a assinatura de JWTs no seu servidor agora e ativar a chave quando seu SDK for compatível.

Qual algoritmo o JWT usa? \

ES256 (ECDSA usando P-256 e SHA-256). Outros algoritmos são rejeitados.

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

O SDK dispara um evento de JWT invalidado. Implemente addUserJwtInvalidatedListener (consulte Adicionar o JWT ao seu aplicativo) para buscar um novo token e passá-lo para updateUserJwt. Na web, escute o evento userJwtInvalidated com OneSignal.User.addEventListener.

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

Somente depois de ativar o Token Identity Verification. A partir daí, os endpoints de User e Subscription exigem Authorization: Bearer YOUR_ONESIGNAL_JWT. Eles não aceitam a App API key para essas chamadas. Create message e outros endpoints que não são de usuário continuam usando Authorization: Key YOUR_APP_API_KEY.

O que acontece com a assinatura push no logout? \

Quando a verificação de identidade está ativada, logout() desativa a assinatura push. A assinatura continua associada a esse usuário. Chamar login com um JWT restaura o status anterior da assinatura. Você não precisa chamar optIn() novamente. No Android (Kotlin), logoutSuspend() é o equivalente não bloqueante de logout().

Usuários

External ID, usuários anônimos e identificados, e login/logout.

Keys & IDs

App ID, App API keys e onde ficam as chaves de verificação de identidade.

Referência do SDK mobile

login, logout, addEmail, addSms e métodos de assinatura.

Referência do SDK Web

login, updateUserJwt, o evento userJwtInvalidated e outros métodos do SDK Web.

Visão geral da REST API

Autenticação padrão com App API key para endpoints que não são protegidos por JWT.