Using an SSL certificate with BIRT iHub enables verification of the identity of the BIRT iHub server and encryption of data sent between the web browser and BIRT Visualization Platform. The certificate installed with BIRT iHub is self-signed and is for demonstration purposes only. A self-signed certificate is not signed by a Certification Authority (CA). A CA verifies that a certificate is valid and that no tampering has occurred. Using this demonstration SSL certificate shows a warning in the web browser. Use the self-signed certificate to test the creation of an SSL-based connection between the web browser and the BIRT iHub server.
Using self-signed certificates during server testing is common practice for web developers. To test a secure SSL connection, generate a root certificate that signs and validates the self-signed certificate. This root certificate can then be installed and trusted in web browsers that connect to BIRT iHub. Root certificates from many certificate authorities are preinstalled in operating systems. These root certificates offer temporary SSL certificates that can also be used for testing SSL data security.
An SSL certificate has the following general characteristics:
Domain name, such as actuate.com. The name confirms the server is associated with the domain name of the web site.
Expiration date. After this expiration date, the certificate will not be trusted.
Certificate authority signature. The certificate authority distributes a public root certificate that, when trusted, can validate an SSL certificate. Most commercial certificate authorities distribute a public root certificate to computer operating systems. Check that this is the case with your certificate authority.
The server’s public key, used to send encrypted information to the server.
Using SSL with IDAPI
The Actuate Information Delivery application programming interface (IDAPI) supports integrating and administering BIRT iHub using extensible markup language (XML) and the simple object access protocol (SOAP). Using the IDAPI, developers create applications that perform such tasks as uploading and downloading files, generating a document and scheduling document generation, sending an e-mail notification when a job completes, and using external libraries.
By default, BIRT iHub supports SSL secured SOAP services on port 8001. This port number is set in the acserverconfig.xml file in the SOAPDispatchService element. In a default Windows installation, the location of this file is:
The default values for the port numbers defined in the SOAPDispatchService are:
<SOAPDispatchService
EnableRequestService="true"
ProvisioningSOAPPort="8010"
SOAPDispatchSOAPPort="8000"
ProvisioningSOAPSSLPort="8011"
SOAPDispatchSOAPSSLPort="8001"/>
After enabling SSL for the Visualization Platform, test the SSL secured SOAP port using a URL of the following format:
https://<servername>:8001/wsdl
For example, for a server named urup, use the following URL:
https://urup:8001/wsdl
This request asks which Web Service Description Language (WSDL) utilities are available. The response is a list of available SOAP APIs and their implementations, as shown in Figure 4‑15. The green padlock symbol in the browser address field confirms that SSL security is enabled.
Figure 4‑15 WSDL utility secured with SSL
For more information about using IDAPI, see Integrating Applications into BIRT iHub.
Using SSL with JSAPI
The Actuate JavaScript API (JSAPI) is a set of JavaScript classes that support authenticating users, connecting to data sources, interacting with the user, generating reports, and viewing reports. These classes support using the HTTPS protocol and SSL security.
The JSAPI library is available from any iHub Visualization Platform client installation or Actuate BIRT Deployment Kit. The URL for the library is:
http://127.0.0.1:8700/iportal/jsapi
127.0.0.1:8700 is the host name and TCP port for an available Actuate web application host.
/iportal is the context root for the web application.
/jsapi is the default location of the JSAPI libraries.
A script tag in an HTML page loads the JSAPI library, as shown in the following code:
A BIRT iHub system using external tools to manage Visualization Platform users supports connecting to a Lightweight Directory Access Protocol (LDAP) or Active Directory server using SSL. By default, BIRT iHub only connects to an LDAP or Active Directory server that has a signed certificate. To connect to a server that does not have a signed certificate, use the Java keytool utility to add that certificate as a trusted certificate. For information on using the Java keytool utility, see the following URL:
Use SSL to validate the identity of the BIRT iHub Visualization Platform server and to encrypt the data between the client web browser and the BIRT iHub server. To use SSL with the BIRT Visualization Platform, disable SAML and Message Distribution Service (MDS). In the web.xml file located at \iHub\web\iportal\WEB-INF\. In a default Windows installation, this location is:
Change the following values and restart the Actuate iHub 3 Service:
Set the SAMLEntityID parameter to an empty value. For example:
<context-param>
<description>The SP ID for SAML SSO</description>
<param-name>SAMLEntityID</param-name>
<param-value></param-value>
</context-param>
Set the Message Distribution Service MDS_ENABLED parameter to false. For example:
<context-param>
<!-- true or false: Enable or disable MDS -->
<param-name>MDS_ENABLED</param-name>
<param-value>false</param-value>
</context-param>
After restarting the Actuate iHub 3 Service, access the Visualization Platform using a URL of the following format:
https://<servername>:8701/iportal/
For example, for a server named urup, use the following URL:
https://urup:8701/iportal/
Figure 4‑16 shows the secured SSL connection to the Visualization Platform using HTTPS. The default certificate included with the installation of Visualization Platform is not signed by a certification authority and the browser identifies it as not trusted. When you use your own signed and trusted SSL certificate, the web browser trusts your certificate.
Figure 4‑16 Using HTTPS to access the Visualization Platform
For testing purposes, install and trust the self-signed demonstration certificate included in the default installation of Visualization Platform. This certificate is birtihub.crt located in the following folder:
Each operating system has a different method to install a trusted certificate. For example, in Windows, install this certificate into the Trusted Root Certification Authorities certificate store. Figure 4‑17 shows the same web URL as Figure 4‑16 after setting the demonstration certificate to be trusted.
Figure 4‑17 Using HTTPS with a trusted certificate
How to install and trust the demonstration SSL certificate on Windows
This example shows how to install your own root certificate for testing purposes. This procedure applies to browsers other than Mozilla Firefox. Firefox uses a different mechanism to trust certificates. Refer to the Firefox documentation to set up a trusted certificate on Firefox.
1 Using Windows Explorer, navigate to the following folder:
2 Open the birtihub.crt file. Certificate—General appears, as shown in Figure 4‑18.
Figure 4‑18 Opening an untrusted root certificate
3 Choose Install Certificate. Certificate Import Wizard appears, as shown in Figure 4‑19.
Figure 4‑19 Installing an root certificate
4 Choose Next. Certificate Store appears.
5 Enable Place all certificates in the following store. Choose Browse. Select Certificate Store appears.
6 Select Trusted Root Certification Authorities, as shown in Figure 4‑20. Choose OK.
Figure 4‑20 Selecting a store to install the root certificate
7 In Certificate Store, choose Next, as shown in Figure 4‑21.
Figure 4‑21 Selecting where to install the root certificate
In Completing the Certificate Import Wizard, choose Finish, as shown in Figure 4‑22.
Figure 4‑22 Finishing the installation of the root certificate
If you receive a security warning asking if you want to install this certificate, choose Yes.
When you receive an alert that the import was successful, choose OK.
Choose OK to close Certificate—General.
How to verify that the HTTPS connection is trusted
This example shows how to verify that the HTTPS connection to Visualization Platform is trusted. This procedure applies to browsers other than Mozilla Firefox. Firefox uses a different mechanism to check trusted certificates. Refer to the Firefox documentation to check the HTTPS connection on Firefox.
1 Using Windows Explorer, navigate to the following folder:
2 Open the birtihub.crt file. The certificate should look similar to Figure 4‑23.
Figure 4‑23 Verifying the installation of the root certificate
3 Choose Certification Path. Verify that the certificate status is OK, as shown in Figure 4‑24.
Figure 4‑24 Verifying the certificate status
Choose OK.
4 Open a web browser such as Google Chrome. Type the a URL of the following format, replacing servername with the name of your server. Do not use localhost as the name of the server.
https://servername:8701/iportal/
Visualization Platform appears, using HTTPS.
5 Choose view site information. Choose Connection as shown in Figure 4‑25.
Figure 4‑25 Verifying a secured SSL connection to Visualization Platform
Using SSL for communication with the volume metadata database
You can encrypt the connection from BIRT iHub to the volume metadata database. By default, BIRT iHub uses a PostgreSQL database to contain volume metadata. In System Console, Metadata Database displays the properties for this PostgreSQL database. The database type for this database is ActuatePostgreSQL. Figure 4‑26 shows the following properties for this database, installed on a machine named urup. An asterisk (*) next to the property name means the property is required.
Database server
The host name of the machine containing the database.
Database port
The default port number for the default PostgreSQL database is 8432.
Database name
The name of the database. The default database name is ihub.
Encryption Method
One of the following methods:
requestSSL
BIRT iHub encrypts the login request and data using SSL. If the database server does not support SSL, the driver establishes an unencrypted channel.
SSL
BIRT iHub performs SSL certificate verification.
noEncryption
The channel between BIRT iHub and the metadata database passes unencrypted data.
Username
The database user name. The default user name is ihub.
Password
The database user name password. The default password of the ihub user is postgres.
Test Connection
Choose to verify that the BIRT iHub system can successfully connect to the metadata database.
The PostgreSQL data folder is the location of the certificate and keys used by the PostgreSQL server. If you change the certificate or keys, restart the PostgreSQL server. The SSL files for a default PostgreSQL database are in the following folder:
Test the SSL connection of the PostgreSQL using the PostgreSQL interactive terminal (psql) command. This command is located in \postgresql\bin folder of the iHub installation. The default location of this software is:
See the documentation at the following URL for more information about configuring and securing a PostgreSQL database:
http://www.postgresql.org/docs/
How to verify that a PostgreSQL server supports an SSL connection
The following example shows how to use the Windows command prompt to check if an SSL connection to a PostgreSQL database is possible. This example connects you to the default PostgreSQL server installed with iHub. Use the same computer as the PostgreSQL server. This server has a user name and password with the value postgres and a database table named ihub. If either the user name or password of your PostgreSQL server has changed, use the current user name and password.
1 In a command window, navigate to \postgresql\bin folder of the iHub installation. The default location is:
3 When prompted for a password, type the password for the postgres user. In this example, the password is postgres. Then press Enter. You should receive the following response.
psql (9.2.4)
WARNING: Console code page (437) differs from Windows code page (1252)
8-bit characters might not work correctly. See psql reference
4 Type \q and press Enter to quit the terminal. You can see in the connection information that an SSL connection is established.
Managing SSL files
The SSL certificates and keys used to secure BIRT iHub and the Visualization Platform are located in the \shared\config\credentials folder in the BIRT iHub installation folder. The default location is:
This location contains the iHub’s digital certificate in the Privacy Enhanced Mail (PEM) format and the Java KeyStore (JKS) file, which is a repository of security certificates. BIRT iHub is configured to use these certificates in the following files:
The acpmdconfig.xml file located in the iHub \etc\ folder. The default location is:
Although you can change the SSL key alias and keystore file, you must use the existing the keystore password defined in KeystorePass. Your JKS keystore must use the following password:
birtihub
If you change these SSL files, you must restart the Actuate iHub 3 Windows service.
You can use the Java keytool utility to view and create SSL certificates and keys. This utility is located in the \bin folder of the BIRT iHub installation of the Java SE Development Kit (JDK). The default location of the JDK is:
How to use the Java keytool utility to view the contents of the JKS file
BIRT iHub generates sample SSL certificates that securely connect a web browser to BIRT iHub. To use SSL security in a production environment, you must replace these SSL certificates with certificates signed by a Certification Authority.
1 In a command window, navigate to the \credentials folder. The default location is:
10 In a web browser, navigate to https://MyHost:8701/iportal, where MyHost is the name of the computer on which iHub is installed. You must also change the cluster URL in System Console.
11 Check the SSL certificate. It should have the certification number of the commercial SSL certificate, not the SSL certificate that installs with BIRT iHub.
Domain name, such as actuate.com. The name confirms the server is associated with the domain name of the web site.
