> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Verificação de identidade
> Previna a falsificação de identidade de usuários exigindo JWTs gerados pelo servidor para verificar IDs de Usuário Externos, emails e assinaturas de SMS enviados ao OneSignal.
## 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](https://jwt.io/introduction), 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](#enable-token-identity-verification-in-the-dashboard)).
## Pré-requisitos
* Um aplicativo OneSignal existente com uma plataforma push configurada.
* Um aplicativo móvel integrado com um dos SDKs suportados:
* [OneSignal Android SDK 5.2.0+](https://github.com/OneSignal/OneSignal-Android-SDK/releases)
* [OneSignal iOS SDK 5.3.0+](https://github.com/OneSignal/OneSignal-iOS-SDK/releases)
Suporte a wrapper SDK (Flutter, React Native, Unity, etc.) em breve.
## Configuração
Faça login em sua conta OneSignal e navegue até **Settings > Keys & IDs > Identity Verification**.
Clique em **Generate New Keys** para criar um novo par de chaves.
Baixe o arquivo PEM ou copie a chave privada, certificando-se de armazenar a chave privada com segurança.
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.
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:
Seu OneSignal App ID
A data de expiração do token.
O alias do usuário.
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](https://jwt.io/libraries) para fazer isso.
Exemplo usando [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken):
```typescript Node.js theme={null}
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:
```typescript Node.js theme={null}
node server.js
```
```bash cURL theme={null}
curl http://localhost:3000/generate-jwt/your-external-id
```
Você deve receber uma resposta como:
```json theme={null}
{
"jwt": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
Cole o valor do JWT em [jwt.io](https://jwt.io) e confirme que o payload decodificado contém os seguintes parâmetros:
```json theme={null}
{
"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
```typescript Node.js theme={null}
const subscriptions = [
{
"type": "Email",
"token": "[email protected]"
},
{
"type": "SMS",
"token": "+12345678"
}
]
const onesignalJWT = signOneSignalJWT('EXTERNAL_ID', subscriptions)
```
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:
```java java theme={null}
String externalId = "YOUR_EXTERNAL_ID";
String onesignalJWT = "YOUR_JWT_TOKEN";
OneSignal.login(externalId, onesignalJWT);
```
```kotlin kotlin theme={null}
val externalId = "YOUR_EXTERNAL_ID"
val onesignalJWT = "YOUR_JWT_TOKEN"
OneSignal.login(externalId, onesignalJWT)
```
```swift Swift theme={null}
let externalId = "YOUR_EXTERNAL_ID"
let onesignalJWT = "YOUR_JWT_TOKEN"
OneSignal.login(externalId: externalId, token: onesignalJWT)
```
```c objective-c theme={null}
NSString* externalId = @"YOUR_EXTERNAL_ID";
NSString* onesignalJWT = @"YOUR_JWT_TOKEN";
[OneSignal login:externalId withToken:onesignalJWT];
```
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:
```java java theme={null}
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);
});
```
```kotlin kotlin theme={null}
OneSignal.addUserJwtInvalidatedListener(
object : IUserJwtInvalidatedListener {
override fun onUserJwtInvalidated(event: UserJwtInvalidatedEvent) {
val externalId = event.externalId
val onesignalJWT = ""
updateUserJwt(externalId, onesignalJWT)
}
},
)
```
```swift Swift theme={null}
class AppDelegate: UIResponder, UIApplicationDelegate, OSUserJwtInvalidatedListener {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
// Set self to listen for JWT invalidated events
OneSignal.addUserJwtInvalidatedListener(self)
// Remove the JWT listener as needed by calling:
// `OneSignal.removeUserJwtInvalidatedListener(self)`
}
// Required to conform to `OSUserJwtInvalidatedListener` protocol
func onUserJwtInvalidated(event: OneSignalUser.OSUserJwtInvalidatedEvent) {
// Get the expired user's External ID
let externalId = event.externalId
// Fetch a new JWT from your backend for the user
let onesignalJWT = "yourUpdatedToken"
// Provide the new JWT to the SDK
OneSignal.updateUserJwt(externalId: externalId, token: onesignalJWT)
}
}
```
```c objective-c theme={null}
@interface MyListener: NSObject
@end
@implementation MyListener
- (void)onUserJwtInvalidatedWithEvent:(OSUserJwtInvalidatedEvent * _Nonnull)event {
// Get the expired user's External ID
NSString *externalId = event.externalId;
// Fetch a new JWT from your backend for the user
NSString *onesignalJWT = @"yourUpdatedToken";
// Provide the new JWT to the SDK
[OneSignal updateUserJwt:externalId withToken:onesignalJWT];
}
// Add or remove your User Jwt Invalidated Listener
[OneSignal addUserJwtInvalidatedListener:myListener];
[OneSignal removeUserJwtInvalidatedListener:myListener];
```
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.
Em **Settings > Keys & IDs**, alterne **Token Identity Verification** para habilitar.
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ê.
```java java theme={null}
OneSignal.getUser().addEmail(emailAddress);
```
```kotlin kotlin theme={null}
OneSignal.getUser().addEmail(emailAddress)
```
```swift Swift theme={null}
// If you have not already included it in your JWT token, update the JWT with the email
let onesignalJWT = "newTokenThatContainsTheEmailToAdd"
OneSignal.updateUserJwt(externalId: externalId, token: onesignalJWT)
// Add the email
OneSignal.User.addEmail(emailAddress)
```
```c objective-c theme={null}
// If you have not already included it in your JWT token, update the JWT with the email
NSString *onesignalJWT = @"newTokenThatContainsTheEmailToAdd";
[OneSignal updateUserJwt:externalId withToken:onesignalJWT];
// Add the email
[OneSignal.User addEmail:emailAddress];
```
```java java theme={null}
OneSignal.getUser().addSms(smsNumber);
```
```kotlin kotlin theme={null}
OneSignal.getUser().addSms(smsNumber)
```
```swift Swift theme={null}
// If you have not already included it in your JWT token, update the JWT with the sms
let onesignalJWT = "newTokenThatContainsTheSmsToAdd"
OneSignal.updateUserJwt(externalId: externalId, token: onesignalJWT)
// Add the sms number
OneSignal.User.addSms(smsNumber)
```
```c objective-c theme={null}
// If you have not already included it in your JWT token, update the JWT with the sms
NSString *onesignalJWT = @"newTokenThatContainsTheSmsToAdd";
[OneSignal updateUserJwt:externalId withToken:onesignalJWT];
// Add the sms number
[OneSignal.User addSms:smsNumber];
```
***
## 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 `.
* [Create user](/reference/create-user)
* [View user](/reference/view-user)
* [Update user](/reference/update-user)
* [Delete user](/reference/delete-user)
* [View user identity](/reference/fetch-aliases)
* [Create alias](/reference/create-alias)
* [Delete alias](/reference/delete-alias)
* [Create subscription](/reference/create-subscription)
* [Update subscription](/reference/update-subscription)
***
## 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](#handle-jwt-lifecycle-events)) 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](#rest-api) 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.
***