How Do I Secure API Gateway Server Communication with API Clients?

To configure webMethods API Gateway server for secure communication with API Clients

1. Locate the keystore and truststore files in the file system.

   The default keystore and truststore files are available in the Installation_Dir\common\conf folder.

   Note: If you want to use a custom keystore with self-signed certificates, see Creating a Custom Keystore with Self-Signed Certificates for details on how to create a keystore and generate the required self-signed certificate.
2. Configure keystore and truststore in the webMethods API Gateway UI.

   You require a keystore alias for configuring an HTTPS port in API Gateway. You require the truststore alias for validating client certificates.

   1. Log on to webMethods API Gateway.
   2. Navigate to Administration > Security > Keystore/Truststore.
   3. Click Add keystore.
   4. Provide the following details:
      • Alias. A text identifier for the keystore file. The alias name can contain only alphabets, numbers and underscores. It cannot include a space, hyphen, and special characters.
      • Select file. Browse and select the file https_keystore.jks file located at Installation_Dir\common\conf.
      • Password. Specify the password for the saved keystore file associated with this alias.
      • Type. Specify the certificate file format of the keystore file, which, by default, is JKS for keystores.
      
   5. Click OK.

      A warning appears, prompting you to create a password for the key alias.

   6. Close the warning dialog box.

      The Update keystore dialog box appears.

   7. Provide the password for the https_keystore file, for example, manage.
      
   8. Click Save.
   9. Click Add truststore.
   10. Provide the following details.
       • Name. A name for the truststore file.
       • Upload truststore file. Browse and select the https_truststore.jks file located at Installation_Dir\common\conf.
       • Password. Specify the password that is used to protect the contents of the truststore, for example, manage.
       
   11. Click Save.
   12. In the Configure keystore and truststore settings for inbound messages section, provide the keystore and truststore aliases for deploying any SOAP message flows that require signature, encryption, X.509 authentication, and so on, as configured in the Inbound Authentication - Message policy.
       
   13. Click Save.
3. Create an HTTPS port in webMethods API Gateway and associate the keystore and truststore aliases.
   1. Navigate to Administration > Security > Ports.
   2. Click Add ports, and select HTTPS as the port type.
   3. Click Add.
   4. Provide the following details
      • Port. Specify the port number you want to use for the HTTPS communication.
      • Alias. Specify an alias for the port that is unique for this API Gateway instance. The alias must be between 1 and 255 characters in length and include one or more of the following: alphabets (a -z, A-Z), numbers (0-9), underscore (_), period (.), and hyphen (-).
      • Backlog. Specify the number of requests that can remain in the queue for an enabled port before API Gateway begins rejecting requests. The default is 200. The maximum value is 65535.
      • Keep alive timeout. Specify when to close the connection if the server has not received a request from the client within this timeout value (in milliseconds) or when to close the connection if the client has explicitly placed a close request with the server.
   5. In the Listener-specific credentials section provide the following information:
      • Keystore alias. Select HTTPS_KEYSTORE.
      • Key alias(signing). Select https_keystore.
      • Truststore alias. Select Truststore.
      
   6. Click Add.

      The HTTPS port 8886 is added and displayed in the list of ports.

      
   7. Enable the new port 8886 by clicking the X mark in the port's Enabled column.

      The port 8886 is now enabled and webMethods API Gateway server is now ready to accept requests over HTTPS port 8886.

4. Setup security configuration parameters for the HTTPS port, which is enabled for communication with API Clients, to determine how API Gateway server interacts with the clients and defines whether the connection is one-way or two-way SSL.
   1. Navigate to Administration > Security > Ports. This displays the list of ports.
   2. Click the port 8886.
   3. In the Security configuration > Client authentication section, select one of the following values:
      • Request client certificate. API Gateway requests client certificates for all requests. If the client does not provide a certificate, the server prompts the client for a userid and password. The server checks whether the certificate exactly matches a client certificate on file and is signed by a trusted authority. If so, the client is logged in as the user to which the certificate is mapped in API Gateway. If not, the client request fails, unless central user management is configured.
      • Require client certificate. API Gateway requires client certificates for all requests. The server checks whether the certificate exactly matches a client certificate on file and is signed by a trusted authority.
   4. Click Update. The security configuration updates are saved.
5. Set port 8886 as primary port. This is an optional step only if you want to change the primary port.
   1. Set the port 8886 as primary port by clicking in the port's Primary port column. The port 8886 is now enabled and webMethods API Gateway server is now ready to accept requests over HTTPS port 8886.
      
   2. Disable the port 5555 by clicking the tick mark in the port's Enabled column.

      The default primary port 5555 that accepts requests on HTTP is now disabled.

6. Configure the webMethods API Gateway UI to access the webMethods API Gateway server securely.

   This step is required only when the primary port is set to HTTPS.

   1. Open the file uiconfiguration.properties located in the folder Installation_Dir\profiles\IS_default\apigateway\config\.
   2. Modify the following properties:

      #IS properties
      apigw.is.base.url = https://localhost:8886
      apigw.is.rest.directive = /rest
      apigw.user.lang.default = en 
      

      Here we configure the HTTPS port 8886 in the base URL property to point the webMethods API Gateway to communicate to the server URL.

Restart API Gateway server for the changes to take effect. You now have a secure communication channel established between the webMethods API Gateway server and the client.

Harden TLS configuration of the webMethods API Gateway server ports

To harden the TLS configuration of the API Gateway server ports, perform the following:

1. Disable support for unsafe protocols using the following setting:

   watt.net.jsse.server.disabledProtocols=SSLv2Hello,SSLv3,TLSv1,TLSv1.1

2. Optional. You can restrict the supported protocols to exclusively use TLSv1.3 protocol by disabling TLSv1.2 using the following setting:

   watt.net.jsse.server.disabledProtocols=SSLv2Hello,SSLv3,TLSv1,TLSv1.1,TLSv1.2

3. Reject the client initiated renegotiation by adding the following line to the custom_wrapper.conf file located in the directory SAG_root /profiles/IS_default/configuration.

   wrapper.java.additional.402=-Djdk.tls.rejectClientInitiatedRenegotiation=TRUE

4. Specify a list of secure cipher suites.

   For details about the recommended cipher suites, see the cipher suite recommendation by IANA organization (https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml) or the https://documentation.softwareag.com/webmethods/integration_server/pie10-5/10-5_Integration_Server_Administrators_Guide.pdf

5. Set the size of Ephemeral Diffie-Hellman Keys to 2048 depending on the configured cipher suites. You can do this by adding the following line to the custom_wrapper.conf file located in the directory SAG_root /profiles/IS_default/configuration:

   wrapper.java.additional.401=-Djdk.tls.ephemeralDHKeySize=2048

You can verify the resulting TLS configuration using tools such as testTLS.sh that checks for vulnerable TLS configurations.