Web Service Applications › WS_API - Web Services API Application

WS_API - Web Services API Application

Latest version: 1.0.20-1

This section contains the following topics:

Functional Overview

CA AppLogic® for System z Web Services 'WS_API' Application Boundary Properties

Application Resources

Operation

Application Architecture

Configure

HTTP Mode

HTTPS Mode

VPN Mode

Notes

Functional Overview

The WS_API application provides a web service interface to one or multiple grids through a Representational State Transfer (REST) based service. Any one of the following access methods can be used with the WS_API REST interface:

• HTTP : Simple HTTP based REST API calls.
• HTTPS : Secure HTTP based REST API calls.
• VPN : HTTP requests are sent through a secure VPN tunnel.

CA AppLogic® for System z Web Services 'WS_API' Application Boundary Properties

Important! The IP addresses configured in the vpn_ip, usr_ip and net_ip properties must be IP addresses available on your CA AppLogic® for System z grid. You can find them, together with the netmask, gateway, and DNS servers on the dashboard of your grid. We are working to make it possible for CA AppLogic® for System z to provide these addresses automatically.

Application Resources

"WS_API" Application

Application Volumes

The application itself uses several volumes. They are part of the application and are already configured into the appliance instances.

Operation

Before starting the WS_API application, it needs to be configured to access the grids that are going to be managed through the web service interface. This involves creating a vdcs.conf file inside the data sub-directory on the conf volume. A pair of private/public keys need to be created and a user needs to be setup on the targeted grid controller with the generated public key. For information about how to populate vdcs.conf and how to setup ssh keys and create a grid user for the web service API see the configure section.

The WS_API can be configured to work in one or a combination of the following modes:

Using HTTP

In this mode, the REST API can be accessed through the regular HTTP based interface.
For example, curl "http://usr_ip/api/v1/app/list?vdc=controller_name".
To start the application to work in this mode, it is required to set the mandatory properties to appropriate values and the http_mode property to http. For more information about how to set the application up to work in this mode,refer to the configure section.

Using HTTPS

In this mode, the REST API can be accessed through the Secure HTTP based interface.
For example, curl -k -E /path/to/client_key.pem "https://usr_ip/api/v1/app/list?vdc=controller_name".
To start the application to work in this mode, it is required to set the mandatory properties to appropriate values and the http_mode property to https. You may also set the opts property with the options shown in the properties table above for your certificate to be signed accordingly. After the application is started successfully, the client certificates must be copied from the ssl-keys subdirectory within the conf volume to the client application or browser to be used to access the WS_API. For more information about how to set the application up to work in this mode, refer to the configure section.

Using vpn tunnel

In this mode, a secure VPN tunnel is created between the in_vpn VPN server within the application and a VPN client on the client side. Once the tunnel is successfully created using one of the different VPN tunneling types available, the REST API can be accessed through the regular HTTP based interface.
For example, curl "http://usr_ip/api/v1/app/list?vdc=controller_name".
To start the application to work in this mode, it is required to set the mandatory properties to appropriate values, set the vpn_ip property and set the vpn_standby to 0. By default, vpn_ports is set to 80,443 to allow connections to ports 80 and 443 (http and https respectively) and vpn_type is set to certificate to allow a VPN client to connect to the VPN server in the application using a SSL certificate based tunnel. You may also set the in_standby property to 1 so that only requests through the VPN tunnel are allowed. Any API requests from outside of the VPN tunnel are dropped. For more information about how to set the application up to work in this mode, refer to the configure section.

Application Architecture

The Web Services 'WS_API' application infrastructure has the following components:

• One firewalled input gateways - supports HTTP- and HTTPS-based requests
• One VPN server - serves API requests through a secure tunnel to the VPN client on the client side
• A web server - serves REST API requests
• A centralized configuration file storage
• A centralized log - collects log and stores temporary data
• A firewalled net gateway to connect with grids

  

Configure

This section describes how to configure the WS_API application to start in one of the three different modes of operation.

To configure the WS_API application

1. Provision the WS_API using the app provision wizard in the CA AppLogic® for System z GUI or use the app provision command in the shell, do not set any properties yet. Verify the wizard is configured not to start the application after provisioning or use the --skipstart option if the command line is used.

   app provision WS_API ws_api_instance --skipstart 
   

2. Manage the data volume of the application:

   vol manage ws_api_instance:conf 
   

3. In the data sub-directory, verify a file named vdcs.conf exists.

   cd /mnt/vol/data
   ls vdcs.conf 
   

   This file consists of information necessary to access the grids that will be managed through the REST API.

4. Open the file using the vi text editor:

   vi vdcs.conf 
   

5. Edit the file using the template as a reference:

   vdcs
      { 
      vdc controller_name : host = controller_ip or FQDN
         { 
         location  = "city, state, country" 
         latitude  = latitude 
         longitude = longitude 
         } 
   
   #  vdc controller_name : host = controller_ip or FQDN 
   #     { 
   #     location  = "city, state, country"
   #     latitude  = latitude
   #     longitude = longitude
   #     }
      } 
   

