Adding the Secure Gateway
The basic concept about using Secure Gateway is represented in the following chart.
The above picture shows IBM Cloud where all applications and services are located, including the Secure Gateway Service and other customer applications. The IBM Services for Managed Applications represents the IBM services provided along with the infrastructure that provides hosting for Secure Gateway Client along with other customer solutions or resources. These two components would require configuration to allow data traffic securely between the applications in IBM Cloud with remote resource located in IBM Services for Managed Applications.
Two ways of configuring Secure Gateway Service are shown below:
1. IBM Services for Managed Applications: User application resides on the IBM Cloud, while the target or destination resides on the IBM Services for Managed Applications network.
2. Cloud: User application resides on the premises network, while the target or destination resides on the IBM Cloud.
For effects of the recipe we will assume we have an API running on IBM Cloud (area demarked by The Cloud) and on the premise network our destination is an SAP instance that we will connect to retrieve data via Netweaver Gateway and located in IBM Services for Managed Applications.
To set up the Secure Gateway Service perform the following steps:
1. Login to your IBM Cloud (we assume an account is already set in place)
2. Under Catalog and under Integration select Secure Gateway.
3. Based on your type of account select “Features”, “Pricing Plans” and hit the Create button to complete adding the service to the account.
4. Once the Create button has been pushed, the browser will show a screen with the Secure Gateway Dashboard:
5. Click on Add Gateway box and small window will show Add Gateway screen. Please provide a name for the gateway and leave the Require security token to connect clients enabled. Leave the 90 days default for token expiration and click on Add Gateway box.
Once steps above are completed a gateway is added to your dashboard. Proceed now to the Getting the Secure Gateway Client instructions.
Getting the Secure Gateway Client
1. Once a gateway has been added, the Dashboard window is updated showing a green box labeled ‘Connect Client’ as shown on the below screen.
2. The screen above shows Clients (0) are connected and a connection it is required for a remote resource to be visible for the Secure Gateway. Click on Connect Client box to add a connection.
3. A new screen will come up to ask how to connect to the Secure Gateway, as shown in below screen. Depending on the operating system where the remote resource is located, a different Secure Gateway Client code needs be obtained.
- Mac OSX
- RHEL 6+
- Ubuntu Z-Linux
- Ubuntu 14+ PPC
- Ubuntu 14+
- AIX 7.1+
The screen below it shows the Gateway ID and Security Token. These two values will be needed later when configuring the software after the code has been downloaded and installed, so make sure you have noted them down somewhere.
For the sake of this example, it is assumed that the Secure Gateway Client will be deployed on a Red Hat installation. Notice that there are two methods to be utilized to access the installation code. Both options are marked in red on the screen below. The first option will copy the HTTPS link to memory and it must be pasted into an opened browser to begin the download. The second option will force the source code to immediately download to the IBM Services for Managed Applications network.
Note on above screenshot RHEL 6+ is the client to install for this exercise. Whatever red box option is selected, please make sure the RHEL 6+ rpm file gets downloaded in your target system. As of July 2018, IBM Cloud currently provides the ibm-securegateway-client-1.8.0fp6+client_x86_64.rpm file.
If the file is not delivered to the VM that would host the Secure Gateway Client, please copy it and proceed with its installation as explained on the next step.
Installing Secure Gateway Client
Assuming the rpm file is now present on the VM or Hosting environment in IBM Services for Managed Applications, the following steps should be performed.
Please locate and move the command line prompt to the folder where ibm-securegateway-client-1.8.0fp6+client_x86_64.rpm it is located. The following screen shows an example of file location after issuing ls -l command.
Note: If one of the below steps is skipped or if data is not currently available, please continue with installation and later edit the configuration file to update accordingly. How to edit this file will demonstrated later below on Secure Gateway Client Configuration step.
1. Make sure you are in the directory where the file was downloaded or copied, issue the following command:
rpm -ivhf ibm-securegateway-client-1.8.0fp6+client_x86_64.rpm
2. Please answer Y (Yes) on the the question: “Stop and restart the client during install or upgrade? [y/n]?”
It was mentioned on a prior step that it was required to have a copy of the Secure Gateway ID and Security Token elements as they were required at this step.
3. On the question “Enter the gateway IDs, separated by spaces:”, please provide the security ID when prompted to enter it.
4. On the question “Enter the gateway ID security tokens separated by spaces, enter ‘none’ for no security token:”, please provide the Token ID previously obtained. It is assumed token was an option selected to maintain additional security.
5. On the question “Enter log level for each gateway separated by spaces. Enter ‘none’ or ‘INFO’ for default log level:”, please type INFO followed by the enter key.
6. On the question “Supply ACL File each gateway separated by spaces. Enter none if no ACL file:”, please press the enter key to continue. Later it would be explained how to create the ACL file and added it to the configuration file.
7. On the question “Would you like to use the client UI (Y/N):”, please enter Y to indicate UI client would be needed. This option will allow to have a web application available to manage certain administrative functions of the Secure Gateway Client.
8. On the question “Please provide the port the run client UI, default is 9003:”, please press enter key to accept 9003.
9. Once the above questions are responded or skipped, the installation code will begin deploying and configuring the new secure gateway environment. As it begins this deployment process the following text would be shown on screen:
“[postinst] INFO: Calling node install for production modules from /opt/ibm/securegateway
[ …………..] / fetchMetadata: sill mapToRegistry uri https://registry.n“
After the above described steps are executed, the Secure Gateway Client code will attempt to launch and run; however, before an actual data traffic can run through the gateway, end-points will need to be configured to indicate what it is allowed or disallowed to connect via this process. An ACL file will serve for this purpose and it must be configured accordingly as explained on the next step.
Creating/updating Access Control List file (ACL)
Steps executed for this update will be performed via command line rather than going through the Secure Gateway Client UI, as in some cases access to it might not be available at the remote VM/Host due to firewall rules or network configurations.
Again, it is assumed the Secure Gateway Client has been installed on RHEL 6+ and installation of the code is located in /opt/ibm/securegateway/client
1. Based on above given path, if an ACL file exists please open such a document. If it does not exit, please create the new file and give the following name ACLFile.txt. (if other name is given please keep reference of it as it is needed later).
The current supported commands on ACL file are:
- acl allow [<hostname>]:[<port>]
- acl deny [<hostname>]:[<port>]
- no acl [<hostname>]:[<port>]
- no acl
- show acl
We will focus on acl allow [<hostname>]:[<port>]
2. While editing the file add the following line: acl allow [<hostname>]:[<port>], that must be added for each end-point we want the secure gateway to allow traffic to. In our case we are interested in connecting to SAP ERP via a OData protocol enabled by NetWeaver Gateway, located in 192.168.100.10, port 8010 in IBM Services for Managed Applications. we add:
acl allow 192.168.100.10:8010
Below picture represents what it is set
Note: In IBM Services for Managed Applications there are several firewall policies enabled that disable many ports, therefore if the port 9003 on the VM where the Secure Gateway Client is installed it is not accessible via its own IP, it would require to add another entry in the ACL file to allow the localhost via port 9003 to allow access to the Secure Gateway UI. Please add the following line if the case applies to you:
acl allow 127.0.0.1:9003
3. After adding the above lines, the file will look like this:
acl allow 192.168.100.10:8010
acl allow 127.0.0.1:9003
4. Update the hostnames and/or IPs that your Secure Gateway Client must allow traffic to. Save your file to keep these changes.
Note: If you assigned a different name to this file please remember it as it is needed later on the next step.
Secure Gateway Client Configuration
Before you edit the configuration file please stop the service by issuing the follow command:
initctl stop securegateway_client
If there was client running you will get: securegateway_client stop/waiting, if no client is running you will get: initctl: Unknown instance:
Proceed with the following steps:
1. Locate sgenvironment.conf on /etc/ibm path.
2. Edit the above file.
Please note the file contains variables that address specific aspects of the configuration:
RESTART_CLIENT: Stop and Restart the client during install or upgrade
GATEWAY_ID: Gateway ID to connect to Secure Gateway Server in Bluemix
SECTOKEN: Token generated at the Secure Gateway server used to authenticate the client connection.
ACL_FILE: Path and location of Access Control List file used to allow connections.
LOGLEVEL: Level of messages generated in the log. (This log can be accessed via an option on the UI web page) Options are INFO, DEBUG, ERROR, TRACE.
USE_UI: Whether to launch a UI client.
UI_PORT: Port used by the UI client
LANGUAGE: Language used.
Note: Default values and others are included in file for each variable used.
3. If you missed entering the Gateway ID during installation, please enter the Gateway ID and assign it to GATEWAY_ID variable.
4. If you missed entering the Security Token during installation, please enter the generated token and assign it to SECTOKEN. Make sure no extra characters are added.
5. On the ACL_FILE variable please add the ACL file name you created on prior steps including the full path. For example if you kept same path and filename this is how the variable would be assigned:
6. Save the file.
Continue with the next step.
Start the Secure Gateway Client
As it is still assumed the installation of Secure Gateway Client has been performed in RHEL 6+, the following command can be issued to start the Client.
1. Enter initctl start securegateway_client
2. As an example response the system will show an output as follow:
securegateway_client start/running, process 123943.
Now that client side has been configured we turn our attention back to the Secure Gateway Service on IBM Cloud, please proceed to the next step to complete its configuration.
Finishing Configuring Secure Gateway Server
If the prior steps were executed accordingly, and all network settings are in place, the Secure Gateway Service should register and show there is a client connection active in IBM Services for Managed Applications, as it is shown on the below screen
Observe the Secure Gateway Server dashboard shows one client connected as demonstrated by the objects surrounded by the read squares.
To visualize the above and complete the configuration of the secure gateway at the server perform the following the next steps:
1. Login to your IBM Cloud (https://console.bluemix.net/)
2. Under your Catalog and under Integration, select Secure Gateway.
3. Click on Destinations green box button.
4. Please note the dashboard is showing the recently configured client connected to the Secure Gateway Server.
5. On same dashboard screen, click on Destinations (0) link as shown below
6. Click on the + of the green square to add a destination. (End-point the Secure Gateway Server should allow connections)
7. The Add Destination screen will come up where Guided Setup or Advance Setup can be selected. For the purpose of this exercise we will use Advance Setup option. Upon selection of the given action, a new screen will show up presenting the following content.
8. It assumed the remote resource is on premises of IBM Services for Managed Applications (not in Bluemix), therefore the On-Premises Destination radio-button is selected.
9. On Destination name, please provide a name to reference such a connection. For the exercise my APP is assigned.
10. On Resource Hostname, please provide one of the entries added to the ACLFile where the Secure Gateway must allow traffic to. For this exercise we are interested in connecting to SAP environment in IBM Services for Managed Applications and obtain data via NetWeaver service. Our IBM Services for Managed Applications resource instance is located on 192.168.100.10.
11. On Resource Port, please enter the port number you enabled in the ACL file. For the exercise we use 8010 where the SAP NetWeaver service provides the data in form of a JSON object. It is not part of this exercise to demonstrate how a service on SAP via NetWeaver is configured.
12. From the drop-down option please select the appropriate protocol your service or resource allows. For this exercise HTTP it is selected. Other protocols available are: TCP, TLS, HTTPS and UDP but we are not covering them for our exercise.
Note other settings are left as they are. Depending of levels of security or connections these values would require additional configuration.
13. This is how the screen would look like after the entries have been provided accordingly to the exercise.
Please click on Add Destination button to save the changes.
14. After save the dashboard will present the screen reflecting the recently destination added. On the destination please click on setting icon to display the configuration as shown below by the red square:
15. Once the icon is clicked a new window will display information as follows:
Very important: Please note on the above response screen the Cloud Host : Port text shown within the red rectangle. You need now to be aware that Cloud Host and Port are the values required within your solution or application at IBM Cloud to connect to the remote service.
Making use of the configured Secure Gateway Server
The following lines of code are from an API that pulls data from a SAP system in IBM Services for Managed Applications via the NetWeaver Gateway service and through a REST call. The segments of code below are from an API implementation on Node.js Express. In particular these lines of code are extracted from server.js file of a current deployment of a proof of concept solution. Here, we are only focusing on presenting the lines of code needed to define credentials, define connection object, connect to SAP through a REST call, and to obtain back a JSON object; all of this while connecting via the recently configured Secure Gateway service in Bluemix.
1. Adding Client() to the code.
2. Adding user access. You will need to determine with your SAP administrator what are the user and password to connect to the system.
3. Define connection to ERP SAP. Below, It supports JSON and XML.
4. Retrieving data from the SAP via ODATA protocol and NetWeaver service
The JSON.stringify(data)) section on the code above will contain the data returned by the service from SAP and that you can now process within your own implementation.
Please note that cap-sg-prd-3.integration.ibmcloud.com:18503 -Host and Port- are the values obtained from the Secure Gateway Server dashboard when looking at the destination target object. The above code demonstrates how the solution using Secure Gateway Service can securely connects to a remote SAP instance (or resource) via the shown host and port. Also note the rest of the URI path is what the SAP NetWeaver gateway provides to access the ODATA element via the REST call. Check with your SAP administrator or development team to determine what service is available to connect to your solution.