Configuring Route Service Lookup

Page last updated:

Warning: Pivotal Cloud Foundry (PCF) v2.5 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.

This topic describes how Pivotal Application Service (PAS) administrators can configure route service lookup.

Overview

Developers can bind their app to a route service to preprocess requests before they reach an app. Example use cases include authentication, rate limiting, and caching services. For more information, see Route Services.

The Bypass security checks for route service lookup field in the PAS tile allows you to configure how the router handles traffic for apps that are bound to route services.

The table below describes the configuration options and provides guidance for when to select which option:

Configuration Option Explanation When to Select
Default Lookup The router uses the load balancer for DNS lookup of the route service instead of checking for an existing route. Select this option if your load balancer does not require mutual TLS from clients.

Reason: To avoid risk. While bypass mode would improve performance, it introduces the security risk described in Bypass Mode and External Route Service (Security Risk).
Bypass Mode The router checks for an existing route instead of sending the request to the load balancer for DNS lookup. Select this option if your load balancer requires mutual TLS from clients.

Reason: To avoid request failure when an app is bound to an internal route service. If you do not configure bypass mode, requests fail because the router does not have the necessary certificates from the client to communicate back with the load balancer for DNS lookup.

For more details, see Summary of Behavior in Different Configurations.

For configuration procedures, see Configure Route Service Lookup.

Configure Route Service Lookup

This following sections provide configuration steps for route service lookup. Review the guidance in the Overview section before configuring route service lookup.

Configure PAS for Bypass Mode

To configure bypass mode:

  1. Select Bypass security checks for route service lookup in the Networking pane of the PAS tile.

  2. Follow the procedure in Mitigate Security Risk.

Mitigate Security Risk

To prevent users from intercepting traffic for externally hosted route services:

  1. Work with developers running apps on PAS to identify all external route services. You can list all user-provided service instances by running:

    cf curl /v2/user_provided_service_instances
    
  2. Create an org for use by the PAS administrator by running:

    cf create-org ORG-NAME
    

    Where ORG-NAME is the name of the org you want to create.

  3. For each external route service identified, register the route service domain as a private domain in the org you created by running:

    cf create-domain ORG-NAME DOMAIN
    

    Where:

    • ORG-NAME is the name of the org you created.
    • DOMAIN is the route service domain you want to register as a private domain.
      For more information, see the Private Domains section of the Configuring Routes and Domains topic.
  4. Establish a process for monitoring PAS for the addition of new external route services so that you can repeat these steps for them. You may need to regularly curl the user_provided_service_instances endpoint.

Configure PAS for Default Lookup

To configure PAS for default lookup behavior, with bypass mode disabled:

  1. Ensure that Bypass security checks for route service lookup in the Networking pane of the PAS tile is not selected.

  2. Follow the procedure in Ensure Internal Route Services are Reachable.

Ensure Internal Route Services are Reachable

To ensure that internal route services are reachable:

  1. Communicate to developers of route services that the domain name for their internally hosted route services must resolve to the load balancer. You can list all user-provided service instances by running:

    cf curl /v2/user_provided_service_instances
    
  2. If your load balancer or router terminates TLS, work with developers of route services to ensure the load balancer or router have TLS certificates that are valid for the route service URL.

  3. Work with developers of route services to verify that their internal route service apps are reachable. You can do this by visiting the HTTPS URL of the route service directly and confirming that the app received the request with the cf logs output for the route service app.

Summary of Behavior in Different Configurations

The following sections describe how the router behaves when bypass mode is enabled or disabled and when a route service is internal or external.

Default Lookup and Internal Route Service

This section describes how the router handles app requests when the following is true:

  • The Bypass security checks for route service lookup field in the PAS tile is not selected.
  • The app is bound to a route service that is hosted on PAS.

In this case, when the router receives the request, it sends the traffic back to the load balancer to resolve DNS. The load balancer then sends the traffic back to the router.

The following diagram illustrates the flow of the request and numbers the steps to indicate order of occurrence.

A request makes multiple trips between the load balancer and router before reaching the route service. Four boxes are labeled as follows: Load Balancer, Router, Route Service, and PAS. The router and route service box are inside of the PAS box to show that they are running inside of PAS. Arrows numbered 1-5 indicate the flow of the request in the following order: load balancer, router, load balancer, router, router service.

Bypass Mode and Internal Route Service

This section describes how the router handles app requests when the following is true:

  • The Bypass security checks for route service lookup field in the PAS tile is selected.
  • The app is bound to a route service that is hosted on PAS.

In this case, when the router receives the request, it sends it directly to the route service. This assumes the router finds an existing route for the route service.

The following diagram illustrates the flow of the request.

Arrows indicate the flow of the request through platform components. A request goes directly from the load balancer to the router to the route service.

Bypass Mode and External Route Service (Security Risk)

This section describes how the router handles app requests when the following is true:

  • The Bypass security checks for route service lookup field in the PAS tile is selected.
  • The app is bound to a route service that is hosted outside of PAS.

In this case, when the router receives the request, it checks for an existing route and then sends the request directly to the route service.

This introduces the ability for route service traffic to be intercepted. A developer can register the external route service domain as a private domain in PAS and map it to their own, malicious app. When the router receives a request for the original app bound to the external route service, it will find the domain internally and send the request to the malicious app.

Note: This vulnerability exists for both externally hosted route services and route services hosted on a separate foundation.

The following diagram illustrates the flow of the request in the case that it is intercepted:

A fake route service inside of PAS intercepts traffic intended for a route service outside of PAS. Five boxes are labeled as follows: Load Balancer, Router, Route Service (example.com), Fake Route Service (example.com), and PAS. The router and fake route service boxes are inside of the PAS box to show that they are running inside of PAS. Arrows point to the load balancer and then the router to indicate the flow of traffic. Two arrows then point from the router: one to the fake route service and another to the the route service. A red "X" indicates that the traffic does not go to the route service. It goes to the fake route service instead.

Default Lookup and External Route Service

This section describes how the router handles app requests when the following is true:

  • The Bypass security checks for route service lookup field in the PAS tile is not selected.
  • The app is bound to a route service that is hosted outside of PAS.

In this case, the router sends traffic directly to the external route service without checking for an existing route.

The following diagram illustrates the flow of the request.

Arrows indicate the flow of the request through platform components. A request goes directly from the load balancer to the router to the route service.