Install Apigee SSO for high availability

You install multiple instances of Apigee SSO for high availability in two scenarios:

In a single data center environment, install two Apigee SSO instances to create a high availability environment, meaning the system continues to operate if one of the Apigee SSO modules goes down.
In an environment with two data centers, install Apigee SSO in both data centers so that the system continues to operate if one of the Apigee SSO modules goes down.

Install two Apigee SSO modules in the same data center

You deploy two instances of Apigee SSO, on different nodes, in a single data center to support high availability. In this scenario:

Both instances of Apigee SSO must be connected to the same Postgres server. Apigee recommends using a dedicated Postgres server for Apigee SSO and not the same Postgres server that you installed with Edge.
Both instances of Apigee SSO must use the same JWT key pair as specified by the SSO_JWT_SIGNING_KEY_FILEPATH and SSO_JWT_VERIFICATION_KEY_FILEPATH properties in the configuration file. See Install and configure Apigee SSO for more on setting these properties.
You require a load balancer in front of the two instances of Apigee SSO:
- The load balancer must support application generated cookie stickiness, and the session cookie must be named JSESSIONID.
- Configure the load balancer to perform a TCP or HTTP health check on Apigee SSO. For TCP, use the URL of Apigee SSO:
```
http_or_https://edge_sso_IP_DNS:9099
```
  Specify the port as set by Apigee SSO. Port 9099 is the default.
  
  For HTTP, include /healthz:
```
http_or_https://edge_sso_IP_DNS:9099/healthz
```
- Some load balancer settings depend on whether you enabled HTTPS on Apigee SSO. See the following sections for more information.

HTTP access to Apigee SSO

If you are using HTTP access to Apigee SSO, then configure the load balancer to:

Use HTTP mode to connect to Apigee SSO.
Listen on the same port as Apigee SSO.

By default, Apigee SSO listens for HTTP requests on port 9099. Optionally, you can use SSO_TOMCAT_PORT to set the Apigee SSO port. If you used SSO_TOMCAT_PORT to change the Apigee SSO port from the default, ensure that the load balancer listens on that port.

For example, on each Apigee SSO instance you set the port to 9033 by adding the following to the config file:

SSO_TOMCAT_PORT=9033

You then configure the load balancer to listen on port 9033 and forwarding requests to an Edge SSO instance on port 9033. The public URL of Apigee SSO in this scenario is:

http://LB_DNS_NAME:9033

HTTPS access to Apigee SSO

You can configure the Apigee SSO instances to use HTTPS for secure communications. In this scenario, follow the steps in Configure Apigee SSO for HTTPS access. As part of the process of enabling HTTPS, set the SSO_TOMCAT_PROFILE in the Apigee SSO configuration file as shown below:

SSO_TOMCAT_PROFILE=SSL_TERMINATION

Optionally, set the port used by Apigee SSO for HTTPS access:

SSO_TOMCAT_PORT=9443

To ensure proper communication between the Load Balancer and Apigee SSO, configure the Load Balancer as follows:

Use TCP mode, not HTTP mode, to connect to Apigee SSO. This allows SSL connections to pass through without termination at the Load Balancer.
Listen on the same port as Apigee SSO as defined by SSO_TOMCAT_PORT (e.g., 9443).
Forward requests to an Apigee SSO instance on the same port (9443).

Ensure that the public URL reflects the Load Balancer's DNS and port settings. The public URL of Apigee SSO in this scenario is:

https://LB_DNS_NAME:9443

Install Apigee SSO in multiple data centers

In a multiple data center environment, you install an Apigee SSO instance in each data center. One Apigee SSO instance then handles all traffic. If that Apigee SSO instance goes down you can then switch to the second Apigee SSO instance.

Before you install Apigee SSO in two data centers, you need the following:

The IP address or domain name of the Master Postgres server.

In a multiple data center environment, you typically install one Postgres server in each data center and configure them in Master-Standby replication mode. For this example, data center 1 contains the Master Postgres server and data center 2 contains the Standby. For more information, see Set up Master-Standby Replication for Postgres.
A single DNS entry that points to one Apigee SSO instance. For example, you create a DNS entry in the form below that points to the Apigee SSO instance in data center 1:
```
my-sso.domain.com => apigee-sso-dc1-ip-or-lb
```
Both instances of Apigee SSO must use the same JWT key pair as specified by the SSO_JWT_SIGNING_KEY_FILEPATH and SSO_JWT_VERIFICATION_KEY_FILEPATH properties in the configuration file. See Install and configure Apigee SSO for more on setting these properties.

When you install Apigee SSO in each data center, you configure both to use the Postgres Master in data center 1:

## Postgres configuration
PG_HOST=IP_or_DNS_of_PG_Master_in_DC1
PG_PORT=5432

You also configure both data centers to use the DNS entry as the publicly accessible URL:

# Externally accessible URL of Apigee SSO
SSO_PUBLIC_URL_HOSTNAME=my-sso.domain.com
# Default port is 9099.
SSO_PUBLIC_URL_PORT=9099

If Apigee SSO in data center 1 goes down, you can then switch to the Apigee SSO instance in data center 2:

Convert the Postgres Standby server in data center 2 to Master as described in Handling a PostgreSQL database failover.
Update the DNS record to point my-sso.domain.com to the Apigee SSO instance in data center 2:
```
my-sso.domain.com => apigee-sso-dc2-ip-or-lb
```
Update the config file for Apigee SSO in data center 2 to point to the new Postgres Master server in data center 2:
```
## Postgres configuration
PG_HOST=IP_or_DNS_of_PG_Master_in_DC2
```

Restart Apigee SSO in data center 2 to update its configuration:

/opt/apigee/apigee-service/bin/apigee-service apigee-sso restart