Configuring TLS for API BaaS

Edge for Private Cloud v. 4.17.05

TLS (Transport Layer Security, whose predecessor is SSL) is the standard security technology for ensuring secure, encrypted messaging across your API environment. You can configure TLS on API BaaS Portal and API BaaS Stack nodes.

The following image shows a typical deployment diagram for API BaaS with a single BaaS Portal node and three API BaaS Stack nodes.

Developers use a browser to make requests to the Portal. By default, the requests use the HTTP protocol on port 9000 of the Portal node.

This deployment includes a load balancer between the Portal and Stack nodes. In this configuration, the Portal makes HTTP requests to the load balancer, and the load balancer then forwards the requests to one of the Stack nodes. This is the recommended deployment environment for a production system.

TLS configuration options

When configuring TLS for API BaaS, you have several options:

Configure TLS on the Portal and on the load balancer for the Stack nodes

In this configuration, developers use the HTTPS protocol to access the Portal, and the Portal running in the browser uses HTTPS to make requests to the Stack nodes through the load balancer. The load balancer uses HTTP to access the Stack nodes.
Configure TLS on the Portal, load balancer, and Stack nodes

For added security, configure the load balancer to use TLS to access the Stack nodes.
Configure TLS on the Portal and on a single Stack node

In a small environment, such as in a testing or development environment, you might only have a single Stack node, meaning there is no need to include a load balancer. In this configuration, configure TLS on both the Portal and the Stack nodes.
Configure TLS on a load balancer for the Portal

One option not shown above is to use a load balancer in front of the Portal node. In that configuration, you can configure TLS on the load balancer, and optionally on the connection between the load balancer and the Portal.

Ensure that the TLS port is open

The procedures below configures TLS on the default Portal port of 9000 and Stack node of 8080. However, you can change this port if desired.

Regardless of the port that you use, you must ensure that the port is open on the node. For example, you can use the following command to open port 8443:

$ iptables -A INPUT -m state --state NEW -m tcp -p tcp --dport 8443 -j ACCEPT --verbose

Configuring TLS on the API BaaS Stack

By default, TLS is disabled for the API BaaS Stack. You then access the BaaS API over HTTP by using the IP address or DNS name of the Stack node and port 8080. For example:

http://stack_IP:8080

Alternatively, you can configure TLS access to the BaaS API so that you can access it in the form:

https://stack_IP:8080

In this example, you configure TLS access to use port 8080. However, port 8080 is not required - you can configure the Stack to use a different port. The only requirement is that your firewall allows traffic over the specified port.

The Stack can only support one type of request (HTTP or HTTPS) over a single port. Therefore, if you configure HTTPS access on port 8080, you cannot use HTTP to access port 8080. If you configure the Stack to use port 8443 with HTTPS, then the Stack will no longer listen on port 8080.

Use the following procedure to configure TLS access to the Stack:

Generate the keystore JKS file containing your TLS certification and private key. For more see Configuring TLS/SSL for Edge On Premises.
Note: Ensure that the password on the keystore and for key are the same.
Copy the keystore JKS file to a directory on the Stack node, such as /opt/apigee/customer/application. The directory must be accessible to the 'apigee' user.
Change ownership of the JKS file to the 'apigee' user:
> chown apigee:apigee /opt/apigee/customer/application/keystore.jks

where keystore.jks is the name of your keystore file.
Edit the /opt/apigee/customer/application/usergrid.properties file to set the following properties, including the path to the JKS file and the password on the keystore and key. If that file does not exist, create it:
tomcat-server_scheme=https
tomcat-server_secure=true
tomcat-server_ssl.enabled=true
tomcat-server_keystore.type=JKS
tomcat-server_keystore.file=/opt/apigee/customer/application/keystore.jks
tomcat-server_keystore.password=password
tomcat-server_keyalias=keystore_alias
tomcat-server_clientauth.enabled=false
tomcat-server_ssl.protocols=TLSv1,TLSv1.1,TLSv1.2
# By default, TLS access uses port 8080.
# Use this property to specify a different port.
# tomcat-server_port=8080

Warning: The password value has to be in clear text. Therefore you should protect usergrid.properties from unauthorized access.

Use the tomcat-server_keyalias property to specify the keystore alias. You set the key alias at the time you created the key. For example, you can set it by using the -alias option to the keytool command.

Use tomcat-server_ssl.protocols to set the TLS protocols supported by the Stack. For a list of protocols supported by Java 8, see http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#jssename.
Configure the Stack node:
> /opt/apigee/apigee-service/bin/apigee-service baas-usergrid configure
Restart the BaaS Stack:
> /opt/apigee/apigee-service/bin/apigee-service baas-usergrid restart
Confirm that TLS is working by running the following cURL command on the Stack node using HTTPS:
> curl -k https://localhost:8080/status -v

If TLS is configured correctly, you should see a response containing status information.

If you configured TLS access over a port other than 8080, modify the command above to use the correct port.
Repeat on all Stack nodes.
If you have a load balancer in front of the Stack nodes, configure the load balancer to make requests to the Stack nodes over HTTPS. See the documentation on your load balancer for more information.

If the Portal makes direct requests to the Stack, configure the Portal to access the Stack over HTTPS as described in the following section.
Use the procedure below in "Configure API BaaS Stack nodes for TLS on the Stack or Portal" to ensure that the Stack node has the correct TLS URLs when generating user responses.

Configuring the Portal to access the Stack over TLS

The BaaS Portal running in a browser functions by making API calls to the BaaS Stack. If you configure the BaaS Stack to use TLS, then you must also configure the Portal to make those calls over HTTPS.

An API BaaS installation is typically configured to either:

Use a load balancer between the Portal and Stack nodes

