Secure API Gateway server, a component in an API Management setup, to enable the other components in the API Management setup to communicate with the API Gateway server over HTTPS. This use case explains how to secure API Gateway server communication using HTTPS protocol by using the existing server and client certificates.

The use case starts when you have an API Gateway instance to be secured using HTTPS and you have the required server and client certificates to secure the communication channel between API Gateway server and other components. It ends when the secure channel is configured for communication between API Gateway server and the other components.

Before you begin

Ensure that you have:

• API Gateway administrator privileges
• Required client and server certificates

To configure the API Gateway server for secure communication

1. Ensure that the keystore and truststore with the required certificates are located at Installation_Dir\common\conf.
   
   

   835×418 52.2 KB
   
   for details on how to create a keystore and generate the required self-signed certificate.
2. API Gateway UI.
   This is required to set up a secure outbound communication from the API Gateway server to the client.
   1. Log on to the API Gateway user interface.
   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 can not 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.
      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.
         
   11. Click Save.
   12. In the Configure keystore and truststore settings section, provide the details of keystore and truststore configured.
       
   13. Click Save.
       API Gateway, by default, uses the configured keystore and truststore files for keys and certificates for any in and out HTTPS communication.
        
3. Create an HTTPS port in API Gateway and associate the keystore and truststore aliases.

   This is required to set up the inbound communication.

   1. Navigate to Administration > Security > Port.
   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 the API Gateway server is now ready to accept requests over HTTPS port 8886.

   8. Set the port 8886 as a primary port by clicking in the port's Primary port column.

      The port 8886 is now set as the primary port and the port 5555 is no more the primary port.
      

   9. 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.

4. Configure the API Gateway UI to access the API Gateway server securely.
   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 API Gateway to communicate to the server URL.

You now have a secure communication channel established between the API Gateway server and the client.

Creating a Custom Keystore with Self-Signed Certificates

You have to perform this procedure if your organization does not have policies and procedures in place regarding the generation and use of digital certificates and certificate chains, including the use of certificates signed by a CA but want to generate a self-signed certificate and import them into the Keystore and truststore.

1. Create a new keystore with a self-signed certificate.
   1. Run the following command, and provide the keystore password (for example, manage) and the other required details to generate a new key and store it in the specified keystore https_keystore.jks.
      keytool -genkey -v -keystore https_keystore.jks

      -alias HTTPS_KEYSTORE -keyalg RSA -keysize 2048 -validity 10000
      

      Example:
      
      

   2. Run the following command and provide the keystore password (for example, manage) to export the certificate from the keystore https_keystore, and place it in a specified location.

      keytool -exportcert -v -alias HTTPS_KEYSTORE -file
Installation_Dir\common\conf\https_gateway.cer -keystore
Installation_Dir\common\conf\https_keystore.jks
      
      Example:

      
      The certificate https_gateway.cer is exported from the keystore https_keystore and placed in the location Installation_Dir\common\conf\.
2. Create a truststore and import the generated certificate.
   1. Run the following command to create a truststore file and import the generated certificate into the truststore file.

      keytool -importcert -alias HTTPS_TRUSTSTORE -file 
      Installation_Dir\common\conf\https_gateway.cer -keystore 
      Installation_Dir\common\conf\https_truststore.jks

      Example:

      

      A truststore file https_truststore.jks is created with the imported certificate.

      You can now view the keystore and truststore files created and located at Installation_Dir\common\conf\.

      

      835×418 52.2 KB

How do I Secure API Gateway User Interface Communication using HTTPS?

Secure API Gateway UI (web application), one of the API Gateway components in an API Management setup, to enable users to access the API Gateway UI securely over HTTPS. This use case explains how to secure API Gateway communication using HTTPS protocol.

The use case starts when you have an API Gateway instance with API Gateway UI that needs to be secured using HTTPS where you are using existing certificates to secure the communication channel between API Gateway UI and the clients(browsers). It ends when the secure channel is configured for communication between the API Gateway UI and the client.

Before you begin

• You must have API Gateway administrator privileges.
• You must have the required client and server certificates.

To configure API Gateway user interface for secure communication

1. Ensure that the server certificates and client certificates are located at Installation_Dir\common\conf.
   Note: If you want to use a custom keystore with self-signed certificates, see #Creating a Custom Keystore with Self-Signed Certificates for more details on how to create a keystore and generate the required self-signed certificate.
