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.

Note: The API BaaS Portal never makes requests directly to an BaaS
Stack node. When a developer logs into the Portal, the Portal app is downloaded to the browser.
The Portal app running in the browser then makes requests to the BaaS Stack nodes.

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

Note: Because the Portal runs as a browser app, if you configure TLS
access to the Portal, then requests from the Portal to the Stack nodes must also use TLS.
Therefore, either the load balancer for the Stack nodes must be configured to support TLS or, if
you omit the load balancer, then the Stack node must be configured to support TLS.

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:

Note: This example uses port 8080 and 9443 for the TLS port, and not the more common
port 443. The reason is that ports below 1024 are typically protected by the operating system
and require the process that accesses them to have root access. The Portal and Stack run as the
"apigee" user and therefore typically do not have access to ports below 1024.

One alternative it to use a load balancer and terminate TLS on the load balancer on port
443. You can then use either HTTP or HTTPS between the load balancer and the Portal and
Stack.

Another alternative is to use iptables to forward requests. For example,
to forward request to port 443 to port 9443:

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.

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.

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.

Note: Because the Portal runs as a browser app, if you configure TLS
access to the Portal, then requests from the Portal to the Stack nodes must also
use TLS. Therefore, either the load balancer for the Stack nodes must be configured to support
TLS or, if you omit the load balancer, then the Sack node must be configured to support
TLS.

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