Configuring Edge SSO using Ops Manager

Edge for Private Cloud v4.18.05

Apigee Edge Installer for Pivotal Cloud Foundry v18.05.01 corresponds to Apigee Edge for Private Cloud v4.18.05.01

After you install, configure, and provision Edge, you can optionally enable and provision Edge SSO. When you enable Edge SSO, the installer adds Edge SSO to both Management Server nodes.

Before you enable Edge SSO, read about Edge SSO and SAML support at Supporting SAML on Edge for Private Cloud.

Overview of Configuring Edge SSO

Ops Manager installs the Edge SSO module on the same nodes as the two Edge Management Servers. Ops Manager does not install a separate Postgres server for Edge SSO. Instead Edge SSO uses the Postgres servers already installed with Edge.

The process for installing and configuring SAML support on Edge for Private Cloud requires that you perform some tasks on your SAML IDP and some on Edge. The general process is:

  1. Install Edge and ensure that your installation is working properly. See Installing Edge using Ops Manager.
  2. Define a load balancer for Edge SSO. The requirements for the load balancer are described below.
  3. Configure your SAML IDP. This process requires that you configure your IDP to use e-mail addresses as the user ID, and specify the redirect URL to the Edge UI, which is used after a successful login. See Configure your SAML IDP.
  4. Create the TLS keys and certificates used by Edge SSO. This process is described below.
  5. Install and configure apigee-sso, the Edge SSO module. Configuring apigee-sso enables SAML on the Edge management API and Edge UI. This process is described below.
  6. For each user in the IDP that corresponds to an Edge user, create an Edge user account and assign that user a role in an Edge organization. The Edge user must have the same e-mail address as is stored for the user in the IDP. See Register new Edge users.
  7. Optionally enable Edge SSO for for the Developer Services portal. This process is described below.
  8. After you have tested SAML support, you can disable Basic Auth. See Disabling Basic Auth on Edge for more.

Prerequisite: Define a load balancer for Edge SSO

With Ops Manager, you must predefine a load balancer to control access to Edge SSO. The load balancer defines the domain name and port of the Edge SSO access point, optionally enables TLS, and forwards requests to the appropriate port on Edge SSO.

The following table lists the requirements of the load balancer:

Component Load Balancer Requirements TLS
Edge SSO Ops Manager installs Edge SSO on both Edge Management Server nodes.

The load balancer defines the publicly accessible domain name of Edge SSO. For example, https://edge_sso.example.com.

The load balancer then routes Edge SSO requests to the correct port (9099 by default) on the Edge SSO server. You can use the SSO Tomcat port option in Ops Manager to specify a different port for use by Edge SSO. If you do change the port on Edge SSO, make sure the load balancer directs requests to that port.

Recommended

Prerequisite: Create the 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. Installing and configuring the Edge SSO module requires that you first generate two sets of 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.

This section describes how to create the keys and certs on the Ops Manager server. After you create the keys and certs, you must copy them to the Edge Management Server instances.

Create the keys and certs for communicating with the IDP

You must first log in to the Ops Manager server:

  1. Use ssh to connect to the Ops Manager server. For example: > ssh -i ~/.ssh/bosh.pem user@serverIP
  2. Log in to bosh:
    > bosh login

    At the prompts, enter the e-mail address and password of the BOSH user.

On the Ops Manager server, to create the JWT verification and signing key as a self-signed cert and then copy them to the Management Server VMs:

  1. > mkdir -p /home/yourhomedir/jwt-keys/
  2. > cd /home/yourhomedir/jwt-keys/
  3. > sudo openssl genrsa -out privkey.pem 2048
  4. > sudo openssl rsa -pubout -in privkey.pem -out pubkey.pem
  5. Upload the files to the /tmp directory on the two Management Servers:
    > bosh scp edge-management-server/0 --upload /home/yourhomedir/jwt-keys/privkey.pem /tmp
    > bosh scp edge-management-server/1 --upload /home/yourhomedir/jwt-keys/privkey.pem /tmp

    > bosh scp edge-management-server/0 --upload /home/yourhomedir/jwt-keys/pubkey.pem /tmp
    > bosh scp edge-management-server/1 --upload /home/yourhomedir/jwt-keys/pubkey.pem /tmp
  6. Copy the files to the correct location on the Management Server, and set the file permissions:
    1. For Management Server 0:
      > bosh ssh edge-management-server/0 "sudo mkdir -p /opt/apigee/customer/application/apigee-sso/jwt-keys"

      >
      bosh ssh edge-management-server/0 "sudo cp -r /tmp/privkey.pem /opt/apigee/customer/application/apigee-sso/jwt-keys/privkey.pem"

      >
      bosh ssh edge-management-server/0 "sudo chmod 644 /opt/apigee/customer/application/apigee-sso/jwt-keys/privkey.pem"

      >
      bosh ssh edge-management-server/0 "sudo chown apigee:apigee /opt/apigee/customer/application/apigee-sso/jwt-keys/privkey.pem"

      > bosh ssh edge-management-server/0 "sudo cp -r /tmp/pubkey.pem /opt/apigee/customer/application/apigee-sso/jwt-keys/pubkey.pem"

      >
      bosh ssh edge-management-server/0 "sudo chmod 644 /opt/apigee/customer/application/apigee-sso/jwt-keys/pubkey.pem"

      >
      bosh ssh edge-management-server/0 "sudo chown apigee:apigee /opt/apigee/customer/application/apigee-sso/jwt-keys/pubkey.pem"
    2. Repeat the step for Management Server 1.

