User Guide Cancel

Configure SSL

Last updated on May 30, 2024 | Also applies to ColdFusion

Overview

Secure Socket Layer (SSL) is a protocol that provides communications security between a client and a server by implementing encrypted data and certificate-based authentication.

SSL is a mature protocol and is supported by most browsers.

SSL uses encryption while transmitting data between two or more parties where the sender encrypts the data and the receiver decrypts the data. This method is known as public key encryption. For the public key encryption to take place, the parties in the loop must present a certificate before transmitting any encrypted data.

To ensure that the certificate used is valid, the SSL usually contacts a trusted third-party server called a Certificate Authority (CA).

HTTP vs HTTPS

HTTPS uses SSL protocols to transmit data. When a message is sent using HTTPS,the message is first encrypted with SSL, sent and received using HTTP, and finally decrypted using SSL.

In comparison to HTTP, HTTPS provides better security through encryption and uses digital certificates.

Configuring SSL in API Manager

The API Manager includes two SSL-specific configuration files for both portal and proxy. They are:

portalsslconfig .xml
proxysslconfig .xml

Both the files are located in <APIManagerHome>/conf. The config.xml file, located in the same location, contains the following lines:

</https>

To enable SSL, change the flag to "true" after creating the keystore and the certificates.

You can configure SSL without using the ColdFusion connector or web server.

Note:

This document contains the steps for configuring SSL for a portal. To configure SSL for proxy, the same procedure holds true.

Generating key pairs and certificates

To generate the keys and certificate, you can use the keytool utility that is bundled with JDK. You can also use third-party certificates or use OpenSSL to create keys and certificates.

Using keytool, enter the following in the command prompt:

keytool -keystore keystore -alias portal -genkey -keyalg RSA

This command creates a keystore with alias named portal and generates a key using the RSA algorithm.

After you enter the command, the keytool will ask you to enter the values for Common Name (CN), Organizational Unit (OU), Organization(O), Locality (L), State (ST) and Country (C).

You will also set the passwords for the keystore and the keystore alias.

The CN should match the domain name of your application.

Updating portalsslconfig.xml

After you generate the keystore, update the portalsslconfig.xml with the keystore's information.

<keystore>
    <path>The keystore path where the server certificate and key is present</path>
    <type>The keystore type, for example, jks or pkcs12.</type>
    <password>The keystore password</password>
    <alias>The key alias to choose as server certificate. If the keystore contains multiple aliases, you can select the specific alias by specifying here.</alias>
    <keypassword>The key password that is used to extract the private key stored at the specified alias. If you do not specify the alias, the JVM chooses the first key as alias.</keypassword>
</keystore>

For example,

<keystore>
      <path>/path/to/keystore</path>
      <type>jks</type>
      <password>keyspassword</password>
      <alias>portal</alias>
      <keypassword>aliaspassword</keypassword>              
</keystore>

To enable two-way SSL between the client and API Manager portal, specify the following configuration:

Set <clientauth>false</clientauth> to "true".
Specify the trust store path where the client certificates are stored.
Specify the type of the trust store (for example, jks or pkcs12). If you do not specify a trust store, the API Manager detects whether the keystore is jks or pkcs12.
Specify the trust store password.

<truststore>
      <path>/trust/store/path</path>
      <type>jks</type>
      <password>tspassword</password>
</truststore>
<clientauth>true</clientauth>

Specifying TLS protocols

Specify the list of TLS protocols that the HTTPS listener supports. By default, all TLS protocols are enabled.

<protocols>
      <value>TLSv1.2</value>
      <value>TLSv1.1</value>
      <value>TLSv1</value>
</protocols>

Specifying ciphersuites

Specify the list of ciphersuites to be included or excluded. The resulting list of ciphersuites will be supported by the HTTPS. If the included list is empty, all supported ciphersuites by JVM will be included by default.

<ciphersuites>
      <excluded>
             <value>.*NULL.*</value>
             <value>.*RC4.*</value>
             <value>.*MD5.*</value>
             <value>.*DES.*</value>
             <value>.*DSS.*</value>
             <Item>.*_RSA_.*MD5$</Item>
      </excluded>
      <included>
             <value>TLS_DHE_RSA.*</value>
             <value>TLS_ECDHE.*</value>
      </included>
</ciphersuites>

Updating config.xml

Enable https to "true" and access the portal through the port specified.

<https enabled="true">
     <port>9500</port>
     <ssl ref="${sys:apim.home}/conf/portalsslconfig.xml"/>
</https>

To access the administrator portal, enter the following in your browser:

https://<servername>:9500/admin.html

Get help faster and easier

New user?