Identity verification
Authenticate External User IDs, SMS, and emails sent to OneSignal.
Overview
OneSignal offers an enhanced security feature called Identity Verification to help prevent user impersonation. This feature utilizes JSON Web Tokens – or JWTs, securely generated on your server. To verify subscription information, these tokens are passed to your app and OneSignal’s API.
We recommend enabling Identity Verification to:
- Log in users
- Add email subscriptions
- Add SMS subscriptions
- Modify user identities
support@onesignal.com
to get this enabled.Prerequisites
-
An existing OneSignal app with a configured push platform.
-
A mobile app integrated with one of the supported SDKS:
Setup
Generate new keys
Log in to your OneSignal account and navigate to Settings > Keys & IDs > Identity Verification.
Identity Verification configuration
Click Generate New Keys to create a new key pair.
Creating new key pair
Download the PEM file or copy the private key, making sure to store the private key securely.
Identity Verification key pair
Always store your private keys in a secure environment, such as a key management system. Never expose private keys in
Generate verification JWT on your backend
Identity verification requires authenticating the end-user with your authentication server before logging them into OneSignal. When the end-user authenticates with your backend, generate the token and include it in the auth response to the device. If your app doesn’t run a backend server, consider setting up a lightweight server to verify users and generate these tokens.
JWT payload
The JWT can have the following properties:
Your OneSignal App ID
The token expiration date.
The user’s alias.
Required only when adding Email and SMS subscriptions to a user.
Signing the JWT
Sign the JWT using the ES256 algorithm. Ensure your backend is configured to use this signing method to avoid verification issues when sending the JWT to OneSignal. We recommend a JWT Library to do this.
Example using jsonwebtoken:
The private key is in the previous step’s file we downloaded from the Dashboard.
Including subscriptions
Ideally, subscription details, such as email or phone number, get included in the JWT payload when logging a user in. If these details aren’t available upfront, your verification server must provide an endpoint to generate tokens dynamically as subscription information becomes available.
Example: Generating JWT to add subscriptions
Pass JWT to the `login` method
Once your backend generates the JWT, call the login
method with it. This token ensures the user’s identity is verified before any changes, such as adding an email or SMS subscription, can be made.
Example of logging in:
Handle JWT lifecycle events
You’ll need to implement a dedicated endpoint on your backend to handle scenarios like token invalidation. This endpoint should provide a refreshed JWT when OneSignal requests an update.
Example of handling token invalidation and refreshing the JWT:
This ensures that when a user’s JWT is invalidated, a new one can be fetched from your backend and passed to OneSignal. You can also use this function to generate a token with an email and phone number, allowing you to manage email and SMS subscriptions if the token created during authentication does not contain them.
Enable token identity verification in the dashboard
From Settings > Keys & IDs, toggle Token Identity Verification to enable.
Enabling Token Identity Verification
Once enabled, your app must send OneSignal JWTs to verify subscription authenticity. Additionally, your app is required to call the login
method using a JWT generated by your identity verification token server.
Adding subscriptions
You don’t need to take extra steps to add subscriptions from your mobile app; calling the login method automatically handles this for you.
REST API
When Token Identity Verification is enabled, all requests to the following APIs must include a server-generated JWT in the headers as a bearer token, e.g., Authorization: Bearer <JWT>
.
- Create user
- View user
- Update user
- Delete user
- View user identity
- Create alias
- Delete alias
- Create subscription
- Update subscription