Using TLS on the portal

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

You can configure the portal to use TLS. The TLS configuration procedure for the portal depends on how you have deployed the portal:

• Cloud: Configure TLS from Pantheon or Acquia, the cloud-based hosting services for the portal.
• Apigee Edge for Private Cloud: Configure TLS on-premises on the server hosting the portal.

TLS and the portal

The following image show the two places where the portal uses TLS:

1. For communication between the portal and the Edge management API.
   
   The portal does not function as a stand-alone system. Instead, much of the information used by the portal is actually stored on Edge, where Edge can be deployed either in the cloud or on-premises as a Private Cloud installation. When necessary, the portal makes an HTTP or HTTPS request to the Edge management API to retrieve information or to send information.
   
   When you create your portal, one of the first steps you must perform is to specify the URL of the Edge management API. Depending on how the Edge management API is configured, that URL can use TLS. See Creating a developer portal for more.
2. For communication between developers and the portal.
   
   When you use the Developer Services portal to deploy your APIs, your developers log in to the portal to register apps and receive API keys. The login credentials and the API key are proprietary information that you want to send over HTTPS to ensure their security. This type of proprietary information should be sent over HTTPS.
   
   The way you configure TLS for this scenario depends on how you have deployed the portal: cloud or Apigee Edge for Private Cloud. The following sections describe both scenarios.

Configuring TLS between the portal and the Edge management API

The configuration of the Edge management API determines whether or not communication can use TLS. If the Edge management API is configured to use TLS, then the portal can use HTTPS. Otherwise, the portal communicates with Edge over HTTP. Therefore, as a portal developer, you only need to know how Edge is configured to set the connection between the portal and Edge.

For the procedure that you use to configure the connection to the Edge management API, see Creating a developer portal.

Cloud-based version of Edge

If your portal connects to the cloud-based version of Edge, then the URL for the Edge management API is preconfigured by Apigee to use TLS. When configuring the portal, you access the Edge management API by using the URL https://api.enterprise.apigee.com/v1.

Private Cloud installation of Edge

For a Private Cloud installation of Edge, the URL of the Edge management API is in the form:
http://EdgePrivateCloudIp:8080/v1
or:
https://EdgePrivateCloudIp:TLSport/v1

where EdgePrivateCloudIp is the IP address of the Edge Management Server server and TLSport is the TLS port for the Edge management API. For example, the port number could be 8443 or even 8080 based on the Edge configuration.

Configuring TLS between developers and the portal

The way you configure TLS between developers and the portal depends on how you deployed the portal: cloud or Apigee Edge for Private Cloud.

Cloud-based portals

Pantheon

Pantheon provides free automated HTTPS for all sites on its platform through the Pantheon Global CDN and using Let's Encrypt. See also HTTPS on Pantheon's Global CDN.

Acquia

To enable TLS/SSL using Acquia, see Enabling SSL.

Edge for Private Cloud portals

All Apigee recommended Private Cloud installations of the portal require the portal to be behind a load balancer, as shown below:

Therefore, for on-premises installations, you have two options for configuring TLS:

• Configure TLS on the load balancer: Configure TLS on the load balancer itself, and not on the portal. The procedure that you use to configure TLS is therefore dependent on the load balancer. See the documentation on your load balancer for more information.
• Configure TLS on the portal itself: If necessary, you can configure TLS on the web server that hosts the portal. See Configuring the portal to use HTTPS for more information.

You must obtain your own TLS certificate before you can deploy the portal to a production environment.

Configuring additional TLS settings

You can edit the sites/default/settings.local.php (cloud) or sites/default/settings.php (Private Cloud) file to make configuration changes to TLS for the portal.

When editing the file, add instances of the ini_set() function to set a property. For more information on this function, see: http://php.net/manual/en/function.ini-set.php.

You can set the following properties in the sites/default/settings.local.php (cloud) or sites/default/settings.php (Private Cloud) file:

• cookie_httponly: (Recommended) Specifies that cookie as accessible only over the HTTP protocol. Set this property as:
  
  ini_set('session.cookie_httponly', true);
• session.cookie_secure - (Optional) Specifies that cookies can only be sent over secure connections. However, this means that all content must be served over HTTPS. If this setting is enabled, the site will not work over HTTP. Set this property as:
  
  ini_set('session.cookie_secure', true);
• gc_maxlifetime and cookie_lifetime: (Optional) gc_lifeteime specifies the number of seconds after which data can potentially be cleaned up, and cookie_lifetime specifies the lifetime of the cookie in seconds. Set these properties as:
  
  ini_set('session.gc_maxlifetime', 3600);
  ini_set('session.cookie_lifetime', 3600);

For more information on setting up TLS between the developer portal and clients, see Enable SSL for Secure HTTPS Communication on the Pantheon doc site.

Configuring TLS with Load Balancers

For better performance, load balancers are sometimes configured to perform TLS termination. With TLS termination, load balancers decrypt messages sent over https:// and forward the messages to backend servers over http://. That saves backend servers the overhead of decrypting https:// messages themselves.

