This section provides details about the authentication mechanism used for the Rhapsody REST API. It includes examples of how this API can be called, in this case using the cURL command line application (available on most *nix installations by default, and can be downloaded for Windows®).

Basic HTTP Authentication

The REST APIs perform authentication using basic HTTP authentication over an HTTPS connection. Though basic HTTP authentication effectively sends the plain-text password, the HTTPS connection ensures it is not visible to any observing third party. Basic HTTP authentication using cURL is performed as follows:

curl -v -k --basic -u administrator:rhapsody -H "Accept: application/json" https://localhost:8444/api/alerts/active
  • -v – verbose mode.
  • -k – turns off SSL server authentication.
  • --basic – enables basic HTTP authentication.
  • -u: administrator:rhapsody – logs in using a username administrator and a password rhapsody.
  • -H "Accept: application/json" – requests the REST web service to return the response data in JSON format (rather than HTML which is the default). The response to this particular request is JSON data containing the active alerts in the Rhapsody engine.

HTTPS Server Authentication

Basic HTTP authentication uses HTTPS to make the connection, but explicitly disables server authentication. Even though the connection is encrypted, it is vulnerable to a man-in-the-middle attack as the request does not verify that it is connected to the server it thinks that it is connected to. The -k parameter tells cURL to disable this authentication. While this is is acceptable for a testing environment, but is obviously not ideal for a production scenario where it is desirable to guarantee that a man-in-the-middle attack is not possible. Removing the -k parameter, however, causes the cURL command to fail since it does not trust the server it is connecting to.

While many of the REST APIs can be called over both HTTP and HTTPS, it should be noted that standard HTTP is not secure and therefore should not be used in most cases. It is subject to various forms of attacks, including but not limited to eavesdropping, man-in-the-middle and replay attacks, which will compromise the security of the connection. It is instead recommend that standard HTTP be disabled and the Management Console and REST API accessed solely using HTTPS. See  Using a User-defined Certificate for the HTTPS Mode  for how to configure the HTTPS certificate and enable or disable the HTTP port.

To allow cURL to connect to the Rhapsody REST API over HTTPS with server authentication, do the following:

  1. Download the SSL certificate from the Rhapsody server, and store it on the disk in Privacy Enhanced Mail (PEM) format.
  2. Provide the SSL certificate to cURL when it is run.
  3. Ensure that the URL provided to cURL contains the actual hostname of the server. For example, do not use localhost.

Download the SSL Certificate

To retrieve the SSL certificate:

  1. Start the Rhapsody HTTPS Management Console. By default the URL is https://<enginename>:8444/rhapsody. This generates SSL certificate errors unless the certificate has previously been explicitly trusted (or a CA issued certificate has been obtained and installed), but does provide a way to open and then download the certificate.
  2. If using IE, continue past the SSL errors, then click the Certificate Error icon in the address bar and select View Certificates.
    If using Chrome, click the Security icon at the start of the address bar and then the Certificate Information link.
    This shows the SSL certificate in the standard Windows® certificate viewer.
  3. Download the certificate by selecting the Details tab at the top of the window, then click the Copy to File... button on the Details window. This starts the Certificate Export wizard.
  4. Export the certificate as DER encoded binary X.509 (.CER), which corresponds to the PEM certificate format expected by cURL.
  5. Save the certificate to the disk, and note its location and filename.

cURL and Server Authentication

cURL can then be called as follows to use the downloaded certificate:

curl -v --cacert <theCertificate.cer> --basic -u administrator:rhapsody -H "Accept: application/json" https://server:8444/api/alerts/active

The --cacert parameter tells cURL when its trusted certificates can be found, and so is directed to the Rhapsody server's certificate by giving it the path to the download certificate file (encapsulate it within double quotes if the path contains spaces). SSL authentication only succeeds if the server you are connecting to presents either the certificate you already have, or a certificate issued by that certificate, and so consequently prevents man-in-the-middle attacks. This SSL authentication is done prior to sending the username and password, so an attacker is unable to view this information before cURL terminates the connection.

It is essential that the URL used to connect to the Rhapsody REST API contains the real hostname for the machine - specifically it must use one of the hostnames that are included in the SSL certificate. If it fails to do this, then cURL will abort the connection due to a hostname mismatch. SSL certificates generated for a Rhapsody engine at installation time include all hostnames available for that machine at the time Rhapsody is first started; on the other hand, manually generated SSL certificates may not. View the certificate (double-click it in Windows®) to see which hostnames are included by looking at the Subject (the CN attribute) and the SubjectAltnerativeNames extension.