Author: Raj, Gokul (gora@softwareag.com)
Supported Versions: 10.2
webMethods API Gateway tutorial
Overview of the tutorial
This tutorial explains how API Gateway and the related inter components can communicate with each other in a secure transport protocol that is using HTTPS. Let us go through the following steps in detail:
- Securing API Gateway server using HTTPS
- Securing API Gateway UI (web application) using HTTPS
- Securing API Gateway Reverse Invoke setup using HTTPS
Required knowledge
This tutorial assumes that the reader has,
- a basic understanding of API Gateway and its related components like UI, Elasticsearch, etc
- a basic understanding of java security using Keystore and Truststore certificates
- a basic understanding of API Gateway administration configurations
Why?
SSL creates a secure connection between servers and clients over the web and internal network, safeguarding and allowing sensitive data to be securely transmitted. The HTTPS (Hypertext Transfer Protocol Secure) is an internet communication protocol that protects the integrity and confidentiality of data between the user's computer and the site. Seeing “https://” in the URL means “this is a website, and it’s using SSL to encrypt data and authenticate the website”. The data sent over HTTPS is secured via TLS which provides protection using encrypted channel.
Prerequisite steps
Complete the below prerequisites to make you ready to get into the details securing API Gateway and its components using HTTPS.
- Install API Gateway standard and advanced edition of version 10.2 and above (for on-premise setup)
Details
In this tutorial, to secure the connections between the components of the API Gateway, we would use keystore and trustore self-signed certificates.
Step 1: Securing API Gateway server using HTTPS
This section explains generating certificates, configuring the generated certificates in Integration Server by adding them, creating a HTTPS port in API Gateway and configure the keystore and truststore settings in API Gateway administration configuration to achieve securing API Gateway server using HTTPS protocol.
Creating keystore
First create a new keystore with self-signed trusted certificate with corresponding public/private keys. You can use keystore.jks and truststore.jks in folder C:\APIGateway_105\common\conf if you don't want to generate a one and use the out of the box provided keystore and truststore files.
Open a command window and run the following commands to generate new keystore and truststore.
$> keytool -genkey -v -keystore https_keystore.jks -alias HTTPS_KEYSTORE -keyalg RSA -keysize 2048 -validity 10000
When prompted, provide a password for e.g "manage" and other necessary details. This will generate the keystore file gateway_keystore.jks
Creating certificate
Next run the below command to generate a certificate signing request.
$> keytool -certreq -v -alias HTTPS_KEYSTORE -keyalg rsa -file C:\APIGateway_105\common\conf\https_gateway.cer -keystore C:\APIGateway_105\common\conf\https_keystore.jks
When prompted, provide a password for e.g "manage". This will create a certificate signing request file https_gateway.cer.
Next run the below command to generate the self-signed certificate from the certificate signing request.
$> keytool -exportcert -v -alias HTTPS_KEYSTORE -file C:\APIGateway_105\common\conf\https_gateway.cer -keystore C:\APIGateway_105\common\conf\https_keystore.jks
When prompted, provide a password for e.g "manage". A certificate will be generated and available in the location specified in the command line.
Creating truststore & importing the Certificate
Then create a truststore file and import the generated certificate into the truststore file by running the below command.
$> keytool -importcert -alias HTTPS_TRUSTSTORE -file C:\APIGateway_105\common\conf\https_gateway.cer -keystore C:\APIGateway_105\common\conf\https_truststore.jks
A truststore file https_trustStore.jks will be created with the imported certificate.
Configuring keystore and truststore in API Gateway
Next step, we will configure the generated keystore and truststore files in the API Gateway. Login to API Gateway and go to Administration → Security → Keystore/Truststore. Click Add keystore button. Provide the details as below. Select the https_keystore.jks file created at C:\APIGateway_105\common\conf and click OK.
It will throw some warning saying provide the proper password for Alias. Provide the password for the keystore file, in our case it is "manage", and click Save.
Then click Add truststore button and provide the details to add the truststore.
After adding the keystore and truststore files, go to Configure keystore and truststore settings section and provide the details of keystore and truststore we have configured and click Save. The API Gateway will by default use the configured keystore and truststore files for keys and certificates for any HTTPS communication in and out.
Creating HTTPS Port in API Gateway
In this step we will create a HTTPS port in API Gateway and configure the keystore and truststore aliases for that. Go to Administration → Security→ Ports and click Add ports. Select HTTPS and click Add. Provide required details and expand Listener specific credentials. Select the created truststore and keystore and click Add.
The HTTPS port is added. Enable it by clicking the X mark.
Now API Gateway server is ready to accept requests over HTTPS port 8866.
Invocation of API over HTTPS port
The below screenshot shows an API in API Gateway is invoked using HTTPS port.
Step 2: Securing API Gateway UI (web application) using HTTPS
In this section we will discuss how to configure HTTPS port for API Gateway UI (web application). By default webApp exposed over HTTPS enabled port 9073. Use the default port or follow this section to configure custom keystore and port. To enable SSL and expose API Gateway webApp in HTTPS protocol the following steps need to be done.
Generate Keystore
Create a new keystore with self-signed trusted certificate with corresponding public/private keys by using the above steps or use the out of the box keystore.jks under folder C:\<gatewayInstallation dir>\common\conf.
Configure Keystore and Port
Go to C:\APIGateway_105\profiles\IS_default\configuration\com.softwareag.platform.config.propsloader and open the property file com.softwareag.catalina.connector.https.pid-apigateway.properties. Modify the below properties with the keystore, passsword and port details.
keystoreFile=<generated_keystore_path>/keystore.jks
port=9073 (https port in which you want to expose webApp)
@secure.keystorePass=password (password used while creating the keystore file)
Configure the above entries to expose the web application over HTTPS port. Now the web application can be accessed using the HTTPS port.
Step 3: Securing API Gateway Reverse Invoke setup using HTTPS
In this section we will see how HTTPS communication can be configured in the Reverse Invoke setup.
Configuring External and Registration port
Go to Administration → Security → Ports and click Add ports. Select type API Gateway external and click Add. Provide the external port, select HTTPS protocol and enter external port alias. Add keystore and kruststore aliases if required under Listener specific credentials. Refer the below image.
Enter required registration port and alias for registration listener and then Add. Select HTTPS protocol and add Keystore and Truststore if required.
Click Add, this will create the external and registration port and by default both these ports were disabled.
Click the X to enable the ports as shown in the below image. Now, the port for reverse invoke is created and enabled.
Configuring Load balancer URL
In this step the external port would be configured in the Load balancer URL so that the API's endpoints will have the external port as one of their endpoint. Go to Administration → General → Load balancer. Add the HTTPS load balancer URL and click Save as shown in the image.
API invocation using Reverse invoke
Create an API, add HTTPS protocol in Transport Policy and activate. In Technical information section, HTTPS enabled reverse invoke endpoint is exposed for the created API as shown in the below image.
Now invoke the API from a client. A sample invocation is given in the below image.
Limitations
- Kibana server (Dashboard) can also be secured using HTTPS protocol, but the support for API Gateway to communicate to Kibana over a secured channel is missing and will be fixed in the upcoming release (on or above 10.5)
Troubleshooting
| # | Error / Exception | Message | Possible Solution |
|---|---|---|---|
| 1 | OpenSSL Error | openssl is not recognized as an internal or external command | Download OpenSSL and add Environment Variable will solve the problem. Download link is placed in the Downloadable artifacts section. |
| 2 | OAuth Get Token Exception | Improper URL(https://<host>:5555/<rest>/<apiname>) during OAuth token access during API Tryout in API Portal | In IS go to Settings → Remote Servers. Test the connection by clicking play button under Test. If it fails, then change the port to 7777(https enabled port) by clicking local in alias and test again |
References
Downloadable artifacts
Learn more
- Please refer Securing Elasticsearch for API Gateway 10.2 for securing Elasticsearch using SearchGuard.