If load balancers forward unencrypted http messages to servers in the same data center, security is not an issue. However, if load balancers forward messages over http:// to servers outside the data center, such as your Apigee developer portal, the messages are unencrypted, which opens a security hole.

If your developer portal sits behind load balancers that are using TLS termination, and you want all traffic served over https://, the website pages will need to contain https:// links only and you will need to add the following code to your developer portal sites/default/settings.local.php (cloud) or sites/default/settings.php (Private Cloud) file. Because the load balancer does not automatically transform the content of the HTML pages, the code ensures that all links passed to the client start with https://.

To configure TLS with load balancers, add the following lines to the sites/default/settings.local.php (cloud) or sites/default/settings.php (Private Cloud) file:

// Only check for SSL if we are not using PHP from the command line.
if (PHP_SAPI != 'cli') {
  // Assume we can't detect SSL unless proven otherwise.
  $can_detect_ssl = FALSE;

  // Set HTTPS URL of portal 
  $base_url = 'https://developers.myCo.com';

  if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) || (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] == 'on')) {
    $can_detect_ssl = TRUE;
  }

  if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && strtolower($_SERVER['HTTP_X_FORWARDED_PROTO']) == 'https') {
    $_SERVER['HTTPS'] = 'on';
  }

  if ($can_detect_ssl && $_SERVER['HTTPS'] != 'on') {
    header('HTTP/1.0 301 Moved Permanently');
    // You could optionally substitute a canonical server name for $_SERVER['HTTP_HOST'] here.
    header('Location: https://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI']);
    exit;
  }
}

For more information, see:

• https://drupal.org/node/425990
• https://drupal.org/node/313145
• http://drupal.stackexchange.com/questions/102091/drupal-behind-a-ssl-offloading-reverse-proxy-is-this-config-correct

Redirecting portal traffic to HTTPS

You can redirect all portal traffic to HTTPS by updating your sites/default/settings.local.php (cloud) or sites/default/settings.php (Private Cloud) file. The updates required vary based on whether you are redirecting to HTTPS on the same hostname or multiple hostnames.

Redirecting to HTTPS on the same hostname

Add the following code to your sites/default/settings.local.php (cloud) or sites/default/settings.php (Private Cloud) file to redirect to all portal traffic to HTTPS on the same hostname (for example, *.devportal.apigee.io).

In this scenario, if a developer is visiting your portal at live-example.devportal.apigee.io, but needs to access a certificate that was uploaded for devportal.example.com, the request will fail.

// Only check for SSL if we are not using PHP from the command line.
if (PHP_SAPI != 'cli') {
  // Assume we can't detect SSL unless proven otherwise.
  $can_detect_ssl = FALSE;

  if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) || (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] == 'on')) {
    $can_detect_ssl = TRUE;
  }

  if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && strtolower($_SERVER['HTTP_X_FORWARDED_PROTO']) == 'https') {
    $_SERVER['HTTPS'] = 'on';
  }

  if ($can_detect_ssl && $_SERVER['HTTPS'] != 'on') {
    header('HTTP/1.0 301 Moved Permanently');
    header('Location: https://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI']);
    exit;
  }
}

Redirecting to HTTPS on multiple hostnames

Add the following code to your sites/default/settings.local.php file (cloud) or sites/default/settings.php file (Private Cloud) to redirect to all portal traffic to HTTPS on multiple hostnames.

  // Only check for SSL if we are not using PHP from the command line.
if (PHP_SAPI != 'cli') {
  // Assume we can't detect SSL unless proven otherwise.
  $can_detect_ssl = FALSE;
  // Assume we are not forcing a redirect until proven otherwise.
  $force_redirect = FALSE;

  if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) || (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] == 'on')) {
    $can_detect_ssl = TRUE;
  }

  if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && strtolower($_SERVER['HTTP_X_FORWARDED_PROTO']) == 'https') {
    $_SERVER['HTTPS'] = 'on';
  }
  
  if ($can_detect_ssl && $_SERVER['HTTPS'] != 'on') {
    // We will force a redirect because HTTPS is required.
    $force_redirect = TRUE;
  }
  
  // This works on Pantheon only; the constant is undefined elsewhere.
  switch (PANTHEON_ENVIRONMENT) {
    case 'dev':
      $canonical_hostname = 'dev.devportal.example.com';
      break;
    case 'test':
      $canonical_hostname = 'test.devportal.example.com';
      break;
    case 'live':
      $canonical_hostname = 'devportal.example.com';
      break;
    default:
      $canonical_hostname = strtolower($_SERVER['HTTP_HOST']);
      break;
  }
  if ($canonical_hostname != strtolower($_SERVER['HTTP_HOST'])) {
    // We will force a redirect because hostname is not canonical.
    $force_redirect = TRUE;
  }

  if ($force_redirect) {
    header('HTTP/1.0 301 Moved Permanently');
    header('Location: https://' . $canonical_hostname . $_SERVER['REQUEST_URI']);
    exit;
  }
}