Install Apigee SSO for high availability

You install multiple instances of the 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 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 the Apigee SSO in one data center goes down.

Install two Apigee SSO modules in the same data center

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

  • Both instances of the Apigee SSO must be connected to the same Postgres server. Apigee recommends using a dedicated Postgres server for the Apigee SSO and not the same Postgres server that you installed with Edge. Both instances must share the apigee_dex database for state persistence.
  • No manual JWT key distribution is required: Unlike the legacy UAA component, the modernized Apigee SSO stores and syncs its JSON Web Key Sets (JWKS) and OAuth2 state natively in the shared PostgreSQL database. You do not need to manually copy signing keys across nodes.
  • Credential synchronization for internal OpenLDAP: If you are using the default internal OpenLDAP, the Apigee SSO uses a dedicated read-only service account (cn=sso-reader). For HA (Node 2), the admin must either set the same SSO_READER_PW in /opt/silent.conf on both nodes, or copy /opt/apigee/data/apigee-openldap/sso-reader.key from Node 1 to Node 2 before running setup-sso on Node 2.

    To manually copy the keyfile, execute the following commands on Node 2:

    scp node1_ip:/opt/apigee/data/apigee-openldap/sso-reader.key /opt/apigee/data/apigee-openldap/sso-reader.key
chown apigee:apigee /opt/apigee/data/apigee-openldap/sso-reader.key
chmod 600 /opt/apigee/data/apigee-openldap/sso-reader.key
  • You require a load balancer in front of the two instances of the Apigee SSO:
    • Configure the load balancer to perform a TCP or HTTP health check on the SSO. For HTTP, include /healthz: 
      http_or_https://edge_sso_IP_DNS:9099/healthz

      Specify the port as set by the Apigee SSO. Port 9099 is the default.

    • Some load balancer settings depend on whether you enabled HTTPS on the Apigee SSO. See the following sections for more information.

HTTP access to Apigee SSO

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

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

By default, the Apigee SSO listens for HTTP requests on port 9099. Optionally, you can use SSO_PUBLIC_URL_PORT in your /opt/silent.conf file to set the port. If you used SSO_PUBLIC_URL_PORT to change the port from the default, ensure that the load balancer listens on that port.

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

SSO_PUBLIC_URL_PORT=9033

You then configure the load balancer to listen on port 9033 and forward requests to the SSO instances on port 9033. The public Issuer URL of the Apigee SSO in this scenario is:

http://LB_DNS_NAME:9033

HTTPS access to Apigee SSO

You can configure HA with HTTPS using either of the following two modes. In both scenarios, follow the detailed setup steps in Configure Apigee SSO for HTTPS access.

Mode 1: Load balancer terminates TLS (SSL_PROXY)

If your load balancer terminates the TLS connection, it must forward plain HTTP traffic to the Apigee SSO instances.

  • Set SSO_PUBLIC_URL_SCHEME=https and SSO_PUBLIC_URL_PORT=443 (or your load balancer's public HTTPS port) in your /opt/silent.conf file.
  • Configure the load balancer to use HTTP mode to connect to the backend Apigee SSO instances.
  • Configure the load balancer to forward requests to the Apigee SSO instances on their local HTTP bind port (default: 9099).

Mode 2: Apigee SSO terminates TLS (SSL_TERMINATION)

If you want the Apigee SSO instances to terminate the TLS connections directly, the load balancer must pass the encrypted traffic through to them.

  • Set SSO_PUBLIC_URL_SCHEME=https and SSO_PUBLIC_URL_PORT=9443 (or your chosen secure port) in your /opt/silent.conf file.
  • Configure the load balancer to use TCP mode (not HTTP mode) to connect to the backend, allowing the Apigee SSO to terminate TLS.
  • Configure the load balancer to listen on the same port as the Apigee SSO, and forward requests to the Apigee SSO instances on their secure port (for example, 9443).

Install Apigee SSO in multiple data centers

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

Before you install the 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 primary-standby replication for Postgres.

  • A single DNS entry that points to one SSO instance. For example, you create a DNS entry in the following form, which points to the SSO instance in data center 1: 
    my-sso.domain.com => apigee-sso-dc1-ip-or-lb
  • Synchronized OpenLDAP Reader Credentials. If you are using the internal OpenLDAP, you must ensure both data centers use the exact same SSO_READER_PW or share the same sso-reader.key file to prevent cluster desynchronization during setup.

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

## Postgres configuration
PG_HOST=IP_or_DNS_of_PG_Master_in_DC1
PG_PORT=5432

You must also configure both data centers to use the shared DNS entry as the publicly accessible Issuer URL. Because the setup-sso script automatically constructs the issuer URL and appends the port, you must set the exact URL directly in /opt/apigee/customer/application/openldap.properties instead of /opt/silent.conf to prevent the port from being appended if it is not required:

# Externally accessible URL of the Apigee SSO
etc_sso_config_issuer_url=https://my-sso.domain.com

Handling SSO failover

If the Apigee SSO instance (or its Postgres Master) in data center 1 goes down, you can switch to the SSO instance in data center 2 without losing active OAuth sessions:

  1. Convert the Postgres Standby server in data center 2 to Master as described in Handling a PostgreSQL database failover.
  2. Update your DNS record to point my-sso.domain.com to the SSO instance in data center 2: 
    my-sso.domain.com => apigee-sso-dc2-ip-or-lb
  3. Update your /opt/silent.conf file for the 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
  4. Reconfigure and restart the Apigee SSO in data center 2 to update its connection natively: 
    /opt/apigee/apigee-service/bin/apigee-service apigee-openldap setup-sso -f /opt/silent.conf