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 ofapigee-sso
and terminated TLS on the load balancer. You then specify the port used onapigee-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.
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.
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:
- 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:
- 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.