Configuring Route Service Lookup

This topic describes configuring route service lookup in Pivotal Application Service (PAS).

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 option in the Networking pane of the PAS tile allows you to configure how the router handles traffic for apps that are bound to route services. The configuration options are as follows:

  • Default lookup:
    • Default lookup is configured when you do not select Bypass security checks for route service lookup. In this case, the router does not check for an existing route. It sends traffic back through the load balancer when the traffic is for an internal route service.
  • Bypass mode:
    • Bypass mode is configured when you select Bypass security checks for route service lookup. The router checks for an existing route. If the router finds the route and the route service is internal, it sends the traffic directly to the route service and skips the load balancer. This improves performance, but introduces the security risk described in Bypass Mode and External Route Service (Security Risk).

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

For configuration guidance and procedures, see Configure Route Service Lookup.

Configure Route Service Lookup

This following sections provide guidance and configuration steps for route service lookup.

Guidance

Pivotal recommends that you do not configure PAS for bypass mode because of the security risk described in Bypass Mode and External Route Service (Security Risk). However, you may need to do so if your load balancer requires mutual TLS from clients.

If your load balancer requires mutual TLS from clients and PAS is configured for default lookup, the router cannot handle traffic successfully for internal route services. This is because the router does not have the necessary certificates from the client to communicate back with the load balancer for DNS lookup. Therefore you must configure bypass mode so the router can send the traffic directly to the route service.

Configuring 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 steps in Mitigate Security Risk.

Mitigate Security Risk

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

  1. Create an org for use by the PAS administrator.

  2. Register all external route service domains as private domains in the org you created.

  3. Monitor PAS for the addition of new external route services and ensure you follow the same process for those. One way to do this is by using cf curl to regularly view a list of user-provided service instances. You can do this by running cf curl /v2/user_provided_service_instances.

    Note: Since route services can be added by any space developer, this may be difficult to manage.

Configuring 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. Communicate to developers of route services that the domain name for their internally hosted route services must resolve to the load balancer.

  3. If your load balancer or router terminates TLS:

    1. Work with developers of route services to ensure the load balancer or router have TLS certificates that are valid for the route service URL.
    2. Ensure that the TLS certificate from your load balancer is either signed by a well known CA, or the CA has been added to the Certificate Authorities trusted by Router and HAProxy field in the Networking pane of the PAS and Isolation Segment tiles. The CA for the TLS certificate provided by the load balancer must be trusted by the Router.
  4. Work with route service developers 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 PAS 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 PAS 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 PAS 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. If all of your route services are hosted internally on the same foundation, you are not at risk for this vulnerability. However, you would be at risk if externally hosted route services are later configured.

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 PAS 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.