Send Docs Feedback

Using TLS on the portal

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, the cloud-based hosting service for the portal. 
  • Apigee Edge for Private Cloud: Configure TLS on-premises on the server hosting the portal. 

When configuring TLS settings in the cloud, if an update to sites/default/settings.php is required, to avoid Git conflicts Apigee recommends that you edit sites/default/settings.local.php instead of editing sites/default/settings.php directly.

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. 

Apigee recommends that you configure the Private Cloud version of the Edge management API to use TLS, unless you have deployed both Edge and the portal behind a firewall with no public access. For information on configuring Edge to use TLS, see the Edge Operations Guide.

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. 

However, in both instances you must obtain your own TLS certificate before you can deploy the portal to a production environment. 

Cloud-based portals

Portals deployed in the cloud on Pantheon are preconfigured with three environments: development, test, and production. The way you configure and use TLS depends on the environment:

  • Development and test environments: Requests can use http:// or https://. Requests over https:// use the Apigee TLS certificate so that you can build and test your portal. However, you must obtain your own TLS certificate to move to a production environment.
  • Production environment: If you want to encrypt portal data transfers, then you require your own TLS certificate. 

You use the Pantheon UI to configure TLS for the portal. Before starting this process, you should be familiar with the Pantheon documentation:

http://helpdesk.getpantheon.com/customer/portal/articles/385443

You must have access to the Pantheon dashboard to configure TLS. You can get access by requesting it from your portal administrator, or by making a request to Apigee Support.

To configure TLS for the portal in Pantheon:

  1. Obtain an TLS certificate.
  2. Log in to Pantheon at https://dashboard.getpantheon.com/login.
  3. Use the instructions at http://helpdesk.getpantheon.com/customer/portal/articles/385443 to:
    • Generate the RSA Key (.key) and CSR (certificate signing request).
    • Enable TLS.
    • Enter the RSA Key and CSR.
  4. In Pantheon, select Domains > Domain Setup.
  5. Ensure that the IP address generated when you registered your TLS certificate appears as a record type of A, references the generated IP directly, and does not use a redirect.

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. By default, Apigee installs the Apache web server. For information on configuring TLS for Apache, see https://www.drupal.org/https-information

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_maslifetime 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:

The following assumes your load balancer is configured to include the X-Forwarded-Proto HTTP header.

// 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');
    // 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:

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.

All Canonical Name records (CNAMEs) in your DNS must have corresponding certificates. For *.devportal.apigee.com, a default certificate is provided.

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.com).

In this scenario, if a developer is visiting your portal at live-example.devportal.apigee.com, 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.

Replace devportal.example.com with your custom hostname. In addition, Apigee Edge on-premise users need to replace the PANTHEON_ENVIRONMENT switch condition with a value that makes sense in their environment.
  // 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;
  }
}
 

Help or comments?