v3-4 SDK Identity Verification
Security feature to authenticate your external user ids and emails sent to OneSignal.
The methods below require the OneSignal SDK versions 3 & 4.
It is recommended to upgrade to our latest version 5 SDKs for User Model APIs.
See Update to User Model for migration steps.
OneSignal supports a higher security method known as Identity Verification. This helps prevent users from impersonating one another by generating a user-specific token on your server, if you have one.
Enabling Identity Verification applies to:
- Adding Email and SMS records into OneSignal AND associated tags.
- Setting
external_user_id
for any record across all channels (Push, Email, SMS)
It can be enabled in the Dashboard > Settings > Keys & IDs
Once enabled or disabled, this will take up to 10 minutes to process.
We highly recommend enabling identity verification for apps and websites that use setting external_user_ids
and/or Email Messaging. For apps and websites that are ‘backendless’ and do not run their own servers, we suggest either creating a minimal server that just verifies users, saving the OneSignal User ID records to your database, or avoid sending sensitive information in user tags and notifications.
Auth Hash Generation
Auth hashes are expected to be a HMAC on a SHA-256 of the OneSignal REST API Key and the <protected_field_value>
.
Example Auth Hash Generation Code
When identity verification is enabled, OneSignal will look for a SHA-256 hash of a user’s email address or external user identifier from your server. See the following code examples for how to generate these hashes on your server:
SDK setEmail
Method
Your backend can generate an email authentication token and send it to your app to include in the setEmail
method.
SDK setSMSNumber
Method
Your backend can generate an SMS authentication token and send it to your app to include in the setSMSNumber
method.
SDK setExternalUserId
Method
Your backend can generate an email authentication token and send it to your app to include in the setExternalUserId
method.
Updating Devices with REST API
If you enabled Identity Verification and call the Add a device or Edit device endpoint (api/v1/players
), the request must contain the external_user_id_auth_hash
or identifier_auth_hash
parameters.
If you are adding or updating the external_user_id
on a non-email device (device_type
!= 11
), you must use the external_user_id_auth_hash
parameter.
If you are adding or updating the email (identifier
parameter && device_type
= 11
), then any field being updated will need the identifier_auth_hash
(or email_auth_hash
for backwards compatibility) value.
Removing External User ID
To remove an external_user_id
from a device record with Identity Verification enabled, you can set it to an empty string with the auth hash based on the existing external_user_id
value before removal.