How do I use IG 7.x as a route service for Cloud Foundry?

Overview

IG can be deployed and configured as a route service for CF by following the procedure outlined in this article:

• Prepare IG to be used as a route for CF
• Create and use the IG Route Service

This integration will not be tested with future IG releases.

Preparing IG to be used as a route service for CF

Consider the following points when preparing your installation:

• Install IG in a separate environment from CF, on an IP address that CF can access. For example, set up an instance of IG in Amazon Web Services™, Google® Cloud Platform, or Microsoft® Azure®.
• Configure IG for HTTPS. See Configure IG For HTTPS (Client-Side) for further information.
• Use the config.json file described below as a template in your IG configuration. This base configuration file manages how requests are redirected from the IG Route Service back to the CF load balancer.

Adding the base configuration of IG

Add the following route to the IG configuration in config.json (located in the $HOME/.openig/config directory):

{  "heap": [     {       "name": "ClientHandler",       "type": "ClientHandler",       "config": {         "hostnameVerifier": "ALLOW_ALL",         "trustManager": {           "type": "TrustAllManager"         }       }     },     {       "name": "_router",       "type": "Router",       "config": {         "defaultHandler": {           "type": "StaticResponseHandler",           "config": {             "status": 404,             "reason": "Not Found",             "headers": {               "Content-Type": [                 "application/json"               ]             },             "entity": "{ \"error\": \"Something went wrong, contact the sys admin\"}"           }         }       }     },     {       "type": "Chain",       "name": "CloudFoundryProxy",       "config": {         "filters": [           {             "type": "ScriptableFilter",             "name": "CloudFoundryRequestRebaser",             "comment": "Rebase the request based on the CloudFoundry provided headers",             "config": {               "type": "application/x-groovy",               "source": [                 "Request newRequest = new Request(request);",                 "org.forgerock.util.Utils.closeSilently(request);",                 "newRequest.uri = URI.create(request.headers['X-CF-Forwarded-Url'].firstValue);",                 "newRequest.headers['Host'] = newRequest.uri.host;",                 "logger.info('Receive request : ' + request.uri + ' forwarding to ' + newRequest.uri);",                 "Context newRoutingContext = org.forgerock.http.routing.UriRouterContext.uriRouterContext(context).originalUri(newRequest.uri.asURI()).build();",                 "return next.handle(newRoutingContext, newRequest);"               ]             }           }         ],         "handler": "_router"       },       "capture": [         "request",         "response"       ]     }   ],   "handler": {     "type": "DispatchHandler",     "name": "Dispatcher",     "config": {       "bindings": [         {           "condition": "${not empty request.headers['X-CF-Forwarded-Url']}",           "handler": "CloudFoundryProxy"         },         {           "handler": {             "type": "StaticResponseHandler",             "config": {               "status": 400,               "entity": "Bad request : expecting a header X-CF-Forwarded-Url"             }           }         }       ]     }   } }

Notice the following features of the route:

• For testing purposes, the ClientHandler is configured to accept all SSL certificates and not to verify host names. This configuration is not recommended for a production environment.
• If a request contains a X-CF-Forwarded-Url header, the DispatchHandler dispatches the request to the chain called CloudFoundryProxy.
• The ScriptableFilter in CloudFoundryProxy returns the request to the original URI for processing.

Adding routes to protect a CF application

Configure the IG Route Service to protect applications by adding additional routes to the IG configuration, as described in the Gateway guide.

Add the routes to the IG configuration in the $HOME/.openig/routes directory. Consider adding routes for the following typical use cases:

• To require users to authenticate before requests are passed to the CF application, set up IG as an OpenID Connect relying party, as described in Act As an OpenID Connect Relying Party.

To require login with Google credentials, see Use Multiple OpenID Connect Providers.

• To throttle the number of requests that can access a CF application at a given time, set up an IG throttling filter, as described in Throttle the Rate of Requests to Protected Applications.

Creating and using the IG Route Service

The following procedure describes how to bind a CF application to the IG Route Service. Requests to the application are routed through IG.

Binding a CF application to the IG Route Service

1. Manually create a CF route service targeting the IG installation using the following command:$ cf create-user-provided-service myIGRouteService -r <URL TO IG>

Note that the CF application is not yet bound to the service instance:$ cf routes space host domain apps service service-broker [myCFAppHostName] [myCFAppDomain] [myCFAppName]

2. Bind the CF application to the service instance using the following command:$ cf bind-route-service [myCFAppDomain] [myIGRouteService] --hostname [myCFAppHostName]

For example:$ cf bind-route-service cfapps-0123.pivotal.io myIGRouteService --hostname spring-music-miototic-meiosis

Where:

cfapps-0123.pivotal.io is the domain of the CF application

myIGRouteService is the name of the service instance

spring-music-miototic-meiosis is the hostname of the CF application

3. Use the following command to check that the CF application is bound to the service instance:$ cf routes space host domain apps service forgerock [myCFAppHostName] [myCFAppDomain] [myCFAppName] [myIGRouteService]

To unbind routes and delete services, use the cf unbind-route-service and cf delete-service commands.

Testing the setup

When a CF application is bound to an instance of the IG Route Service, requests to the application are routed through IG before they are passed along to the application.

Depending on the routes you configured when adding routes to protect the CF application, the IG Route Service filters and perhaps transforms requests before they are passed to the application, and filters and perhaps transforms responses from the application.

A typical use case might be to configure the IG Route Service to require authentication or authorization before the request is passed to the application. Another might be to throttle the number of requests that are allowed to access it at a given time. Any of the features available in IG and described in the Gateway guide can be configured in the route service and made available to CF applications.

See Also

Configure Routers and Routes

Cloud Foundry Documentation