If the callback method of HTTP requests is used, you can add authentication parameters to the HTTP request headers. This way, the server that receives callback messages can authenticate the signature to prevent illegal or invalid requests. This topic describes the authentication parameters, signature calculation, authentication rules of the server, and authentication key switching.
Usage notes
You can choose to enable or disable callback authentication based on your business requirements. We recommend that you enable callback authentication. The original features are not affected after you enable or disable callback authentication. If callback authentication is enabled, callback requests carry all authentication-related information. The server that receives callback messages uses the information to authenticate callback requests. This helps filter out illegal requests and enhances system security.
Authentication parameters
If the callback method of HTTP requests is used, you can add the following authentication parameters to the HTTP request headers.
Parameter | Description |
X-ICE-TIMESTAMP | The time when the HTTP request was initiated. The value is a UNIX timestamp. |
X-ICE-SIGNATURE | The signature string, which is a 32-character MD5 value. For more information about how to calculate the value of this parameter, see the "Signature calculation" section of this topic. |
Signature calculation
The value of the X-ICE-SIGNATURE parameter is calculated based on the parameters described in the following table.
Parameter | Description | Example |
Callback URL | The callback URL of the HTTP request. | https://www.example.com/your/callback |
X-ICE-TIMESTAMP | The time when the HTTP request was initiated. The value is a UNIX timestamp. | 1519375990 |
Authentication Key | The signature key that is preset by the user. The key can be up to 32 characters in length and must contain uppercase letters, lowercase letters, and digits. | Test123 |
Concatenate the preceding three parameters by separating them with vertical bars (|). Then, calculate the MD5 hash value of the concatenated string. Sample code:
MD5Content = Callback URL|X-ICE-TIMESTAMP|Authentication Key
X-ICE-SIGNATURE = md5sum(MD5Content)Sample code for calculating the value of the X-ICE-SIGNATURE parameter:
X-ICE-SIGNATURE = md5sum(https://www.example.com/your/callback|1519375990|Test123) = c72b60894140fa98920f1279219b****Authentication rules of the server that receives callback messages
The server that receives callback messages concatenates the callback URL, X-ICE-TIMESTAMP, and authentication key into a string and calculates the MD5 hash value of the string. Then, the server compares the MD5 hash value with the value of the X-ICE-SIGNATURE parameter. If the two values are different, the request is considered invalid.
The server that receives callback messages obtains the current time and calculates the difference between the current time and the time specified by the X-ICE-TIMESTAMP parameter in the callback request. If the time difference exceeds the value set by the server, such as 5 minutes, the request is considered invalid.
Authentication key switching
If you need to switch the authentication key, the server that receives callback messages must support authentication within a period of time based on both the old and new keys. This ensures that the callback service is not affected. In this case, the server must implement authentication based on both the old and new keys. We recommend that you perform the following steps to switch the keys:
Define a new authentication key.
Update the server that receives callback messages to support authentication based on both the old and new keys.
Configure the new authentication key for callback authentication in the IMS console.
After a period of time, remove the support for the old key from the server that receives callback messages.