Key management

• Push API configuration

  MPS provides REST APIs for push messaging. Before calling an API, sign the request with the RSA algorithm and configure the key in the Push API configuration area on the Key management page. MPS uses this key to verify the caller's identity.

• Callback API configuration

  To receive message delivery receipts, configure the callback REST API address in the Callback API configuration area on the Key management page. Obtain the public key to verify callback signatures and confirm that callbacks originate from MPS.

Configure the push API interface

Prerequisites

Before you configure the push API interface, generate a 2048-bit RSA public key.

• To generate an RSA public key:

  1. Download and install the OpenSSL tool (version 1.1.1 or later) from the official OpenSSL website.

  2. Open the OpenSSL tool and run the following command to generate a 2048 bit RSA private key.

     openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048

  3. Generate an RSA public key from the RSA private key.

     openssl rsa -pubout -in private_key.pem -out public_key.pem

• The signature algorithm rules are as follows:

  • Use the SHA-256 signature algorithm.

  • Convert the signature result to a base64 string.

  • In the base64 string, replace + with - and / with _ to obtain the final signature.

Procedure

To configure the push interface:

1. Log on to the mPaaS console, select the target application, and then in the navigation pane on the left, choose Mobile Push Service > Settings.

2. On the page that appears, click the Key management tab.

3. In the upper-right corner of the Push API configuration area, click Configure. The configuration fields appear.

   Field	Required	Description
   Status	Yes	The callable status of the push interface. Turn on the switch to enable MPS API calls. Turn off the switch to disable them.
   Encryption method	No	Only the RSA algorithm is available.
   RSA public key	No	Enter the 2048-bit public key. MPS uses this public key to verify the signed request parameters and authenticate the caller.

   Important

   Ensure the public key is entered correctly without spaces. Otherwise, API calls fail. For more information, see API reference.

4. Click OK to save the configuration.

Configure the push callback interface

1. On the Key management page, in the upper-right corner of the Callback API configuration area, click Configure. The configuration fields appear.

   Field	Required	Description
   Status	Yes	The callback status. Turn on the switch to have MPS send delivery receipts to your server. Turn off the switch to stop sending receipts.
   Callback API URL	Yes	The callback URL. This must be a publicly accessible HTTP address. MPS signs the POST request body with a private key and sends the signature as the sign parameter in the callback.
   Encryption method	No	MPS uses the RSA algorithm to sign the POST request body.
   RSA public key	No	This field is automatically populated and cannot be modified. After your server receives the POST request body and the sign parameter, use the public key to verify that the request originates from MPS and that the data was not tampered with during transmission. For more information, see Server-side API.

2. Click OK to save the configuration.

   Callback timing varies depending on the push channel.

   Note

   • Third-party channels (such as FCM, APNs, Xiaomi, Huawei, OPPO, and vivo): A callback is initiated when the call to the third-party service is successful.

   • Self-built channel: A callback is initiated when the message is pushed successfully.

Code sample

/**
 * Alipay.com Inc. Copyright (c) 2004-2020 All Rights Reserved.
 */
package com.callback.demo.callbackdemo;

import com.callback.demo.callbackdemo.util.SignUtil;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;

/**
 *
 * @author yqj
 * @version $Id: PushCallbackController.java, v 0.1 March 22, 2020 11:20 AM yqj Exp $
 */
@Controller
public class PushCallbackController {

    /**
     * Copy the RSA public key from the Callback API configuration in the console
     */
    private static final String pubKey = "";


    @RequestMapping(value = "/push/callback" ,method = RequestMethod.POST)
    public void callback(@RequestBody String callbackJson, @RequestParam String sign) {
        System.out.println(sign);
        // Verify the signature
        sign = sign.replace('/', '_').replace('+', '-');
        if(!SignUtil.check(callbackJson,sign,pubKey,"UTF-8")){
            System.out.println("Signature verification failed");
            return;
        }
        System.out.println("Signature verification successful");
        // JSON message body
        System.out.println(callbackJson);

    }

}

callbackJson is the message request body in JSON format. Example:

{
    "extInfo":{
        "adToken":"da64bc9d7d448684ebaeecfec473f612c57579008343a88d4dbdd145dad20e84",
        "osType":"ios"
    },
    "msgId":"console_1584853300103",
    "pushSuccess":true,
    "statusCode":"2",
    "statusDesc":"Acked",
    "targetId":"da64bc9d7d448684ebaeecfec473f612c57579008343a88d4dbdd145dad20e84"
}

The following table describes the callbackJson fields.

Field	Description
msgId	The business message ID.
pushSuccess	Whether the push was successful.
statusCode	The message status code.
statusDesc	The description of the message status code.
targetId	The target ID.