2. Configure the keystore and the HTTPS port on which you want to expose API Gateway UI.
   1. Navigate to Installation_Dir\profiles\IS_default\configuration\com.softwareag.platform.config.propsloader and open the property file com.softwareag.catalina.connector.https.pid-apigateway.properties.
   2. Modify the following properties by providing the keystore, passsword, and port details.

      keystoreFile=generated_keystore_file_path/https_keystore.jks
      port=9073 (https port in which you want to expose webApp)
      @secure.keystorePass=password (password used while creating the keystore file)

               For details of the configurations, refer the following:

• https://documentation.softwareag.com/webmethods/wmsuites/wmsuite10-5/Cross_Product/10-5_Software_AG_Infrastructure_Administrators_Guide.pdf
• https://tomcat.apache.org/tomcat-7.0-doc/config/http.html

How do I Secure API Gateway Data Store Communication using HTTPS?

API Gateway Data Store is the default data store for API Gateway. You can secure API Gateway Data Store (a simple Elasticsearch instance), one of the components in an API Management setup, to communicate securely over HTTPS. This use case explains how to secure Elasticsearch using Search Guard, an Elasticsearch plugin, that offers encryption, authentication, and authorization to protect data from attackers and other misuses. Search Guard secures Elasticsearch by exposing it over HTTPS, and enables basic authentication by configuring users.

The use case starts when you have an API Gateway instance that uses API Gateway Data Store as the default data store, and you want to secure the communication channel between API Gateway Data Store and other components using HTTPS. It ends when the secure channel is configured for communication between Elasticsearch and other components.

Before you begin

Ensure that you have:

• A basic understanding of API Gateway and its communication with API Gateway Data Store for storing data.
• A basic understanding of Kibana and its communication with API Gateway Data Store for rendering the dashboards in API Gateway.

To secure API Gateway Data Store communication using HTTPS

1. Install and initialize the Search Guard plugin.
   1. Shutdown API Gateway.
   2. Navigate to Installation_Dir\InternalDataStore\bin and open the file enable_ssl.bat. Comment out the last line as shown.
      
      

      898×193 7.08 KB
   3. Click Save.
   4. Copy the folder sagconfig from Installation_Dir\IntegrationServer/instances\Instance_name\packages\WmAPIGateway\config\resources\elasticsearch to Installation_Dir\InternalDataStore.
   5. Copy the certificates node-0-keystore.jks and truststore.jks from Installation_Dir\InternalDataStore\sagconfig to Installation_Dir\InternalDataStore\config.
   6. Navigate to Installation_Dir\InternalDataStore\config\ and open the file elasticsearch.yml.
   7. Delete all the properties that start with searchguard, if present, and add the Search Guard properties as follows:

      searchguard.ssl.transport.keystore_type: JKS
      searchguard.ssl.transport.keystore_filepath: node-0-keystore.jks
      searchguard.ssl.transport.keystore_alias: cn=node-0
      searchguard.ssl.transport.keystore_password: a362fbcce236eb098973
      searchguard.ssl.transport.truststore_type: JKS
      searchguard.ssl.transport.truststore_filepath: truststore.jks
      searchguard.ssl.transport.truststore_alias: root-ca-chain
      searchguard.ssl.transport.truststore_password: 2c0820e69e7dd5356576
      searchguard.ssl.transport.enforce_hostname_verification: false
      searchguard.ssl.transport.resolve_hostname: false
      searchguard.ssl.transport.enable_openssl_if_available: true
      searchguard.ssl.http.enabled: true
      
      searchguard.ssl.http.keystore_type: JKS
      
      searchguard.ssl.http.keystore_filepath: node-0-keystore.jks
      
      searchguard.ssl.http.keystore_alias: cn=node-0
      
      searchguard.ssl.http.keystore_password: a362fbcce236eb098973
      
      searchguard.ssl.http.truststore_type: JKS
      
      searchguard.ssl.http.truststore_filepath: truststore.jks
      
      searchguard.ssl.http.truststore_alias: root-ca-chain
      
      searchguard.ssl.http.truststore_password: 2c0820e69e7dd5356576
      
      searchguard.ssl.http.clientauth_mode: OPTIONAL
      
      searchguard.authcz.admin_dn:
      
      “CN=sgadmin”
      
      

   For details on all the Search Guard properties, see #Search Guard Properties.

   8. Save and close the file.
   9. Run Installation_Dir\InternalInternalDataStore\bin\enable_ssl.bat,

      This installs the Search Guard plugin and starts the API Gateway Data Store.

   10. Shutdown and restart the API Gateway Data Store.
   11. Navigate to Installation_Dir\InternalDataStore\plugins\search-guard-2\tools and run the following command to initialize the API Gateway Data Store.

       sgadmin.bat -cd ..\..\..\sagconfig\
