how tos

Protecting Applications in the Pivotal Cloud Foundry Ecosystem


Instructions for protecting applications in the Pivotal Cloud Foundry Ecosystem. 


Pivotal Cloud Foundry (PCF) deployments are maturing across the corporate landscape. PCF’s identity and access management (IAM) tool, user accounts and authentication (UAA), provide basic user management functions and OAuth 2.0/OIDC 1.0 support. UAA has come a long way since its inception, and provides a solid foundation of IAM services for an isolated application ecosystem running on the Pivotal platform. As organizations experience increasing demands on their applications, they begin to realize that they need a full IAM platform that provides identity services beyond what UAA can offer. Integrating applications running on the Pivotal platform with applications running outside the platform, providing strong and adaptive authentication journeys, managing identities across applications, enforcing security policies and more requires a full-service IAM platform like ForgeRock’s Identity Platform™.

ForgeRock provides a Pivotal service broker implementation, the ForgeRock Service Broker. It runs as a small service inside Pivotal and brokers two services into the PCF platform: an OAuth 2.0 AM Service and an IG Route Service. While the OAuth 2.0 AM Service provides similar capabilities to UAA on the OAuth/OIDC side, the IG Route Service is based on ForgeRock Identity Gateway (IG) and can broker the full spectrum of services of the ForgeRock Identity Platform. PCF applications bound to the IG Route Service can seamlessly consume any of the countless services the ForgeRock Identity Platform provides: Intelligent authenticationauthorizationfederationuser-managed accessidentity synchronizationuser self-serviceworkflowsocial identitydirectory servicesAPI gateway services and more.

This article provides an easy-to-follow path to: 

  • Set up a PCF development environment (PCF Dev)
  • Install and configure IG in that environment
  • Install and configure the ForgeRock Service Broker in that environment
  • Deploy, integrate and protect a number of PCF sample applications using the IG Route Service and IG 

Additionally, the guide provides steps how to run IG on PCF. If you have access to a full PCF instance, you can skip the PCF Dev part and dive right into the Service Broker deployment and configuration. You also need access to a ForgeRock Access Management instance 5.0 or newer.

Prepare a PCF Dev environment

As mentioned, if you have access to a full PCF instance, you can skip this part and go straight  to the Service Broker deployment and configuration.

Install CF CLI

Before you install the server side of the PCF Dev environment, you must first install the Cloud Foundry Command Line Interface (cf CLI) utility, which is mainly how you will interact with PCF throughout this process.

Follow the Pivotal documentation to install the flavor of the CLI you need for your workstation OS:

Install PCF Dev

Now that you are ready to roll with the cf CLI, it's time to download and install the PCF Dev components. This article is based on PCF Dev v0.30.0 for PCF 1.11.0. This version is based on a VirtualBox, and has a number of default services installed, some of which you will need later on.

PCF Dev – PAS is an alpha release of the NextGen PCF Dev using the native OS hypervisor. It doubles the minimum memory requirements from 4G to 8G, has only a few PCF services installed by default, and takes up to one hour to start. It does however include a full BOSH Director, which is the UI to manage “Tiles” in PCF rather than using the CLI. As soon as this version is a bit more stable and bundles more services like the old one did, it might be worth upgrading. But for now, make sure you select and download v0.30.0:

In order to use your own IP address and DNS name (-i and -d parameters of the cf dev start command) you need to set up a wildcard DNS record. I set up * pointing to my workstation’s IP address where I am running PCF Dev. Follow the command log below to install and start PCF Dev.

unzip dev start -i -d -m 6144Warning: the chosen PCF Dev VM IP address may be in use by another VM or device.Using existing image.Allocating 6144 MB out of 16384 MB total system memory (6591 MB free).Importing VM...Starting VM...Provisioning VM...Waiting for services to start...7 out of 58 running7 out of 58 running7 out of 58 running7 out of 58 running40 out of 58 running56 out of 58 running58 out of 58 running _______  _______  _______    ______   _______  __   __|       ||       ||       |  |      | |       ||  | |  ||    _  ||       ||    ___|  |  _    ||    ___||  |_|  ||   |_| ||       ||   |___   | | |   ||   |___ |       ||    ___||      _||    ___|  | |_|   ||    ___||       ||   |    |     |_ |   |      |       ||   |___  |     ||___|    |_______||___|      |______| |_______|  |___|is now running.To begin using PCF Dev, please run:   cf login -a --skip-ssl-validationApps Manager URL: https://apps.pcfdev.mytestrun.comAdmin user => Email: admin / Password: adminRegular user => Email: user / Password: pass

Log in to PCF Dev

Log in to your fresh PCF Dev instance and select the org you want to work with. Use the pcfdev-org:

Authenticate using admin/admin if using PCF Dev, or a Pivotal admin user if using a real PCF instance.

Install Sample Applications

To test the Service Broker and inter-application SSO, install 2 sample applications:

Spring Music

Modify manifest to reduce memory and avoid random route names:


Enter or copy and paste the following content:


Push the app:


Note the routes:

That’s the URL where your application can be reached. You should be able to resolve the dynamically generated DNS name. You should also be able to hit the URL in a web browser.

Retrieve application logs:


Live-tail application logs:


Cloud Foundry Sample NodeJS App


Modify manifest to reduce memory and avoid random route names:


Note the routes:

That’s the URL where your application can be reached. You should be able to resolve the dynamically generated DNS name. You should also be able to hit the URL in a web browser.

Retrieve application logs:


Live-tail application logs:


Create Your Own JSP Headers App

Create your very own useful sample application to display headers. This will come in handy for future experiments with the IG Route Service.


2.4. More Sample Apps


3. Running IG in Pivotal Cloud Foundry

You can run IG absolutely anywhere you want, but since you are going to use it inside PCF, running it in PCF may be a logic choice. 

3.1. Install, Deploy, and Configure  IG in PCF

The steps below describe an opinionated deployment model for IG in PCF. Your specific environment may require you to make different choices to achieve an ideal configuration and behavior.

3.1.1. Download IG

Download IG 6 from to a preferred working location. Log in using your backstage credentials.


3.1.2. Enable Development Mode


3.1.3. Create And Use Persistent Volume For Configuration Data

IG is configured using JSON files. This section is an easy way to create a shares storage volume that can persist your IG configuration between restarts. If you run IG using its default configuration, it will lose all its configuration every time it restarts because the app is reset. Externalizing the config allows the configuration to reside outside the app and persist between restarts. In a real PCF environment (vs a PCF DEV environment) you would probably use a different shared storage like an NSF service or the like. But for development purposes, a local-volume will work great.



3.1.4. Start IG applying all the configuration changes we have made


3.1.5. Logs


3.1.6. Apply Required Configuration SSH into your IG instance Apply configuration

Create /var/openig/config/config.json and populate with default configuration as documented here:




3.1.7. Access IG Studio


4. Install ForgeRock Service Broker

Download and install the service broker following the instructions in the doc: 

4.1. Deploy and Configure the Service Broker App


Note that OPENIG_BASE_URI is specified as https, not http! If specified as http, the following error occurred when binding the ig route service to an application:


To see the service broker app’s environment:


To see the service broker app’s details:


Create service broker:


Enable the service you plan on using. The ForgeRock Service Broker supports OAuth and IG. You can enable either or both.


Create the service instance(s) you will be using for your apps. You should only need one instance per service to handle any number of applications:


4.2. Bind IG Route Service to the Sample Apps

Note how no apps are bound to the IG Route Service (igrs):


Bind the Route Service to the apps:


Now the two sample apps are bound to our IG Route Service:


5. Define IG Routes for the Sample Apps

By default, no routes are defined in IG for our sample apps and the default behavior in IG (defined in the config.json you created earlier) is to deny access to everything. So, the next and very important step is now to define routes that re-enable access to our sample applications. Once the basic routes are defined, we can add authentication and authorization per application as we see fit:

Point your browser to IG Studio:

Select Protect an Application from the Studio home screen, then select Structured.

Select Advanced options and enter the app URL from the step where you pushed the app to PCF:

  • Since PCF does hostname-based routing (as opposed to path-based) you have to change the Condition that selects your route accordingly. In the Condition field, select Expression and enter: 
    • ${matches(, ‘^app-url’)}
      for example:
      ${matches(, ‘^’)}
    • Enter a descriptive name and a unique ID for the application in their respective text areas.
    • Select Create route:

  • Deploy your route.
  • You have now created a route with default configuration, which proxies requests through IG to the app. That means your app is available again, just as it was before you implemented IG and the Service Broker. The next step is to add value to your route like authentication or authorization.

5.1. Prepare for Authentication and Authorization

To prepare for authentication and authorization, create an AM Service for your route, which is a piece of configuration pointing to your ForgeRock Access Management instance.

Select AM service from the left side menu and provide the details of your AM instance:

You don't need to poplulate the agent section for the use cases here.

5.2. Broker Authentication to an Application

To add authentication to your route:

From the left menu, select Authentication from the menu on the left side menu. Activate the Enable authentication on/off switch, then select Single Sign-On as your authentication option. A configuration dialog box displays.

  • In the configuration dialog box, select your AM service, then select Save:

  • Deploy your route.
  • In a browser, point your browser to your app URL, for example:
  • Notice how you will be redirected to your Access Management login page for authentication. Provide valid login credentials and your sample app should load.
  • Repeat with the other apps. Note how you can now use SSO between all the apps!
  • Next, let's add authorization to one of the routes and only allow members of a certain group access to that application. For that, we need some additional prep work in AM:
    • Create a J2EE agent IG can use to evaluate AM policies:
    • Create a new policy set with the name PCF or a name and ID of your choice:

      Add URL as the resource type. 
    • Create a policy and name it after the application you are protecting. Specify your app URL as the resource, allow GET as an action, and specify the subject condition to require a group membership.
    • In this example, we want membership in the Engineering group to be required for access to the “headers” application:
      • Your policy summary page should look something like this:
  • Return to IG Studio and select the route of the app you created your policy for. In our case, it's the headers app.
  • From the left side menu, select Authorization and activate the Enable authorization on/off switch. Select AM Policy Enforcement as the method to authorize users.
  • Select your AM service, specify your realm, and provide the name of the J2EE agent you created in an earlier step and the password. In the policy endpoint section, specify the name of your policy set and the expression to retrieve your SSO token. The default should work: ${contexts.ssoToken.value}

  • Save and deploy your route.
  • Point your browser to the protected app and log in with a user who is a member of the group you configured to control access. Notice how the app loads after logging in.
  • Remove the user from the group and refresh the app. Notice how the page is blank because the user is no longer authorized.


With this setup, applications can now be integrated, protected, SSO-enabled, and identity-infused within minutes. As a result, you can provide profile self-service, password reset, strong and step-up authentication, continuous authentication, authorization, and risk evaluation to any application in the Pivotal Cloud Foundry ecosystem.