LATEST VERSION: 1.9 - RELEASE NOTES
Push Notification Services v1.9

Registering with a Custom User ID

Specifying a Custom User ID

By default, push expects the custom user ID field during a device registration to be specified using a JSON Web Token, signed using the application’s shared secret.

The application’s shared secret can be found on the push dashboard, under the configuration tab.

Security Guidance

Pivotal recommends that you implement signing the custom user ID on the backend.

Avoid storing the shared secret in a mobile application. If the shared secret is compromised in a mobile application, attackers could masquerade as existing users.

Signed Custom User ID Format

Push API expects the custom_user_id to be sent as a signed JSON Web Token (JWT). This is to validate that the registration request came from a trusted application.

The token should be signed with HMAC-SHA256, and the content should be as follows:

Header

{
  "alg": "HS256"
}

Payload

{
  "custom_user_id": "<YOUR CUSTOM USER ID>"
}

Signature

signature = HMAC-SHA256(sharedSecret, unsignedToken)
unsignedToken = encodeBase64(header) + '.' + encodeBase64(payload)
sharedSecret = Application Shared Secret

Final Token

token=encodeBase64(header) + '.' + encodeBase64(payload) + '.' + encodeBase64(signature)

The final token is what should be sent as the value of the custom_user_id field in the registration call.

{
  ...
  "custom_user_id": token
  ...
}

For more information on JWT, see https://en.wikipedia.org/wiki/JSON_Web_Token

For an example on how to generate the Custom User ID JWT in Java check out https://github.com/cfmobile/push-tools

Unsigned Custom User ID Format

The requirement to sign custom user IDs can be disabled by setting the push_security_verifyCustomUserId environment variable to false for the push-api servce.

Pivotal highly recommends that you keep custom user ID signing enabled.

If signed custom user IDs are disabled, then the registration call should just contain the custom user ID as plain text

{
  ...
  "custom_user_id": "<YOUR CUSTOM USER ID>"
  ...
}
Create a pull request or raise an issue on the source for this page in GitHub