Configuring Advanced Networking for AEM as a Cloud Service configuring-advanced-networking

This article introduces the different advanced networking features in AEM as a Cloud Service, including self-service and API provisioning of VPN, non-standard ports, and dedicated egress IP addresses.

Overview overview

AEM as a Cloud Service offers the following advanced networking options:

This article describes each of these options in detail and why you might use them, before describing how they are configured using the Cloud Manager UI and by using the API. The article concludes with some advanced use cases.

Requirements and Limitations requirements

When configuring advanced networking features, the following restrictions apply.

Configuring and Enabling Advanced Networking configuring-enabling

Using advanced networking features requires two steps:

Both steps can be done either using the Cloud Manager UI or the Cloud Manager API.

Flexible Port Egress flexible-port-egress

This advanced networking feature lets you configure AEM as a Cloud Service to egress traffic through ports other than HTTP (port 80) and HTTPS (port 443), which are open by default.

UI Configuration configuring-flexible-port-egress-provision-ui

A new record appears below the Network Infrastructure heading in the side panel including details of the type of infrastructure, status, region, and environments on which it has been enabled.

API Configuration configuring-flexible-port-egress-provision-api

Once per program, the POST /program/<programId>/networkInfrastructures endpoint is invoked, simply passing the value of flexiblePortEgress for the kind parameter and region. The endpoint responds with the network_id, and other information including the status.

Once called, it typically takes approximately 15 minutes for the networking infrastructure to be provisioned. A call to the Cloud Manager’s network infrastructure GET endpoint would show a status of ready.

Traffic Routing flexible-port-egress-traffic-routing

For http or https traffic going to ports other than 80 or 443 a proxy should be configured using the following host and port environment variables:

For example, here’s sample code to send a request to www.example.com:8443:

String url = "www.example.com:8443"
String proxyHost = System.getenv().getOrDefault("AEM_PROXY_HOST", "proxy.tunnel");
int proxyPort = Integer.parseInt(System.getenv().getOrDefault("AEM_HTTPS_PROXY_PORT", "3128"));
HttpClient client = HttpClient.newBuilder()
      .proxy(ProxySelector.of(new InetSocketAddress(proxyHost, proxyPort)))
      .build();

HttpRequest request = HttpRequest.newBuilder().uri(URI.create(url)).build();
HttpResponse<String> response = client.send(request, BodyHandlers.ofString());

If using non-standard Java™ networking libraries, configure proxies using the properties above, for all traffic.

Non-http/s traffic with destinations through ports declared in the portForwards parameter should reference a property called AEM_PROXY_HOST, along with the mapped port. For example:

DriverManager.getConnection("jdbc:mysql://" + System.getenv("AEM_PROXY_HOST") + ":53306/test");

The table below describes traffic routing:

Apache / Dispatcher Configuration apache-dispatcher

The AEM Cloud Service Apache/Dispatcher tier’s mod_proxy directive can be configured using the properties described above.

ProxyRemote "http://example.com:8080" "http://${AEM_PROXY_HOST}:3128"
ProxyPass "/somepath" "http://example.com:8080"
ProxyPassReverse "/somepath" "http://example.com:8080"

SSLProxyEngine on //needed for https backends

ProxyRemote "https://example.com:8443" "http://${AEM_PROXY_HOST}:3128"
ProxyPass "/somepath" "https://example.com:8443"
ProxyPassReverse "/somepath" "https://example.com:8443"

Dedicated Egress IP Address dedicated-egress-ip-address

A dedicated IP address can enhance security when integrating with SaaS vendors (like a CRM vendor) or other integrations outside of AEM as a Cloud Service that offer an allowlist of IP addresses. By adding the dedicated IP address to the allowlist, it ensures that only traffic from the AEM Cloud Service is permitted to flow into the external service. This is in addition to traffic from any other IPs allowed.

The same dedicated IP is applied to all programs in your Adobe Organization and for all environments in each of your programs. It applies to both Author and Publish services.

Without the dedicated IP address feature enabled, traffic coming out of AEM as a Cloud Service flows through a set of IPs shared with other customers of AEM as a Cloud Service.

Configuring dedicated egress IP address is similar to flexible port egress. The main difference is that after configuration, traffic will always egress from a dedicated, unique IP. To find that IP, use a DNS resolver to identify the IP address associated with p{PROGRAM_ID}.external.adobeaemcloud.com. The IP address is not expected to change, but if it must change, advanced notification is provided.

UI Configuration configuring-dedicated-egress-provision-ui

A new record appears below the Network Infrastructure heading in the side panel including details of the type of infrastructure, status, region, and environments on which it has been enabled.

