Install and configure Edge SSO

Edge for Private Cloud v4.18.01

Installing and configuring the Edge SSO module requires that you first generate two sets of TLS keys and certificates. The Edge SSO module uses TLS to secure the transmission of information as part of the SAML handshaking process with the SAML IDP.

Note: By default, the Edge SSO module is accessible over HTTP on port 9099 of the node on which it is installed. You can enable TLS on the Edge SSO module. To do so, you have to create a third set of TLS keys and certificates used by Tomcat to support TLS. See Configure apigee-sso for HTTPS access for more.

Create the TLS keys and certificates

The steps below create self-signed certs which might be fine for your testing environment but you typically require certs signed by a CA for a production environment.

To create the verification and signing key and self-signed cert:

  1. > sudo mkdir -p /opt/apigee/customer/application/apigee-sso/jwt-keys
  2. > cd /opt/apigee/customer/application/apigee-sso/jwt-keys/
  3. > sudo openssl genrsa -out privkey.pem 2048
  4. > sudo openssl rsa -pubout -in privkey.pem -out pubkey.pem
  5. > sudo chown apigee:apigee *.pem

To create the key and self-signed cert, with no passphrase, for communicating with the SAML IDP:

  1. > sudo mkdir -p /opt/apigee/customer/application/apigee-sso/saml/
  2. > cd /opt/apigee/customer/application/apigee-sso/saml/
  3. Generate your private key with a passphrase:
    > sudo openssl genrsa -aes256 -out server.key 1024
  4. Remove the passphrase from the key:
    > sudo openssl rsa -in server.key -out server.key
  5. Generate certificate signing request for CA:
    > sudo openssl req -x509 -sha256 -new -key server.key -out server.csr
  6. Generate self-signed certificate with 365 days expiry-time:
    > sudo openssl x509 -sha256 -days 365 -in server.csr -signkey server.key -out selfsigned.crt
  7. > sudo chown apigee:apigee server.key
  8. > sudo chown apigee:apigee selfsigned.crt

If you want to enable TLS on the Edge SSO module, by setting SSO_TOMCAT_PROFILE to SSL_TERMINATION or to SSL_PROXY, you cannot use a self-signed certificate. You must generate a cert from a CA. See Configure apigee-sso for HTTPS access for more.

Install and configure Edge SSO for HTTP access

To install the Edge SSO module, apigee-sso, you must use the same process that you used to install Edge. Because apigee-sso is represented by an RPM file, that means the user performing the install must be the root user or be a user that has full sudo access. See Edge Installation Overview for more.

Pass a config file to the installer. The config file has the following form:

IP1=hostname_or_ip_of_management_server
IP2=hostname_or_ip_of_UI_and_apigge_sso

## Management Server configuration.
MSIP=$IP1
MGMT_PORT=8080
# Edge sys admin username and password as set when you installed Edge.
ADMIN_EMAIL=opdk@google.com
APIGEE_ADMINPW=Secret123
# Set the protocol for the Edge management API. Default is http. 
# Set to https if you enabled TLS on the management API.
MS_SCHEME=http

## Postgres configuration. 
PG_HOST=$IP1
PG_PORT=5432
# Postgres username and password as set when you installed Edge.
PG_USER=apigee
PG_PWD=postgres

# apigee-sso configuration.
SSO_PROFILE="saml"
# Externally accessible IP or DNS name of apigee-sso.
SSO_PUBLIC_URL_HOSTNAME=$IP2
# Default port is 9099. If changing, set both properties to the same value.
SSO_PUBLIC_URL_PORT=9099
SSO_TOMCAT_PORT=9099
# Set Tomcat TLS mode to DEFAULT to use HTTP access to apigee-sso.
SSO_TOMCAT_PROFILE=DEFAULT
SSO_PUBLIC_URL_SCHEME=http

# SSO admin user name. The default is ssoadmin.
SSO_ADMIN_NAME=ssoadmin
# SSO admin password using uppercase, lowercase, number, and special chars. 
SSO_ADMIN_SECRET=Secret123

# Path to signing key and secret from "Create the TLS keys and certificates" above.
SSO_JWT_SIGNING_KEY_FILEPATH=/opt/apigee/customer/application/apigee-sso/jwt-keys/privkey.pem
SSO_JWT_VERIFICATION_KEY_FILEPATH=/opt/apigee/customer/application/apigee-sso/jwt-keys/pubkey.pem

# Name of SAML IDP. For example, okta or adfs. 
SSO_SAML_IDP_NAME=okta
# Text displayed to user when they attempt to access Edge UI.
SSO_SAML_IDP_LOGIN_TEXT="Please log in to your IDP"

# The metadata URL from your IDP.
# If you have a metadata file, and not a URL, 
# see "Specifying a metadata file instead of a URL" below.
SSO_SAML_IDP_METADATA_URL=https://dev-343434.oktapreview.com/app/exkar20cl/sso/saml/metadata

# Specifies to skip TLS validation for the URL specified
# by SSO_SAML_IDP_METADATA_URL. Necessary if URL uses a self-signed cert. 
# Default value is "n".
SSO_SAML_IDPMETAURL_SKIPSSLVALIDATION=n

# SAML service provider key and cert from "Create the TLS keys and certificates" above.
SSO_SAML_SERVICE_PROVIDER_KEY=/opt/apigee/customer/application/apigee-sso/saml/server.key
SSO_SAML_SERVICE_PROVIDER_CERTIFICATE=/opt/apigee/customer/application/apigee-sso/saml/selfsigned.crt
# The passphrase used when you created the SAML cert and key. 
# The section "Create the TLS keys and certificates" above removes the passphrase, 
# but this property is available if you require a passphrase.
# SSO_SAML_SERVICE_PROVIDER_PASSWORD=samlSP123

# Must configure an SMTP server so Edge SSO can send emails to users.
SKIP_SMTP=n
SMTPHOST=smtp.example.com
SMTPUSER=smtp@example.com  
# omit for no username
SMTPPASSWORD=smtppwd    
# omit for no password
SMTPSSL=n
SMTPPORT=25
SMTPMAILFROM="My Company <myco@company.com>"

To install the Edge SSO module:

  1. Log in to the Management Server node. That node should already have apigee-service installed as described at Install the Edge apigee-setup utility.
    Note that you can install Edge SSO on a different node. However, that node must be able to access the Management Server over port 8080.
  2. Instal and configure apigee-sso:
    > /opt/apigee/apigee-setup/bin/setup.sh -p sso -f configFile

    where configFile is the config file shown above.
  3. Instal the apigee-ssoadminapi.sh utility used to manage admin and machine users for the apigee-sso module:
    /opt/apigee/apigee-service/bin/apigee-service apigee-ssoadminapi install
  4. Log out of the shell, and then log back in again to add the apigee-ssoadminapi.sh utility to your path.

Specifying a metadata file instead of a URL

If your IDP does not support an HTTP/HTTPS metadata URL, you can use a metadata XML file to configure Edge SSO:

  1. Copy the contents of the metadata XML from your IDP to a file on the Edge SSO node. For example, copy the XML to:
    /opt/apigee/customer/application/apigee-sso/saml/metadata.xml
  2. Change ownership of the file to apigee:apigee:
    > chown apigee:apigee /opt/apigee/customer/application/apigee-sso/saml/metadata.xml
  3. Set the value of SSO_SAML_IDP_METADATA_URL to the absolute file path:
    SSO_SAML_IDP_METADATA_URL=file:///opt/apigee/customer/application/apigee-sso/saml/metadata.xml

    You must prefix the file path with "file://", followed by the absolute path from root (/).