6. Enter the relevant information for the grids that will be accessed with the API. To add information for an additional grid, uncomment the lines (remove the #) and add the information for the second grid. More grids can be added by repeating vdc block within the vdcs {...} section. Also note that setting values for latitude and longitude is optional.
7. Save and exit the text editor.
8. Generate a public/private key pair for ssh access to the grids configured in the vdcs.conf.

   To generate the key pair:

   ssh-keygen -t dsa -f /mnt/vol/data/gridkey
   When prompted to enter a password press enter. DO NOT ENTER A PASSWORD.
   chmod 600 /mnt/vol/data/gridkey*
   chown 99:99 /mnt/vol/data/gridkey*
   

9. Copy the public key:

   cat /mnt/vol/data/gridkey.pub 
   

10. On the grid controller, create an API user with this key as sshkey on each of the grids:

    user create api@domain.com pwd=- sshkey="ssh-dsa AAA.................xyz" 
    

    The user is created.

11. Setup access for the newly created user:

    grid modify_acl local:user:api@domain.com=grid_administrator
    

    Note: Other access levels can be used (see RBAC guide for more info) but be aware this will limit the commands the ws_api can run.

12. Exit the volume manager.

    The application boundary can now be configured to work in either one of the three operating modes.

HTTP Mode

The WS_API application provides a web service interface to one or multiple grids through a Representational State Transfer (REST) based service. The HTTP access method enables simple HTTP based REST API calls.

Note: This mode should be used with extreme caution. There is no security check involved in this mode and anybody can create an API request without any authentication. Also, all the traffic between the client and the ws_api_instance application is in plaintext.

To configure the application in HTTP mode, set the http_mode property to http along with setting the mandatory properties to appropriate value. For example,

app config ws_api_instance usr_ip=usr-ip net_ip=net-ip netmask=netmask gateway=gateway dns1=dns1 dns2=dns2 http_mode=http 

The application may now be started using the app start command or by using the "Start Application" button in the GUI.

HTTPS Mode

The WS_API application provides a web service interface to one or multiple grids through a Representational State Transfer (REST) based service. The HTTPS access method enables secure HTTP based REST API calls.

To configure the application in HTTPS mode

1. Set the http_mode property to https (default).
2. Set the mandatory properties to appropriate values.
3. Set the opts property to generate a custom SSL certificate.

   Note: If opts is left blank then, a generic SSL certificate is generated on application start. The http_mode and the allowed_hosts property settings can be left set to their default values. For example,

   app config ws_api_instance usr_ip=usr-ip net_ip=net-ip netmask=netmask gateway=gateway dns1=dns1 dns2=dns2 opts=ssl_country=Country,ssl_state=State,ssl_local=City,ssl_org_name=Organization,ssl_org_unit=Unit,ssl_common_name=Common Name,ssl_email_address=company@domain.com,ssl_export_pass=Passkey 
   

4. Start the application using the app start command or by using the "Start Application" button in the GUI.

   The first time the application is started, a PEM formatted client key consisting of the client certificate and private key named api_client.pem and a PKCS12 formatted equivalent key for browsers named api_client.p14 is created in the /mnt/config/ssl_keys/keys/ directory of the conf volume. The api_client.p14 key file can be used for any browser based API access and the api_client.pem key for any non-browser based API access.

To generate any additional client certificates

1. Log in to the main.api_srv component of running ws_api_instance.
2. Change directory to /mnt/config/ssl_keys.
3. Generate a private key for a 'api' user account. openssl genrsa -out keys/api_client2_privkey.pem 2048
4. Generate a certificate signing request for the CA to sign. openssl req -new -key keys/api_client2_privkey.pem -out keys/api_client2_request.csr.
5. Sign the CSR with our CA. openssl x509 -req -days 365 -in keys/api_client2_request.csr -CA CA/CA_cert.pem -CAkey CA/private/CA_key.pem -CAserial CA/CA_cert.srl -out keys/api_client2.cer.
6. cat the api_client2_a.pem and cert into one for use as a command line SSL/PEM key. cat keys/api_client2_privkey.pem keys/api_client2.cer > keys/api_client2.pem.
7. Export the key in a format that can be used by common web browsers. openssl pkcs12 -export -in keys/api_client2.cer -inkey keys/api_client2_privkey.pem -out keys/api_client2.p14.

VPN Mode

The WS_API application provides a web service interface to one or multiple grids through a Representational State Transfer (REST) based service. The VPN access method enables HTTP requests to be sent through a secure VPN tunnel.

To configure the application in VPN mode

1. Set the vpn_ip to a desired IP address and the vpn_standby is disabled that is, set to 0.
2. Set in_standby to 1to restrict access through VPN set.

   For example:

   app config ws_api_instance usr_ip=usr-ip vpn_ip=vpn-ip net_ip=net-ip netmask=netmask gateway=gateway dns1=dns1 dns2=dns2 vpn_standby=0 in_standby=1 
   

3. Start the application by using the app start command or by using the "Start Application" button in the GUI.

   After the application starts, the VPN server appliance generates necessary server certificates and key files if these files are not already present.

4. Log in to the appliance and execute the security.sh script located in /appliance directory to generate the client certificates and key.

   [ws_api_instance:main.in_vpn appliance]# ./security.sh generate_client
   Generated client SSL cerfiticate and key file.
   ==============================================
   These files, with CA certificate file, should be copied to VPN server into 
   /client/ subdirectory of data volume or fs-mounted volume.
   Path to client files (client.a1c65e2bae3d0b57) should be specified in auth_path property.
   Location of files:
   client certificate: /mnt/data/server/client.a1c65e2bae3d0b57.crt
   client key file: /mnt/data/server/client.a1c65e2bae3d0b57.key
   CA certificate file located at /mnt/data/server/ca.crt
   

   The client certificate (for example, client.xxxxxxxxxxxxxxxx.crt) and key file (for example, client.xxxxxxxxxxxxxxxx.key) are generated in the client sub-directory and the CA certificate (ca.crt) is generated in server sub-directory of the conf volume.

5. Copy the certificates into the remote VPN client appliance inside the /client/ subdirectory on the data volume or nfs-mounted volume.

Notes

Open source and third-party software used

The following open source third-party software is installed on the code volume.