API Configuration configuring-dedicated-egress-provision-api

Once per program, the POST /program/<programId>/networkInfrastructures endpoint is invoked, simply passing the value of dedicatedEgressIp for the kind parameter and region. The endpoint responds with the network_id, and other information including the status.

Once called, it typically takes approximately 15 minutes for the networking infrastructure to be provisioned. A call to the Cloud Manager’s network infrastructure GET endpoint would show a status of ready.

Traffic Routing dedicated-egress-ip-traffic-routing

Http or https traffic go through a preconfigured proxy, provided they use standard Java™ system properties for proxy configurations.

Non-http/s traffic with destinations through ports declared in the portForwards parameter should reference a property called AEM_PROXY_HOST, along with the mapped port. For example:

DriverManager.getConnection("jdbc:mysql://" + System.getenv("AEM_PROXY_HOST") + ":53306/test");

Feature Usage feature-usage

The feature is compatible with Java™ code or libraries that result in outbound traffic, provided they use standard Java™ system properties for proxy configurations. In practice, this should include most common libraries.

Below is a code sample:

public JSONObject getJsonObject(String relativePath, String queryString) throws IOException, JSONException {
  String relativeUri = queryString.isEmpty() ? relativePath : (relativePath + '?' + queryString);
  URL finalUrl = endpointUri.resolve(relativeUri).toURL();
  URLConnection connection = finalUrl.openConnection();
  connection.addRequestProperty("Accept", "application/json");
  connection.addRequestProperty("X-API-KEY", apiKey);

  try (InputStream responseStream = connection.getInputStream(); Reader responseReader = new BufferedReader(new InputStreamReader(responseStream, Charsets.UTF_8))) {
    return new JSONObject(new JSONTokener(responseReader));
  }
}

Some libraries require explicit configuration to use standard Java™ system properties for proxy configurations.

An example using Apache HttpClient that requires explicit calls to
HttpClientBuilder.useSystemProperties() or use
HttpClients.createSystem():

public JSONObject getJsonObject(String relativePath, String queryString) throws IOException, JSONException {
  String relativeUri = queryString.isEmpty() ? relativePath : (relativePath + '?' + queryString);
  URL finalUrl = endpointUri.resolve(relativeUri).toURL();

  HttpClient httpClient = HttpClientBuilder.create().useSystemProperties().build();
  HttpGet request = new HttpGet(finalUrl.toURI());
  request.setHeader("Accept", "application/json");
  request.setHeader("X-API-KEY", apiKey);
  HttpResponse response = httpClient.execute(request);
  String result = EntityUtils.toString(response.getEntity());
}

Debugging Considerations debugging-considerations

To validate that traffic is indeed outgoing on the expected dedicated IP address, check logs in the destination service, if available. Otherwise, it may be useful to call out to a debugging service such as http://ifconfig.me/ip, which returns the calling IP address.

Virtual Private Network (VPN) vpn

A VPN allows connecting to an on-premise infrastructure or data center from the author, publish, or preview instances. This can be useful, for example, to secure access to a database. It also allows connecting to SaaS vendors such as a CRM vendor that supports VPN or connecting from a corporate network to AEM as a Cloud Service author, preview, or publish instance.

Most VPN devices with IPSec technology are supported. Consult the information in the RouteBased configuration instructions column in this list of devices. Configure the device as described in the table.

UI Configuration configuring-vpn-ui

A new record appears below the Network Infrastructure heading in the side panel including details of the type of infrastructure, status, region, and environments on which it has been enabled.

API Configuration configuring-vpn-api

Once per program, the POST /program/<programId>/networkInfrastructures endpoint is invoked. It passes in a payload of configuration information. That information includes the value of vpn for the kind parameter, region, address space (list of CIDRs - note that this cannot be modified later), DNS resolvers (for resolving names in your network). It also includes VPN connection information such as gateway configuration, shared VPN key, and the IP Security policy. The endpoint responds with the network_id, and other information including the status.

Once called, it typically takes from 45 through 60 minutes for the networking infrastructure to be provisioned. The GET method in the API can be called to return the status, which eventually flips from creating to ready. Consult the API documentation for all states.

Traffic Routing vpn-traffic-routing

The table below describes traffic routing.

Useful Domains for Configuration vpn-useful-domains-for-configuration

The diagram below provides a visual representation of a set of domains and associated IPs that are useful for configuration and development. The table further below the diagram describes those domains and IPs.

Restrict VPN to Ingress Connections restrict-vpn-to-ingress-connections