-ks ..\..\..\sagconfig\sgadmin-keystore.jks
-kspass 49fc2492ebbcfa7cfc5e -ts ..\..\..\sagconfig\truststore.jks
-tspass 2c0820e69e7dd5356576 -nhnv -p 9340 -cn SAG_EventDataStore

678×597 45.8 KB

2. Add users for basic authentication.
   1. Navigate to Installation_Dir\InternalDataStore\sagconfig and open the sg_roles_mapping.yml file.
   2. Add the username (for example, TestUser) in the users list as follows:

      sg_all_access:
      users:
      - Administrator
      - 'CN=demouser'
      - TestUser

   3. Generate the hash code for your password.
      1. Run Installation_Dir\InternalDataStore\plugins\search-guard-5\tools\hash.sh.
      2. Type the password.
      3. Press Enter.

         This generates the hash code.
         
         

   4. Navigate to Installation_Dir \InternalDataStore\sagconfig and open the file sg_internal_users.yml.
   5. Add the username and password as follows:

      #keys cannot contain dots
      #if you have a username with dots then specify it with username: xxx
      Administrator:
      hash: $2a$12$sm2AEpQx6QNq6YRSYHGCnetiRWKMWrQY/udSSI0dDFZ1r3qo51bzK
      CN=demouser:
      
      hash: $2a$12$.sbt5vK0AiBOmQ9hVyFK.sR55dx.7NJGSdP1YEqPUXHZKHZBRuoO
      TestUser:
      
      hash: $2a$12$Ua1gUiWaW5/b8ohgDqTfg.ruEDNOCsuV9RexlTigNf65TvSn6/Loy

   6. Run the command sgadmin.bat to initialize the Search Guard plugin.
   7. Shutdown and restart the API Gateway Data Store once the Search Guard plugin is initialized.

      API Gateway Data Store now runs on a secure channel on the HTTPS port and requests the basic authentication details.
      
      

      

      803×360 58.1 KB

3. Change the Kibana configuration to connect to Elasticsearch.

   1. Navigate to Installation_Dir\profiles\IS_default\apigateway\dashboard\config\ and open the file, kibana.yml.
   2. Uncomment the following properties and update them as follows:
      • elasticsearch.username: TestUser
      • elasticsearch.password: TestUser@123
      • elasticsearch.ssl.verificationMode: certificate
      • elasticsearch.ssl.certificateAuthorities: file path of your root-ca.pem certificate
      • elasticsearch.url: https://hostname: 9240
        
        Sample kibana.yml file
        
        
         
4. Change the API Gateway configuration to connect to Elasticsearch.
   1. Navigate to Installation_Dir\IntegrationServer\instances\default\packages\WmAPIGateway\config\resources\elasticsearch and open config.properties file.
   2. Uncomment the following properties and update them as follows:
      • pg.gateway.elasticsearch.http.username=TestUser
      • pg.gateway.elasticsearch.http.password=TestUser@123
      • pg.gateway.elasticsearch.https.truststore.filepath=Installation_Dir/InternalDataStore/sagconfig/truststore.jks
      • pg.gateway.elasticsearch.https.truststore.password=2c0820e69e7dd5356576
      • pg.gateway.elasticsearch.https.enabled=true
   3. Start the API Gateway Data Store manually.
   4. When API Gateway Data Store is up and running, start the Kibana server manually by running the kibana.bat file located at Installation_Dir/profiles\IS_default\apigateway\dashboard\bin.
   5. Start API Gateway.

      You can now log on, create APIs, and access the Analytics page with the user credentials.

Configuring Search Guard with self-generated certificates

As an API Provider, if you want to generate your own certificates to use with Search Guard instead of the default certificates that are shipped with API Gateway, you can configure Search Guard with user-generated certificates as Step 5. Search Guard provides an offline TLS tool. Use the tool to generate the required certificates for running Search Guard in a production environment.

