Configuring Route Service Lookup

Page last updated:

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

Overview

You can bind your 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 checkbox in the Networking pane of the PAS tile allows you to configure how the Gorouter handles traffic for apps that are bound to route services. The configuration options are:

  • Default lookup: Default lookup is configured when you disable the Bypass security checks for route service lookup checkbox. In this case, the Gorouter 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 enable the Bypass security checks for route service lookup checkbox. The Gorouter checks for an existing route. If the Gorouter 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 information, see Summary of Behavior in Different Configurations.

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

Configure Route Service Lookup

These 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 Gorouter cannot handle traffic successfully for internal route services. This is because the Gorouter 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 Gorouter can send the traffic directly to the route service.

Configure PAS for Bypass Mode

To configure bypass mode:

  1. Navigate to the Pivotal Operations Manager Installation Dashboard.

  2. Click the PAS tile.

  3. Select Networking.

  4. Under Route services, select Enable.

  5. Enable the Bypass security checks for route service lookup checkbox.

  6. Follow the procedure 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 admin.

  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 external route services. One way to do this is by using cf curl to regularly view a list of user-provided service instances. Run:

    cf curl /v2/user_provided_service_instances
    

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

Configure PAS for Default Lookup

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

  1. Navigate to the Pivotal Operations Manager Installation Dashboard.

  2. Click the PAS tile.

  3. Select Networking.

  4. Under Route services, select Enable.

  5. Disable the Bypass security checks for route service lookup checkbox.

  6. Communicate to developers of route services that the domain name for their internally-hosted route services must resolve to the load balancer.

  7. If your load balancer or Gorouter terminates TLS:

    1. Work with developers of route services to ensure the load balancer or Gorouter 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 Certificate Authority (CA), or the CA has been added to the Certificate Authorities trusted by the Gorouter and HAProxy field in the Networking pane of the PAS and Pivotal Isolation Segment tiles. The CA for the TLS certificate provided by the load balancer must be trusted by the Gorouter.
  8. 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

These sections describe how the Gorouter 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 Gorouter handles app requests when:

  • The Bypass security checks for route service lookup checkbox in PAS is disabled.
  • The app is bound to a route service that is hosted on PAS.

In this case, when the Gorouter 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 Gorouter.

The diagram below 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 Gorouter before reaching the route service. Four boxes are labeled as follows: Load Balancer, Gorouter, Route Service, and PAS. The Gorouter 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, Gorouter, load balancer, Gorouter, Gorouter service.

Bypass Mode and Internal Route Service

This section describes how the Gorouter handles app requests when:

  • The Bypass security checks for route service lookup checkbox in PAS is enabled.
  • The app is bound to a route service that is hosted on PAS.

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

The diagram below 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 Gorouter to the route service.

Bypass Mode and External Route Service (Security Risk)

This section describes how the Gorouter handles app requests when:

  • The Bypass security checks for route service lookup checkbox in PAS is enabled.
  • The app is bound to a route service that is hosted outside of PAS.

In this case, when the Gorouter receives the request, it checks for an existing route and then sends the request directly to the route service. This enables external clients to intercept route service traffic. 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 Gorouter receives a request for the original app bound to the external route service, it finds the domain internally and sends 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. However, you would be at risk if externally hosted route services are later configured.

The diagram below 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, Gorouter, Route Service (example.com), Fake Route Service (example.com), and PAS. The Gorouter 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 Gorouter to indicate the flow of traffic. Two arrows then point from the Gorouter: one to the fake route service and another to 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 Gorouter handles app requests when:

  • The Bypass security checks for route service lookup checkbox in PAS is disabled.
  • The app is bound to a route service that is hosted outside of PAS.

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

The diagram below 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 Gorouter to the route service.