If you want to allow only VPN access to AEM, environment allowlists can be configured in Cloud Manager so that only the IP defined by p{PROGRAM_ID}.external.adobeaemcloud.com is allowed to talk to the environment. This can be done the same way as any other IP-based allowlist in Cloud Manager.

If rules must be path-based, use standard http directives at the Dispatcher level to deny or allow certain IPs. They should ensure that the desired paths are also not cacheable at the CDN so that the request always gets to origin.

Httpd Config Example httpd-example

Order deny,allow
Deny from all
Allow from 192.168.0.1
Header always set Cache-Control private

Enabling Advanced Networking Configurations on Environments enabling

Once you have configured an advanced networking option for a program, whether flexible port egress, dedicated egress IP address, or VPN, to use it, you must enable it at the environment level.

When you enable an advanced networking configuration for an environment, you can also enable optional port forwarding and non-proxy hosts. Parameters are configurable per environment to offer flexibility.

Enabling Using the UI enabling-ui

The advanced networking configuration is applied to the selected environment. Back on the Environments tab, you can see the details of the configuration applied to the selected environment and their status.

Enabling Using the API enabling-api

To enable an advanced networking configuration for an environment, the PUT /program/<program_id>/environment/<environment_id>/advancedNetworking endpoint must be invoked per environment.

The API should respond in just a few seconds, indicating a status of updating. After about 10 minutes, a call to the Cloud Manager’s environment GET endpoint shows a status of ready, indicating that the update to the environment is applied.

Per environment port forwarding rules can be updated by invoking the PUT /program/{programId}/environment/{environmentId}/advancedNetworking endpoint, and including the full set of configuration parameters, rather than a subset.

Dedicated egress IP address and VPN advanced networking types support a nonProxyHosts parameter. This lets you declare a set of hosts that should route through a shared IPs address range rather than the dedicated IP. The nonProxyHost URLs may follow the patterns of example.com or *.example.com, where the wildcard is only supported at the start of the domain.

Even if there are no environment traffic routing rules (hosts or bypasses), PUT /program/<program_id>/environment/<environment_id>/advancedNetworking must still be called, just with an empty payload.

Editing and Deleting Advanced Networking Configurations on Environments editing-deleting-environments

After enabling advanced networking configurations to environments, you can update the details of those configurations or delete them.

Editing or Deleting using the UI editing-ui

The changes are reflected on the Environments tab.

Editing or Deleting using the API editing-api

To delete advanced networking for a particular environment, invoke DELETE [/program/{programId}/environment/{environmentId}/advancedNetworking]().

Editing and Deleting a Program’s Network Infrastructure editing-deleting-program

Once network infrastructure is created for a program, only limited properties can be edited. If you no loner require it, you can delete the advanced networking infrastructure for your entire program.

Editing and Deleting with the UI delete-ui

The changes are reflected on the Environments tab.

Editing and Deleting with the API delete-api

To delete the network infrastructure for a program, invoke DELETE /program/{program ID}/networkinfrastructure/{networkinfrastructureID}.

Changing a Program’s Advanced Networking Infrastructure Type changing-program

It is only possible to have one type of advanced networking infrastructure configured for a program at a time, The advanced networking infrastructure must either flexible port egress, dedicated egress IP address, or VPN.

If you decide that you need another advanced networking infrastructure type than the one you have already configured, delete the existing one, and create another one. Do the following:

Advanced Networking Configuration for Other Publish Regions advanced-networking-configuration-for-additional-publish-regions

When an additional region is added to an environment that already has advanced networking configured, traffic from the additional publish region that matches the advanced networking rules route through the primary region by default. However, if the primary region becomes unavailable, the advanced networking traffic is dropped if advanced networking hasn’t been enabled in the additional region. If you want to optimize latency and increase availability in case one of the regions undergoes an outage, it is necessary to enable advanced networking for the additional publish regions. Two different scenarios are described in the following sections.

Dedicated Egress IP Addresses additional-publish-regions-dedicated-egress

Advanced networking already enabled in the primary region already-enabled

If an advanced networking configuration is already enabled in the primary region, follow these steps:

Advanced networking not yet configured in any region not-yet-configured

The procedure is mostly similar to the previous instructions. However, if the production environment has not yet been enabled for advanced networking, there is an opportunity to test the configuration by first enabling it in a staging environment:

VPN vpn-regions

The procedure is nearly identical to the dedicated egress IP addresses instructions. The only difference is that in addition to the region property being configured differently from the primary region, the connections.gateway field can optionally be configured. The configuration can route to a different VPN endpoint operated by your organization, geographically closer to the new region.