1. Configure Search Guard with user-generated certificates.
   1. Download the tool zip file from https://search.maven.org/search?q=a:search-guard-tlstool
   2. Create a YAML file at Tool Installation Directory\config

      When you run the TLS tool command, it reads the node and certificate configuration settings from this YAML file, and places the generated files in a configured directory.

      Sample YAML file
      
      

   3. Run the following command to generate the required certificates.

      Tool Installation Directory/tools/sgtlstool.bat 
      -c ../config/Demo.yml -ca -crt

      The generated certificates are placed in the Tool Installation Directory/tools/out folder.
      
       

   4. Copy the certificates listed below from the folder Tool Installation Directory/tools/out to the Installation_Dir/EventDataStore/config folder.
      • test-node-1.key
      • test-node-1.pem
      • test-node-1_http.pem
      • test-node-1_http.key
      • test-client.pem
      • test-client.key
      • root-ca.pem
      • root-ca.key
   5. Configure the generated certificates in the API Gateway Data Store elasticsearch.yml file.
      
      
       
   6. Start API Gateway Data Store manually.
      A log message warns that the Search Guard is not initialized after API Gateway Data Store is up because the Search Guard is not initialized with the latest certificates
   7. Open a command prompt and change the directory to Installation_Dir\EventDataStore \plugins\search-guard-5\tools.
   8. Run the command

      sgadmin.sh -cd ..\sagconfig -nhnv -icl -cacert 
      ..\..\..\config\root-ca.pem -cert ..\..\..\config\test-client.pem 
      -key ..\..\..\config\test-client.key 
      -keypass your certificate password -p 9340
      Done with success log message appears.
      

   9. Shut down and restart API Gateway Data Store.
      API Gateway Data Store now uses the generated certificates for SSL communication.

Search Guard Properties

searchguard.ssl.transport.keystore_type

searchguard.ssl.transport.keystore_filepath

searchguard.ssl.transport.keystore_alias

searchguard.ssl.transport.keystore_password

searchguard.ssl.transport.truststore_type

searchguard.ssl.transport.truststore_filepath

searchguard.ssl.transport.truststore_alias

searchguard.ssl.transport.truststore_password

searchguard.ssl.transport.enforce_hostname_verification

searchguard.ssl.transport.resolve_hostname

searchguard.ssl.transport.enable_openssl_if_available

searchguard.ssl.http.enabled

searchguard.ssl.http.keystore_type

searchguard.ssl.http.keystore_filepath

searchguard.ssl.http.keystore_alias

searchguard.ssl.http.keystore_password

searchguard.ssl.http.truststore_type

searchguard.ssl.http.truststore_filepath

searchguard.ssl.http.truststore_alias

searchguard.ssl.http.truststore_password

searchguard.ssl.http.clientauth_mode

searchguard.authcz.admin_dn

searchguard.cert.oid

searchguard.config_index_name

How do I Secure the TLS Configuration in API Gateway?

Securing the TLS configuration in API Gateway involves securing the TLS configuration for API Gateway server ports
and API Gateway UI ports.

To secure TLS configuration in API Gateway

1. Secure the TLS configuration of the API Gateway server ports.
   1. Restrict the TLS version by adding the following setting:
      watt.net.jsse.server.enabledProtocols=TLSv1.2
      This specifies the SSL protocol versions that API Gateway supports when acting as a server handling inbound requests. Java Secure Socket Extensions (JSSE) is required to support TLS 1.1 or 1.2. For more information about configuring portsnto use JSSE, see https://documentation.softwareag.com/webmethods/integration_server/pie10-5/10-5_Integration_Server_Administrators_Guide.pdf
   2. 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
   3. Specify a list of secure cipher suites.
      For details about the recommended cipher suites, see the cipher suite recommendation by IANA organization or the https://documentation.softwareag.com/webmethods/integration_server/pie10-5/10-5_Integration_Server_Administrators_Guide.pdf.
   4. 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
       
2. Secure the TLS configuration of the API Gateway UI ports.
   1. Enable TLSv1.2 by adding the following line to the properties file com.softwareag.catalina.connector.https.pid-apigateway.properties located in the directory SAG_root/profiles/IS_default/configuration/com.softwareag.platform.config.propsloader.
      sslEnabledProtocols=TLSv1.2
   2. Specify a list of secure cipher suites by adding the following line to the properties file com.softwareag.catalina.connector.https.pid-apigateway.properties located in the directory SAG_root/profiles/IS_default/configuration/com.softwareag.platform.config.propsloader.
      ciphers="List of Secure Cipher_Suites"
      For details about the recommended cipher suites, see the cipher suite recommendation by IANA organization (https://ttps://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.
   3. 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.
 

How do I Configure a Secure Communication Channel between API Gateway and API Portal?