Saltar al contenido principal

Descripción general

OneSignal ofrece una función de seguridad mejorada llamada Verificación de Identidad para ayudar a prevenir la suplantación de usuarios. Esta función utiliza JSON Web Tokens, o JWTs, generados de forma segura en tu servidor. Para verificar la información de suscripción, estos tokens se pasan a tu aplicación y a la API de OneSignal. Habilita la Verificación de Identidad para proteger:
  • Iniciar sesión de usuarios
  • Agregar suscripciones de correo electrónico
  • Agregar suscripciones de SMS
  • Modificar identidades de usuarios
La Verificación de Identidad está actualmente en beta. Contacta a support@onesignal.com para habilitarla en tu cuenta. Una vez que el soporte la habilite, la activas en tu panel (ver Paso 5).

Requisitos previos

Soporte para wrapper SDK (Flutter, React Native, Unity, etc.) próximamente.

Configuración

1

Generar nuevas claves

Inicia sesión en tu cuenta de OneSignal y navega a Configuración > Claves e IDs > Verificación de Identidad.
Settings page showing Keys and IDs with Identity Verification section
Haz clic en Generar Nuevas Claves para crear un nuevo par de claves.
Generate New Keys button in the Identity Verification section
Descarga el archivo PEM o copia la clave privada, asegurándote de almacenar la clave privada de forma segura.
Identity Verification key pair with private key and PEM download
Siempre almacena tus claves privadas en un entorno seguro, como un sistema de gestión de claves. Nunca expongas claves privadas en código del lado del cliente, repositorios públicos o registros.
2

Generar JWT de verificación en tu backend

La verificación de identidad requiere autenticar al usuario final con tu servidor de autenticación antes de iniciar sesión en OneSignal. Cuando el usuario final se autentica con tu backend, genera el token e inclúyelo en la respuesta de autenticación al dispositivo. Si tu aplicación no ejecuta un servidor backend, considera configurar un servidor ligero para verificar usuarios y generar estos tokens.

Carga útil JWT

El JWT puede tener las siguientes propiedades:
iss
requerido
Tu ID de Aplicación de OneSignal
exp
requerido
La fecha de expiración del token.
identity
requerido
El alias del usuario.
subscriptions
Requerido solo cuando se agregan suscripciones de Correo electrónico y SMS a un usuario.

Firmar el JWT

Firma el JWT usando el algoritmo ES256. Asegúrate de que tu backend esté configurado para usar este método de firma para evitar problemas de verificación al enviar el JWT a OneSignal. Recomendamos una Biblioteca JWT para hacer esto.Ejemplo 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');

La clave privada está en el archivo del paso anterior que descargamos del Panel.

Verificar tu JWT

Antes de integrar con el SDK, verifica que tu JWT se está generando correctamente iniciando tu servidor y llamando al endpoint:
  node server.js
  curl http://localhost:3000/generate-jwt/your-external-id
Deberías recibir una respuesta como:
{
  "jwt": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Pega el valor del JWT en jwt.io y confirma que el payload decodificado contiene los siguientes parámetros:
{
  "iss": "your-onesignal-app-id",
  "exp": 1234567890,
  "identity": {
    "external_id": "your-external-id"
  }
}
Confirma lo siguiente antes de pasar al siguiente paso:
  • iss coincide con tu ID de Aplicación de OneSignal en Configuración > Claves e IDs
  • identity.external_id está presente y coincide con el valor que pasarás a OneSignal.login()
  • exp es una marca de tiempo futura — un token expirado será rechazado por OneSignal

Incluir suscripciones

Idealmente, los detalles de suscripción, como correo electrónico o número de teléfono, se incluyen en la carga útil JWT al iniciar sesión de un usuario. Si estos detalles no están disponibles por adelantado, tu servidor de verificación debe proporcionar un endpoint para generar tokens dinámicamente a medida que la información de suscripción esté disponible.Ejemplo: Generar JWT para agregar suscripciones
const subscriptions = [
  {
      "type": "Email",
      "token": "[email protected]"
  },
  {
      "type": "SMS",
      "token": "+12345678"
  }
]
const onesignalJWT = signOneSignalJWT('EXTERNAL_ID', subscriptions)
3

Pasar JWT al método `login`

Una vez que tu backend genera el JWT, llama al método login con él. Este token asegura que la identidad del usuario sea verificada antes de que se puedan hacer cambios, como agregar una suscripción de correo electrónico o SMS.Ejemplo de inicio de sesión:
String externalId = "YOUR_EXTERNAL_ID";
String onesignalJWT = "YOUR_JWT_TOKEN";

OneSignal.login(externalId, onesignalJWT);
4

Manejar eventos del ciclo de vida del JWT

Necesitarás implementar un endpoint dedicado en tu backend para manejar escenarios como la invalidación de tokens. Este endpoint debe proporcionar un JWT actualizado cuando OneSignal solicite una actualización.Ejemplo de manejo de invalidación de token y actualización del 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);
});
Esto asegura que cuando el JWT de un usuario se invalide, se pueda obtener uno nuevo de tu backend y pasarlo a OneSignal. También puedes usar esta función para generar un token con un correo electrónico y número de teléfono, permitiéndote gestionar suscripciones de correo electrónico y SMS si el token creado durante la autenticación no los contiene.
5

Habilitar verificación de identidad de token en el panel

Desde Configuración > Claves e IDs, activa Verificación de Identidad de Token para habilitar.
Token Identity Verification toggle enabled in dashboard settings
Una vez habilitado, tu aplicación debe enviar JWTs de OneSignal para verificar la autenticidad de la suscripción. Además, tu aplicación debe llamar al método login usando un JWT generado por tu servidor de tokens de verificación de identidad.

Agregar suscripciones

No necesitas tomar pasos adicionales para agregar suscripciones desde tu aplicación móvil; llamar al método de inicio de sesión maneja esto automáticamente por ti.
OneSignal.getUser().addEmail(emailAddress);

REST API

Cuando la Verificación de Identidad de Token está habilitada, todas las solicitudes a las siguientes APIs deben incluir un JWT generado por el servidor en los encabezados como un token bearer, ej., Authorization: Bearer <JWT>.

Preguntas frecuentes

¿Es obligatoria la verificación de identidad?

No, pero se recomienda ampliamente. Sin ella, cualquier cliente que conozca el ID de Usuario Externo de un usuario puede hacerse pasar por ese usuario y modificar sus suscripciones o datos.

¿Qué ocurre si el JWT expira durante una sesión?

El SDK activa un evento de invalidación de JWT. Implementa addUserJwtInvalidatedListener (ver Manejar eventos del ciclo de vida del JWT) para obtener un token actualizado de tu backend y pasarlo a updateUserJwt.

¿Qué SDKs admiten la verificación de identidad?

Actualmente, el SDK nativo de Android (5.2.0+) y el SDK de iOS (5.3.0+). El soporte para SDK wrapper (Flutter, React Native, Unity, etc.) llegará próximamente.

¿Necesito verificación de identidad para la API REST?

Cuando la Verificación de Identidad de Token está habilitada, todas las solicitudes a las APIs admitidas deben incluir un JWT generado por el servidor como token bearer en el encabezado Authorization. El JWT se genera de la misma manera que para el uso del SDK.

¿Qué algoritmo usa el JWT?

La Verificación de Identidad requiere JWTs firmados con el algoritmo ES256 (ECDSA usando P-256 y SHA-256). Otros algoritmos serán rechazados.