Configure Apigee SSO for HTTPS access

Install and configure Apigee SSO describes how to install and configure the Apigee SSO module to use HTTP on port 9099, as specified by the following property in the Edge configuration file:

SSO_TOMCAT_PROFILE=DEFAULT

Alternatively, you can set SSO_TOMCAT_PROFILE to one of the following values to enable HTTPS access:

SSL_PROXY: Configures apigee-sso, the Apigee SSO module, in proxy mode, meaning you have installed a load balancer in front of apigee-sso and terminated TLS on the load balancer. You then specify the port used on apigee-sso for requests from the load balancer.
SSL_TERMINATION: Enabled TLS access to apigee-sso on the port of your choice. You must specify a keystore for this mode that contains a certificate signed by a CA. You cannot use a self-signed certificate.

You can choose to enable HTTPS at the time you initially install and configure apigee-sso, or you can enable it later.

Enabling HTTPS access to apigee-sso using either mode disables HTTP access. That is, you cannot access apigee-sso using both HTTP and HTTPS concurrently.

NOTE: If you configure HTTPS access to apigee-sso, ensure that you update any URLs used by the Edge UI and by your IDP to use HTTPS. Also, if you choose to enable HTTPS on a port other than 9099, make sure you update the UI and IDP to use the correct port number.

Enable SSL_PROXY mode

In SSL_PROXY mode, your system uses a load balancer in front of the Apigee SSO module and terminates TLS on the load balancer. In the following figure, the load balancer terminates TLS on port 443, and then forwards requests to the Apigee SSO module on port 9099:

In this configuration, you trust the connection from the load balancer to the Apigee SSO module, so there is no need to use TLS for that connection. However, external entities, such as the IDP, now must access the Apigee SSO module on port 443, not on the unprotected port of 9099.

The reason to configure the Apigee SSO module in SSL_PROXY mode is that the Apigee SSO module auto-generates redirect URLs used externally by the IDP as part of the authentication process. Therefore, these redirect URLs must contain the external port number on the load balancer, 443 in this example, and not the internal port on the Apigee SSO module, 9099.

NOTE: You do not have to create a TLS cert and key for SSL_PROXY mode because the connection from the load balancer to the Apigee SSO module uses HTTP.

To configure the Apigee SSO module for SSL_PROXY mode:

Add the following settings to your config file:

# Enable SSL_PROXY mode.
SSO_TOMCAT_PROFILE=SSL_PROXY

# Specify the apigee-sso port, typically between 1025 and 65535.
# Typically ports 1024 and below require root access by apigee-sso.
# The default is 9099.
SSO_TOMCAT_PORT=9099

# Specify the port number on the load balancer for terminating TLS.
# This port number is necessary for apigee-sso to auto-generate redirect URLs.
SSO_TOMCAT_PROXY_PORT=443
SSO_PUBLIC_URL_PORT=443

# Set public access scheme of apigee-sso to https.
SSO_PUBLIC_URL_SCHEME=https

Configure the Apigee SSO module:

/opt/apigee/apigee-service/bin/apigee-service apigee-sso setup -f configFile

Update your IDP configuration to now make an HTTPS request on port 443 of the load balancer to access Apigee SSO. For more information, see one of the following:
- Configure your SAML IDP
- Configure your LDAP IDP
Update your Edge UI configuration for HTTPS by setting the following properties in the config file:
```
SSO_PUBLIC_URL_PORT=443
SSO_PUBLIC_URL_SCHEME=https
```
Then update the Edge UI:
```
/opt/apigee/apigee-service/bin/apigee-service edge-management-ui configure-sso -f configFile
```
Use the edge-ui component for the Classic UI.
If you installed the Apigee Developer Services portal (or simply, the portal), update it to use HTTPS to access Apigee SSO. For more information, see Configure the portal to use external IDPs

See Enable an external IDP on the Edge UI for more information.

Enable SSL_TERMINATION mode

For SSL_TERMINATION mode, you must:

Generate a TLS cert and key and store them in a keystore file. You cannot use a self-signed certificate. You must generate a cert from a CA.
Update the configuration settings for apigee-sso.

To create a keystore file from your cert and key:

Create a directory for the JKS file:

sudo mkdir -p /opt/apigee/customer/application/apigee-sso/tomcat-ssl/

Change to the new directory:

cd /opt/apigee/customer/application/apigee-sso/tomcat-ssl/

Create a JKS file containing the cert and key. You must specify a keystore for this mode that contains a cert signed by a CA. You cannot use a self-signed cert. For an example of creating a JKS file, see Configuring TLS/SSL for Edge On Premises.

Make the JKS file owned by the "apigee" user:

sudo chown -R apigee:apigee /opt/apigee/customer/application/apigee-sso/tomcat-ssl

To configure the Apigee SSO module:

Add the following settings to your config file:

# Enable SSL_TERMINATION mode.
SSO_TOMCAT_PROFILE=SSL_TERMINATION

# Specify the path to the keystore file.
SSO_TOMCAT_KEYSTORE_FILEPATH=/opt/apigee/customer/application/apigee-sso/tomcat-ssl/keystore.jks

SSO_TOMCAT_KEYSTORE_ALIAS=sso

# The password specified when you created the keystore.
SSO_TOMCAT_KEYSTORE_PASSWORD=keystorePassword

# Specify the HTTPS port number between 1025 and 65535.
# Typically ports 1024 and below require root access by apigee-sso.
# The default is 9099.
SSO_TOMCAT_PORT=9443
SSO_PUBLIC_URL_PORT=9443

# Set public access scheme of apigee-sso to https.
SSO_PUBLIC_URL_SCHEME=https

Configure the Apigee SSO module:

/opt/apigee/apigee-service/bin/apigee-service apigee-sso setup -f configFile

Update your IDP configuration to now make an HTTPS request on port 9443 of the load balancer to access Apigee SSO. Be sure that no other service is using this port.
For more information, see the following:
- Configure your SAML IDP
- Configure your LDAP IDP
Update your Edge UI configuration for HTTPS by setting the following properties:
```
SSO_PUBLIC_URL_PORT=9443
SSO_PUBLIC_URL_SCHEME=https
```
If you installed the Developer Services portal, update it to use HTTPS to access Apigee SSO. For more, see Configure the portal to use external IDPs.

Set SSO_TOMCAT_PROXY_PORT when using SSL_TERMINATION mode

You might have a load balancer in front of the Apigee SSO module that terminates TLS on the load balancer but also enables TLS between the load balancer and Apigee SSO. In the figure above for SSL_PROXY mode, this means the connection from the load balancer to Apigee SSO uses TLS.

In this scenario, you configure TLS on Apigee SSO just as you did above for SSL_TERMINATION mode. However, if the load balancer uses a different TLS port number than Apigee SSO uses for TLS, then you must also specify the SSO_TOMCAT_PROXY_PORT property in the config file. For example:

The load balancer terminates TLS on port 443
Apigee SSO terminates TLS on port 9443

Make sure to include the following setting in the config file:

# Specify the port number on the load balancer for terminating TLS.
# This port number is necessary for apigee-sso to generate redirect URLs.
SSO_TOMCAT_PROXY_PORT=443
SSO_PUBLIC_URL_PORT=443

The configure the IDP and Edge UI to make HTTPS requests on port 443.