On the Ops Manager server, to create the key and self-signed cert, with no passphrase, for communicating with the SAML IDP, and then copy them to the Management Server VMs:

  1. > mkdir -p /home/yourhomedir/saml/
  2. > cd /home/yourhomedir/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 the 365-day expiry time:
    > sudo openssl x509 -sha256 -days 365 -in server.csr -signkey server.key -out selfsigned.crt
  7. Upload the files to the /tmp directory on the two Management Servers:
    > bosh scp edge-management-server/0 --upload /home/yourhomedir/saml/server.key /tmp
    > bosh scp edge-management-server/1 --upload /home/yourhomedir/saml/server.key /tmp

    > bosh scp edge-management-server/0 --upload /home/yourhomedir/saml/selfsigned.crt /tmp
    > bosh scp edge-management-server/1 --upload /home/yourhomedir/saml/selfsigned.crt /tmp
  8. Copy the files to the correct location on the Management Server, and set the file permissions:
    1. For Management Server 0:
      > bosh ssh edge-management-server/0 "sudo mkdir -p /opt/apigee/customer/application/apigee-sso/saml"

      > bosh ssh edge-management-server/0 "sudo cp -r /tmp/server.key /opt/apigee/customer/application/apigee-sso/saml/server.key"

      > bosh ssh edge-management-server/0 "sudo chmod 644 /opt/apigee/customer/application/apigee-sso/saml/server.key"

      > bosh ssh edge-management-server/0 "sudo chown apigee:apigee /opt/apigee/customer/application/apigee-sso/saml/server.key"

      > bosh ssh edge-management-server/0 "sudo cp -r /tmp/selfsigned.crt /opt/apigee/customer/application/apigee-sso/saml/selfsigned.crt"

      > bosh ssh edge-management-server/0 "sudo chmod 644 /opt/apigee/customer/application/apigee-sso/saml/selfsigned.crt"

      > bosh ssh edge-management-server/0 "sudo chown apigee:apigee /opt/apigee/customer/application/apigee-sso/saml/selfsigned.crt"
    2. Repeat the step for Management Server 1.

Optional: Enable TLS on Edge SSO

