Configure the MID Web Server extension

The MID Web Server extension enables external clients to push metric data to the MID Server. This extension is used to listen for raw metric data and it provides options for authentication and data security. The raw data that is collected is transmitted to the instance.

Before you begin

Deploy and start a MID Server.

The Enable REST Listener option must be selected in the ITOA MetricExtension. For more information, see Configure the Operational Metric extension.

If the Secure Connection option is going to be selected, first obtain a server certificate. For more information, see Setup certificate for secure connection.

Role required: evt_mgmt_admin

About this task

The MID Web Server extension runs for as long as it is enabled. The extension starts a web server on the MID Server that can serve web requests from external systems. The

Raw data can be pushed to the extension from a client or using customized script.

The Web Server extension configuration includes these important settings:
  • Authentication type, which can be set to the more advanced option - Keybased.
  • Secure Connection, which lets you choose whether incoming and outgoing data is secured when transmitted. If you choose the more advanced secured option, it requires that you obtain a certificate from a well-known certificate authority, and then provide the Keystore Certificate Alias and the Keystore Password.

Procedure

  1. Navigate to MID Server > Extensions > MID Web Server.
  2. In the MID Web Server Contexts list, click New.
  3. Fill in the fields, as appropriate.
    Field Description
    Name A unique name for this MID Web Server extension for easy identification.
    Short description Enter a brief, meaningful description of this extension.
    Extension Specify MID Web Server.
    Status This field is auto-populated with the status of the extension. The field is blank until the extension is started. After issuing a command to the extension, one of the following values is displayed:
    • Started: The extension is running.
    • Stopped: The extension is not running.
    • Offline: The MID Server is down.
    • Error: The extension failed with an error (the error message is displayed in Error Message).
    • Warning: A run-time exception has occurred. The extension continues to work.
    HTTP/HTTPS Port Port number on which you want to listen to incoming requests.
    Authentication Type Select one of the following:

    Keybased

    • Create an authentication token that is sent with each request.
    • Send this authentication token in the request header Authorization.
    To create an authentication token:
    1. The user must construct a string using defined elements of the HTTP/HTTPS request.
    2. Create a Hash Message Authentication Code (HMAC) of the string, that is, sign the string generated in previous step with the auto-generated secret key. The key is unique per context. See the example.
    Note: A valid timestamp (using the HTTP Date header) is required for the authenticated request. In addition, the timestamp must be within 15 minutes of the time on the MID Server.

    Basic

    • The user must provide a username and password. The same username and password must be provided for every request.
    • On the instance, the password is stored encrypted and it is sent also to the MID Server encrypted.
    • In the MID Server, the password is saved in memory.
    • When the request is received, the password is decrypted and matched with the password provided in the request.
    Secret Key [Read-Only] The value that is generated when keybased authentication is selected for the Authentication Type field.
    Error Message Message describing any error that causes a command, such as Start or Stop, to fail. This field only appears when the value in the Status field is Error.
    Execute on Location for running this extension. The available options are Specific MID Server or Specific MID Server Cluster.
    MID Server Depending on your selection in Execute on, the name of the designated MID Server, or MID Server cluster respectively:
    • If you selected Specific MID Server, the name of the designated MID Server.
    • If you selected Specific MID Server Cluster, the name of the designated MID Server cluster.
    If you selected the MID Server cluster option, an algorithm determines which server in the cluster runs the extension.
    Executing on [Read-Only] The name of the MID Server on which the extension is running. This field shows the name of the MID Server even if the MID Server is down. If the user stops the extension, this field is empty.
  4. Select Secure Connection to provide extra protection, if required. When selected, enter the values for these fields:
    1. In the Keystore Certificate Alias field, enter the name of the keystore certificate.
    2. In the Keystore Password field, enter the keystore password.
  5. Click Save to save the Operational Metric data.
  6. Under Related Links click Start to start the extension.
    Table 1. Commands available in the MID Web Server extension
    Related Link Description
    Start Starts the web server if it is currently not running.
    Stop Stops the web server. No action is taken if the extension is not running.
    Restart Stops, then starts the web server.
    Test The test is not relevant to Operational Metrics. Parameters are not tested or validated when Test is run.
    Update parameters Stops and then starts the web server with new parameters. If none of the parameters were modified, no update is made.

Example

Example describing how to create an authentication token to be sent with each request.

Method: Create a token by constructing a string using defined elements of the HTTP/HTTPS request. Then create an HMAC(Hash Message Authentication Code) of the string by signing the generated string with the auto-generated secret key that is displayed in the Secret Key. This key is unique per context. Send this authentication token in the request header Authorization.

Data for the example:

Table 2. Keybased authentication data
Item Value
Path to a web service API for sending raw data https://<instance>/api/mid/sa/metrics For example: https://mid1.service-now.com/api/mid/sa/metrics
Request type POST
Date format
yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
For example: 2016-06-08T20:54:58.917Z
Content-Type application/json

Use the following request elements to generate the required string: HTTP-Verb, Content-Type, Date, and request path. Specify these elements and place them in the following order:

  • HTTP-Verb + "\n" +
  • Content-Type + "\n" +
  • Date + "\n" +
  • Request-Path

For the above example, the request string is:

POST\napplication/json\n2016-06-08T20:54:58.917Z\n/api/mid/sa/metrics

For the time stamp requirement, a valid time stamp that uses HTTP date header is required for authenticating the request. Ensure that the timestamp is within 15 minutes of the MID Server.

Example, using Java, that describes how to generate HMAC of the string that uses defined elements of the HTTP/HTTPS request.

package sample;

import com.glide.util;
import java.security.SignatureException;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class AuthUtil {
	
private static final String HMAC_SHA1_ALGORITHM = "HmacSHA1";

/***
 * Generates base64-encode the HMAC(Hash Message Authentication Code) of input data
 * 
 * @param data
 * @param key
 * @return
 * @throws java.security.SignatureException
 */
public static String signData(String data, String key) throws java.security.SignatureException {
	String result;
	try {
		// get an hmac_sha1 key from the raw key bytes
		SecretKeySpec signingKey = new SecretKeySpec(key.getBytes(), HMAC_SHA1_ALGORITHM);

		// create hmac_sha1 Mac instance and initialize with the signing key
		Mac = Mac.getInstance(HMAC_SHA1_ALGORITHM);
		mac.init(signingKey);

		// compute the hmac on input data bytes
		byte[] rawHmac = mac.doFinal(data.getBytes("UTF-8"));

		// base64-encode the hmac
		result = Base64.encode(rawHmac);

	} catch (Exception e) {
		throw new SignatureException("Failed to generate HMAC : " + e.getMessage());
	}
	return result;
}
}