Configure the load balancer to make requests to the Stack nodes over HTTPS. See the documentation on your load balancer for more information.

In this configuration, the Portal can access the load balancer over HTTP or HTTPS, depending on how you configure the load balancer. If the load balancer uses TLS, use the procedure below to configure the Portal to make requests to the load balancer of HTTPS.
Have the Portal make direct requests to the Stack

Configure the Portal to access the Stack over HTTPS as described below.

Use the following procedure to configure the API BaaS Portal to make API calls over HTTPS:

Configure TLS access on the BaaS Stack as described above, or on the load balancer for the Stack nodes as described in the documentation for your load balancer.
Edit /opt/apigee/customer/application/portal.properties to set the following property. If that file does not exist, create it:
baas.portal.config.overrideUrl=https://stackIP:port

Specify as the value of this property the IP address or DNS name and port of the API Stack node for a single node installation, or of the load balancer if you have a load balancer in front of the API BaaS Stack nodes.
Configure the Portal node:
> /opt/apigee/apigee-service/bin/apigee-service baas-portal configure
Restart the Portal by using the command:
> /opt/apigee/apigee-service/bin/apigee-service baas-portal restart
If you used a self-signed cert when configuring TLS access to the Stack above, your browser might not allow requests to the Stack from the Portal. If you see an error in the browser that HTTPS access to the Stack is not allowed, request the following URL in your browser, and add a security exception to allow access:
https://stackIP:port/status

Specify the IP address or DNS name and port of the API Stack node or load balancer.

Configuring TLS on the API BaaS Portal

By default, users access the Portal by making unencrypted HTTP requests over port 9000 on the Portal server. You can configure the portal to use HTTPS to encrypt the data send to and from the portal.

By default, you access the Portal over HTTP by using the IP address or DNS name of the Portal node and port 9000. For example:

http://portal_IP:9000

Alternatively, you can configure TLS access to the Portal so that you can access it in the form:

https://portal_IP:9443

In this example, you configure TLS access to use port 9443. However, port 9443 is not required - you can configure the Portal to use a different port.

The Portal can only support one type of request (HTTP or HTTPS) over a single port. Therefore, if you configure HTTPS access on port 9000, you cannot use HTTP to access port 9000. If you configure the Portal to use port 9443 with HTTPS, then the Portal will no longer listen on port 9000.

To configure TLS for the Portal:

Create a key file and cert file in PEM format.
Note: Ensure that there is no password/passphrase on the key or cert.
Copy the PEM files to a directory on the Portal node, such as /opt/apigee/customer/application. The directory must be accessible to the 'apigee' user.
Change ownership of the PEM files to the 'apigee' user:
> chown apigee:apigee /opt/apigee/customer/application/*.PEM
Edit the /opt/apigee/customer/application/portal.properties file to set the following properties. If that file does not exist, create it:
baas.portal.ssl=on
baas.portal.ssl.certificate=/opt/apigee/customer/application/defaultcert.pem
baas.portal.ssl.key=/opt/apigee/customer/application/defaultkey.pem
baas.portal.ssl.protocols=TLSv1 TLSv1.1 TLSv1.2
# By default, TLS access uses port 9000.
# Use this property to specify a different port.
# baas.portal.listen=9000

Use baas.portal.ssl.protocols to set the TLS protocols supported by the Portal. For a list of supported protocols, see the list of SSL protocol names defined by Nginx: http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols.
Configure the Portal node:
> /opt/apigee/apigee-service/bin/apigee-service baas-portal configure
Restart the Portal:
> /opt/apigee/apigee-service/bin/apigee-service baas-portal restart
Use the procedure below in "Configure API BaaS Stack nodes for TLS on the Stack or Portal" to ensure that the Stack node has the correct TLS URL for the Portal.

Configure API BaaS nodes for TLS on the Stack or Portal

If you include a load balancer in front of the Stack or Portal nodes, or if you enable TLS directly on the Portal or Stack node, you have to configure the nodes with the correct URLs to access the Stack and Portal. For example, the Stack nodes require this information when:

Including a URL in responses in BaaS API requests.
Adding links in email templates when resetting a password, or sending other notifications.
Redirecting users to specific Portal pages.

If you use a load balancer in front of the Stack nodes or configure TLS on the Stack node, set the following property in /opt/apigee/customer/application/usergrid.properties:

usergrid-deployment_usergrid.api.url.base=http://localhost:8080

Replace http://localhost:8080 with the URL of the load balancer. If the load balancer is configure to use TLS, use the HTTPS protocol. You only need to include the port if you are using a non-standard port, meaning something other than port 80 for HTTP and port 443 for HTTPS.

You also have to set the following property in /opt/apigee/customer/application/portal.properties if you use a load balancer in front of the Stack nodes:

baas.portal.config.overrideUrl=http://localhost:8080

Replace http://localhost:8080 with the URL of the load balancer for the Stack.

If you use a load balancer in front of the Portal node or configure TLS on the Stack node, set the following properties in usergrid.properties:

usergrid-deployment_portal.url=http://localhost:9000

Replace http://localhost:9000 with the URL of the load balancer. If the load balancer is configure to use TLS, use the HTTPS protocol. You only need to include the port if you are using a non-standard port, meaning something other than port 80 for HTTP and port 443 for HTTPS.

After editing usergrid.properties:

Configure the Stack node:
> /opt/apigee/apigee-service/bin/apigee-service baas-usergrid configure
Restart the BaaS Stack:
> /opt/apigee/apigee-service/bin/apigee-service baas-usergrid restart
If you modified portal.properties, configure the Portal node:
> /opt/apigee/apigee-service/bin/apigee-service baas-portal configure
Restart the BaaS Portal:
> /opt/apigee/apigee-service/bin/apigee-service baas-portal restart