By default, the Edge SSO module supports HTTP access on port 9099. However, Edge SSO supports TLS access in two modes:

  • SSL_PROXY - Configures Edge SSO in proxy mode, meaning you have installed a load balancer in front of Edge SSO and terminated TLS on the load balancer.

    Because Edge requires that you create a load balancer to install Edge SSO, you often select this mode to enable TLS. In this mode, set:
    • SSO Tomcat profile = SSL_PROXY
    • SSO public URL scheme = https
    • SSO public port = Port on the load balancer for requests to Edge SSO
    • SSO Tomcat proxy port = Port on the load balancer for requests to Edge SSO
    • SSO Tomcat port = Port on Edge SSO for requests (default is 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 Edge SSO module uses HTTP.
  • SSL_TERMINATION - Enabled TLS access to the Edge SSO module on the port of your choice. You must specify a keystore for this mode that contains a cert signed by a CA. You cannot use a self-signed cert.

    In this mode, set:
    • SSO Tomcat profile = SSL_TERMINATION
    • SSO public URL scheme = https
    • SSO public port = Port on the load balancer for requests to Edge SSO
    • SSO Tomcat proxy port = Port on the load balancer for requests to Edge SSO
    • SSO Tomcat port = Port on Edge SSO for TLS requests (default is 9099)
    • SSO Tomcat keystore path, SSO Tomcat keystore alias, SSO Tomcat keystore password based on the location and settings of your keystore file.

See Configure apigee-sso for HTTPS access for more.

Create the keys and certs for SSL_TERMINATION mode

There are many ways to create a keystore, so the specific details are left to you. However, you need to represent the keystore as a JKS file.

  1. 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, create a JKS file named keystore.jks as described in Configuring TLS/SSL for Edge On Premises.
  2. Use the procedure above in Prerequisite: Create the TLS keys and certificates to copy the JKS file to /opt/apigee/customer/application/apigee-sso/tomcat-ssl/ on each Management Server node.
  3. Use the procedure above to set the file permissions to 644 and the owner of the file to "apigee".

To change the TLS type

At installation time, you can choose to enable TLS on Edge SSO or not. After you install Edge SSO, you can later decide to change the TLS Setting. That is, if TLS is disabled, you can later enable it. Or if it is enabled, you can later disable it.

However, if you do decide to later change the TLS type, you must first remove the second Management Server node from its load balancer, make the change, and then add the Management Server back. For example:

  1. Remove edge-management-server/1 from the Management Server load balancer.
  2. Apply the TLS change to Edge SSO.
  3. Add edge-management-server/1 back to the Management Server load balancer.

Configure Edge SSO for the Edge management API and Edge UI

After you complete an installation of Edge, you can enable and configure the Edge SSO module:

  1. Create the load balancer for Edge SSO as described above.
  2. Select the Edge Tile in the Ops Manager.
  3. Select Resource Config to specify the load balancer for Edge SSO.
  4. In Resource Config, add the Edge SSO load balancer name in the LOAD BALANCERS column for the Management Server.
  5. Save your changes.
  6. Select Edge SSO in the Setting tab.
  7. Select Enable Edge SSO on Management Server and Edge UI.
  8. Set the following properties, then save and apply your changes:
    Property Description
    SSO profile Set to saml.
    Edge management API scheme.

    Set to the protocol for the Edge management API. Options are http (default) and https.

    Set to https if you enabled TLS on the load balancers for the Edge Management Server, as recommended by Apigee.

    See Installing Edge using Ops Manager for more.

    Postgres port

    The port on the Postgres server used by the Edge SSO module. The default value is 5432.

    You only need to set it to a different value if you changed the port when you installed Edge.

    Externally accessible IP or DNS name of apigee-sso

    The IP address or domain name is defined by the load balancer for Edge SSO.

    Omit the protocol (http:// or https://) from this field and just specify the IP address or DNS name. Specify the protocol below in SSO public URL scheme.

    SSO public port The port used to access Edge SSO. The default value is 9099, but this should be set to the port on the load balancer that handles requests to Edge SSO.
    SSO Tomcat profile

    Sets the mode (HTTP or HTTPS) of the Tomcat server that handles requests to the Edge SSO module. Set to DEFAULT to use HTTP access.

    Note: Edge requires that you create a load balancer for Edge SSO and recommends that you enable TLS on the load balancer. If you enabled TLS on the load balancers for the Edge SSO, then set this property to SSL_PROXY.

    If you want to enable TLS on Edge SSO itself, set this property to SSL_TERMINATION.

    For more in configuring TLS/HTTPS access, see Optional: Enable TLS on Edge SSO and Configure apigee-sso for HTTPS access for more.

    SSO Tomcat port The actual port that Edge SSO listens to for requests. Typically you set this to the default port of 9099.
    SSO Tomcat keystore path (if Tomcat Profile is set to SSL_TERMINATION)

    If you set SSO Tomcat profile=SSL_TERMINATION, the absolute path on the Management Server node for the keystore JKS file.

    If you created the keystore file as described above in Optional: Enable TLS on Edge SSO, set this property to: /opt/apigee/customer/application/apigee-sso/tomcat-ssl/keystore.jks

    See Configure apigee-sso for HTTPS access for more.

    SSO Tomcat keystore alias (if Tomcat profile is set to SSL_TERMINATION)

    If you set SSO Tomcat profile=SSL_TERMINATION, the keystore alias specified when you created the keystore file.

    See Configure apigee-sso for HTTPS access for more.

    SSO Tomcat keystore password (if Tomcat profile is set to SSL_TERMINATION)

    If you set SSO Tomcat profile=SSL_TERMINATION, the password specified when you created the keystore.

    See Configure apigee-sso for HTTPS access for more.

    SSO Tomcat proxy port

    Specify the port number on the load balancer for terminating TLS, if you enabled TLS on the load balancer. This port number is necessary for Edge SSO to redirect URLs.

    See Configure apigee-sso for HTTPS access for more.

    SSO public URL scheme. Set to https if TLS is enabled

    If you enable TLS/HTTPS on the Edge SSO module, set to https. Otherwise set to http.

    Set SSO Tomcat profile=SSL_TERMINATION or SSL_PROXY to enable TLS access. For more in configuring TLS/HTTPS access, see Configure apigee-sso for HTTPS access for more.

    SSO admin name Edge SSO admin username.
    SSO admin password Edge SSO admin password using uppercase, lowercase, number, and special chars.
    Name of SAML IDP For example, okta or adfs.
    Text displayed to users when they attempt to access Edge UI Text string displayed to users when they first attempt to access the Edge UI.
    The metadata URL from your IDP

    Either the metadata URL from your IDP, or the absolute path of the metadata file on the server.

    If you specify the absolute path of the metadata file, then you must first copy the file to the same location on each Management Server server. See Prerequisite: Create the TLS keys and certificates for information on copying a file to a server.

    For example, copy the file to: /opt/apigee/customer/application/apigee-sso/saml/metadata.xml

    Then specify that path as the value of this property.

    Skip TLS validation on metadata URL

    Specifies to skip TLS validation for the metadata URL specified by your SAML IDP.

    Set to "y," if the metadata URL uses a self-signed cert, otherwise set to "n."

    JWT Signing key

    The absolute path on the Management Server node for the JWT signing key you created above in "Create the TLS keys and certificates."

    Set to: /opt/apigee/customer/application/apigee-sso/jwt-keys/privkey.pem

    JWT Verification key

    The absolute path on the Management Server node for the JWT verification key you created above in "Create the TLS keys and certificates."

    Set to: /opt/apigee/customer/application/apigee-sso/jwt-keys/pubkey.pem

    SAML service provider key

    The absolute path on the Management Server node for the verification key you created above in "Create the TLS keys and certificates."

    Set to: /opt/apigee/customer/application/apigee-sso/saml/server.key

    SAML service provider cert

    The absolute path on the Management Server node for the verification key you created above in "Create the TLS keys and certificates."

    Set to: /opt/apigee/customer/application/apigee-sso/saml/selfsigned.crt

    SAML service provider passphrase

    The passphrase used when you created the SAML cert and key, if the cert and key use a passphrase.

    Note that the section above, "Prerequisite: Create the TLS keys and certificates" removes the passphrase.

    Edge UI public URLs as comma separated string

    Comma separated list of URLs for the Edge UI, in the format:

    http_or_https://IP_or_hostname_of_UI:port

    This URL is defined by the load balancer that you specified for the Edge UI, when you installed Edge. See Installing Edge using Ops Manager for more.

    Edge UI Oauth client name The name of the OAuth client used to connect to apigee-sso. For example, edgeui.
    Edge UI Oauth client secret Oauth client password using uppercase, lowercase, number, and special chars.
    Overwrite existing Edge UI client

    If set, the existing EDGEUI client is deleted and a new one is created.

    Set to "y" when you configure SAML and change the value of any of the following properties:

    • Edge UI public URLs as comma separated string
    • Edge UI Oauth client name
    • Edge UI Oauth client secret

    Configure the portal to use SAML to communicate with Edge

    You can enable Edge SSO for API BaaS at the same time that you enable and configure the Edge SSO module for Edge, or later.

    See Configuring the Developer Services portal to use SAML to communicate with Edge for an overview of how the portal uses SAML to communicate with Edge.

    About machine users

    When SAML is enabled, Edge supports automated OAuth2 token generation by employing machine users. A machine user can obtain the OAuth2 tokens without having to specify a passcode. That means you can completely automate the process of obtaining and refreshing the OAuth2 tokens.

    The SAML configuration process for the portal automatically creates a machine user in the organization associated with the portal. The portal then uses this machine user account to connect to Edge. For more on machine users, see Using SAML with automated tasks.

    Before you configure the portal to use SAML

    Before you can configure the portal to use SAML to communicate with Edge, you have to add the e-mail address of the machine user to the Edge organization.

    Configuring the portal to use SAML

    After you complete an installation of Edge, you can enable and configure the portal to use SAML to connect to Edge:

    1. Log in to the Edge UI.
    2. Add the e-mail address of the machine user to the organization associated with the portal as an Organization Administrator. Note: The machine user does not exist yet, but is created automatically in the steps below.
    3. Select the Edge Tile in the Ops Manager.
    4. Select SSO in the Setting tab.
    5. Select Install Edge SSO.
    6. Configure SSO for Edge as described above.
    7. Select Enable SSO on portal.
    8. Set the properties shown in the table below and then save and apply your changes. When you apply these changes, Edge automatically creates the machine user.
    Property Description
    Oauth client name to connect to SSO The name of the OAuth client used to connect to apigee-sso. For example, portalcli.
    The Oauth client secret to connect to SSO The Oauth client password using uppercase, lowercase, number, and special chars.
    Overwrite the existing portal client Set to "y" when you configure SAML and change the value of any of the portal properties.
    Dev Portal admin e-mail An e-mail address for the machine user created in the Edge org.
    Dev Portal admin first name First name of the machine user created in the Edge org.
    Dev Portal admin last name Last name of the machine user created in the Edge org.
    Dev Portal admin password A password of the machine user created in the Edge org.
    An org associated with the Dev Portal The name of the Edge organization associated with the portal.