4.1. Configuring Web Integration Service¶
When you start Web Integration Service, you can specify a configuration file in XML format (it is not required). In that file, you can set properties that control the behavior of the service.
4.2. Terms to Know¶
Before learning how to configure Web Integration Service, you should become familiar with a few key terms and concepts:
- A Web Integration Service configuration—represented by
<web_integration_service>XML tag—refers to an execution of Web Integration Service.
- An Application—represented by the
<application>XML tag—defines a collection of DomainParticipants and their contained entities. Applications are instantiated in the context of a Web Integration Service configuration. That is, a Web Integration Service configuration contains a set of applications that contain entities that are accessible for clients of the service.
4.3. How to Load the XML Configuration¶
Web Integration Service loads its XML configuration from multiple locations. This section presents the various approaches, listed in load order.
The first three locations are inherited from Connext DDS (see the RTI Connext DDS Core Libraries User’s Manual).
$NDDSHOME/resource/xml/NDDS_QOS_PROFILES.xmlThis file contains the Connext DDS default QoS values; it is loaded automatically if it exists. (First to be loaded.).
- File specified in the
NDDS_QOS_PROFILESenvironment variable: The files (or XML strings) separated by semicolons referenced in this environment variable are loaded automatically.
<working directory>/USER_QOS_PROFILES.xmlThis file is loaded automatically if it exists.
The next locations are specific to Web Integration Service.
$NDDSHOME/resource/xml/RTI_WEB_INTEGRATION_SEVICE.xmlThis file contains the default Web Integration Service configuration; it is loaded if it exists. It defines an empty service that clients can add applications to, as well as an example “ShapesDemo” service.
<working directory>/USER_WEB_INTEGRATION_SERVICE.xmlThis file is loaded automatically if it exists.
- File specified using the command-line parameter
You may use a combination of the above approaches.
Here is an example configuration file. You will learn the meaning of each line as you read the rest of this section.
<?xml version="1.0" encoding="UTF-8"?> <dds> <types> <struct name="MyType"> <member name="name" key="true" type="string" stringMaxLength="128"/> <member name="count" type="long" /> </struct> </types> <web_integration_service name="ExampleService"> <application name="MyApplication"> <domain_participant name="MyParticipant" domain_id="32"> <register_type name="MyShapeType" type_ref="ShapeType" /> <topic name="Square" register_type_ref="MyShapeType" /> <publisher name="MyPublisher"> <data_writer name="MySquareWriter" topic_ref="Square" /> </publisher> <subscriber> <data_reader name="MySquareReader" topic_ref="Square" /> </subscriber> </domain_participant> </application> </web_integration_service> </dds>
4.4. XML Syntax and Validation¶
Web Integration Service provides DTD and XSD files that describe the format of the XML content. We recommend including a reference to one of these documents in the XML file that contains the service’s configuration—this provides helpful features in code editors such as Visual Studio® and Eclipse®, including validation and autocompletion while you are editing the XML file.
The DTD and XSD definitions of the XML elements are in
To include a reference to the XSD document in your XML file, use the attribute
xsi:noNamespaceSchemaLocation in the
<dds> tag. For example:
<?xml version="1.0" encoding="UTF-8"?> <dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="<NDDSHOME>/resource/schema/rti_web_integration_service.xsd"> <!-- ... --> </dds>
To include a reference to the DTD document in your XML file, use the
<!DOCTYPE> tag. For example:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE dds SYSTEM "<NDDSHOME>/resource/schema/rti_web_integration_service.dtd"> <dds> <!--...--> </dds>
We recommend including a reference to the XSD file in the XML documents; this provides stricter validation and better autocompletion than the corresponding DTD file.
4.6. Authentication and Access Control Mechanisms¶
Web Integration Service supports a simple access-control mechanism which can be enabled to restrict access to its REST API. It is based on a set of API keys that authorize client applications to perform operations over the HTTPS protocol. When access control is enabled, client applications without an authorized API key are rejected and are not allowed to perform any operation on the running instance.
To enable access control, we recommend that you enable HTTPS to secure the transmission of API keys and data. While HTTPS can be enabled for all kinds of applications—even when access control is not a requirement—API keys should never be exchanged over simple HTTP, as malicious applications could extract the API key, which should be considered a secret.
Section 4.6.1 explains how to enable HTTPS in Web Integration Service. Section 4.6.2 describes the Access Control List file. Section 4.6.3 illustrates how to manage the Access Control List file. Section 4.6.4 explains how to configure client applications to use the generated API keys.
4.6.1. Enabling HTTPS¶
To secure the transmission of API keys and the data exchanged between client applications and Web Integration Service, information must be exchanged via HTTPS.
To enable HTTPS, all the ports specified in the
command-line option must add a trailing “
s” to the port number and
provide an SSL certificate (which must include the private key). For example:
$NDDSHOME/bin/rtiwebintegrationservice -listeningPorts 8080s \ -sslCertificate ~/.certificates/server.pem
The trailing “
s” (that is, using 8080s instead of 8080) indicates that
HTTPS must be used on every port it follows. In contrast, ports specified
without a trailing “
s” will use HTTP.
Unlike other popular web servers, Web Integration Service’s web server requires you to combine both the actual certificate and the RSA private key section in the same file.
For example, Apache uses the
SSLCertificateKeyFile parameters to configure certificates and keys.
Nginx uses two different parameters:
Assuming the original certificate is stored in a file
server.crt and the private key is in a file called
these certificates need to be combined in a common PEM file (which in this
example we call
server.pem) as follows:
$ cat server.crt > server.pem $ cat server.key >> server.pem
In some cases, certificate authorities provide two different certificates, one for the domain and one for a certificate from the appropriate certificate authority (e.g., DigiCert). In that case, all certificates and keys can be combined as follows:
$ cat star_dot_example_dot_com.crt > server.pem $ cat DigiCertCA.crt >> server.pem $ cat star_dot_example_dot_com.key >> server.pem
4.6.2. The Access Control List File¶
To enable access control, you need to provide an Access Control List (ACL)
file when starting the service. The
-aclFile command-line option
specifies the path to the ACL file and configures the service to reject HTTP
requests from clients that do not provide a valid API key (i.e., an API key
included in the Access Control List file the service was started with).
If the file specified with
-aclFile does not exist, Web Integration
Service will create an empty file that can be populated later on with the
-deleteAPIKey command-line options.
The Access Control List is a Sqlite3 database with a single table that contains all the API keys, a message describing each API key, and the date when they were added to the file.
4.6.3. Creating, Deleting, and Listing API keys¶
rtiwebintegrationservice executable can be used to dynamically
create, delete, and list API keys. If the file that is being updated is in use
by any Web Integration Service instance, the service will be automatically
notified of the changes in it. Then it will reload the list of valid API keys
18.104.22.168. Creating API Keys¶
To add a new API key to an ACL file, use the
-aclFile command-line options as follows:
$NDDSHOME/bin/rtiwebintegrationservice \ -createAPIKey "API Key for ShapesDemo client" \ -aclFile ~/.acl/acl_file.db
If the ACL file does not exist, it will automatically be created. Note that a
message identifying the API key must be passed to the
22.214.171.124. Deleting API Keys¶
To delete an API key from an ACL file, use the
-aclFile command-line options as follows:
$NDDSHOME/bin/rtiwebintegrationservice \ -deleteAPIKey "r5x/ERs9wGkIufffeRfWSFH1li/60BUoJmJ0ETua" \ -aclFile ~/.acl/acl_file.db
126.96.36.199. Listing API Keys¶
To list the API keys in an ACL file, use the
-aclFile command-line options as follows:
$NDDSHOME/bin/rtiwebintegrationservice \ -aclFile ~/.acl/acl_file.db \ -listAPIKeys
4.6.4. Using API Keys in Client Applications¶
Client applications communicating with access-control-limited instances of
Web Integration Service must include a valid API key in
OMG-DDS-API-Key header field of every HTTP request. The API key must
remain secret. Therefore, clients should only share it through a secure
connection and should not expose it to users of the client application.
Section 5.1 provides a complete overview of the HTTP headers involved in operations supported by Web Integration Service’s REST API.