Tutorial - Cloud Foundry Integration
Cloud Foundry (CF) is a popular open source Platform as a Service (PaaS) that can be deployed on your own infrastructure or on any Infrastructure-as-a-Service platform, like Amazon Web Service, Google Cloud Platform, or Azure. Using Cloud Foundry makes it easy to run, scale, and maintain applications - and integrating it with Conjur makes it easy for CF-deployed apps to securely get the secrets and credentials that they need.
There are several certified CF platforms offering proprietary implementations of Cloud Foundry that simplify the process of installing and maintaining the platform. For the purposes of this tutorial, we will focus on using the small footprint version of Pivotal Cloud Foundry (PCF) called PCF Dev.
In Cloud Foundry, applications interact with external services via service brokers that are registered in the marketplace. Deployments of applications in CF are split up into orgs (the top-level organizational structure where apps can be grouped) and spaces (where users’ applications are actually deployed; spaces belong to orgs). When you deploy an application to a space in CF, if you want to use an external service you must first create a service instance in the space you are working in. Then, when you push (or upload) your application to CF, you can bind your application to the service instance. For more information about how services work in Cloud Foundry, please reference the CF documentation.
Conjur leverages this framework to allow CF-deployed applications to securely access secrets stored in Conjur. We offer the Conjur Service Broker, which can be installed in your CF deployment and used to create Conjur service instances that you can bind your application to. When you bind your application to the Conjur service instance, your application will automatically be granted a Host identity in Conjur policy, and you can add entitlements to the application Host in policy to grant it access to secrets stored in Conjur.
We also offer the Conjur Buildpack, which can be used to automatically inject secret values into your application’s environment at runtime using Summon. If your application is set up to retrieve secret values from its environment, then you can update your app to include a secrets.yml file that provides a map from environment variable name to the secret path in Conjur. The Conjur Buildpack will then automatically use the application’s Host identity to securely retrieve the secret values from Conjur and inject them into the application’s environment at runtime. In practice, as an alternative to using the Buildpack we also have client libraries in several languages that may be used to deliver secrets to your application, but for the purposes of this tutorial we will use the Conjur Buildpack.
Now that we have a better understanding of how our Cloud Foundry integration works, let’s jump right into the tutorial and try it out.
Before getting started with the tutorial, you must:
- Install Conjur locally or sign up for a hosted evaluation Conjur account
- Install PCF Dev by following the Pivotal tutorial, which will also take you through installing the CF CLI
The following steps will set up our CF deployment to allow a demo CF-deployed application to interact with Conjur:
A Conjur Admin User will:
- Configure the Conjur instance to have a Host identity for the Service Broker that owns a Policy; the Service Broker will use this Host to manage application hosts on bind / unbind.
A CF Admin User will:
- Deploy the Conjur Service Broker to its own org and space and configure it with the Conjur Service Broker host credentials
- Upload the meta-buildpack and the Conjur Buildpack
- Create a Conjur service listing in the marketplace
- Ensure the CF developer user has access to an org / space to deploy their application
A CF Developer User will:
- Create a Conjur service instance in the org / space where the app will be deployed
- Deploy the demo application and bind it to the Conjur service instance
- Request an update to Conjur Policy to add appropriate entitlements to the app’s Host identity in Conjur, and get those changes approved by a Conjur admin before starting or restaging the application
We will begin by preparing our Conjur instance by loading a policy file that contains the configuration we will need for our CF-deployed apps. The policy file will include:
cfPolicy where all Conjur policies for CF-deployed apps may be loaded. As apps are bound to a service instance of the Conjur Service Broker, they will be granted machine identities and added as Hosts to this Policy.
cf-service-brokerHost that is a member of a
cfPolicy, so it has full privileges on that Policy. The Service Broker will be configured with the credentials of the
cf-service-brokerHost so that it will be able to modify the
cfPolicy to manage the application Hosts.
Save the following file as
Load the policy as an admin Conjur user using the following command:
Note: For more information about using the Conjur CLI to load policies, work through our getting started tutorial.
We can see from this response that a
cf-service-broker Host has been created with API
2k60y0338tad17178xb9726pjf00jb7dzk2dgkxs43nsmb7e3txmsjc - we will need
this key when configuring our Service Broker.
In addition, the demo application that we will use has the following Conjur policy:
The app requires access to three secrets, and we declare a
that can access the secret values, and a
secrets-managers group that can update
the secret values.
Once our application has a Host identity in Conjur, we will add the Host to the
secrets-users group so that it will be privileged to access the secret values.
If this policy is stored in a file
app.yml, it can be loaded into the
Policy by calling
The secret values can be populated by calling
Configure Conjur Service in Cloud Foundry
Next, we will need to start PCF Dev and log in via the
Note: If you already have PCF Dev running and want to start with a clean
installation, you can run
cf dev destroy before calling the commands below.
Step 1: Deploy the Conjur Service Broker to its own org and space
While logged in to PCF Dev as the
admin user, run the following commands to
deply the Conjur Service Broker:
Note that in order to be configured properly, the Conjur Service Broker requires several environment variables. These are:
SECURITY_USER_PASSWORD: the Basic Auth credentials for the Service Broker
CONJUR_AUTHN_API_KEY: the credentials needed to access the Conjur instance
CONJUR_VERSION: the major version of the instance of Conjur that you are running, which is 5 for this tutorial
CONJUR_POLICY: the Conjur Policy where Hosts will be added
CONJUR_SSL_CERTIFICATE: not needed for this demo, but can be used if your Conjur instance is secured with TLS. This environment variable should be a copy / paste of the contents of the PEM certificate file that was created on calling
Step 2: Upload the meta-buildpack and the Conjur Buildpack
By default, if your application has a
secrets.yml file the Conjur Service will
use the Conjur Buildpack to automatically inject secret’s into your application’s
environment at runtime. The Conjur Buildpack is a decorator buildpack which relies
on the meta-buildpack
to be properly invoked.
To upload the buildpacks:
Step 3: Create a Conjur service listing in the marketplace
To make the Conjur service listing available in all orgs and spaces, run
Then you will be able to see the
cyberark-conjur service listed from any org /
space, so that developers will be able to create Conjur service instances:
Step 4: Create an org / space for the CF developer user
Uploading the Demo Application to Cloud Foundry
The demo application that we are using is simple - it just echoes three environment variables to the browser window. It will allow us to demonstrate that the Conjur service successfully loads the secret values from Conjur into the application environment.
Step 1: Create a Conjur service instance in the org / space for the demo app
To deploy the application, we will act as a developer and log in to CF using the
non-admin credentials (
pass for PCF Dev)
Step 2: Deploy the demo application and bind it to the Conjur service instance
The demo application we will use is part of our demo repository, which includes demos for testing our Cloud Foundry integration locally using PCF Dev or against an existing PCF installation.
The app includes a Cloud Foundry deployment manifest that binds it to the Conjur service:
As soon as we
cf push the app, it will be bound to the Conjur service instance
we created in the last step and it will be granted a host identity in Conjur.
Note: We use
cf push --no-start here to ensure the app will not start until we
have added entitlements for the application Host in Conjur policy so that it will
have access to the secrets that it needs.
Step 3: Update Conjur policy to privilege the app
Now that the demo app has a Host identity in Conjur, we can add it as a member
cf/app/secrets-users group so that it will have access to the secrets in
The host identity is stored in the
authn_login field in the
credentials in the application’s environment, and might look something like
host/cf/0299a19d-7de4-4e98-89f6-372ac7c0521f. We can update privileges for the
app by creating an
entitlements.yml policy file:
and a Conjur user with privileges to update the
cf Policy can load it by calling
Step 4: Start the demo app and watch it retrieve secrets!
Start the demo app by calling
cf start hello-world. The application will start
and will output a URL (like hello-world.local.pcfdev.io). If everything worked
correctly, you will see the variable values we loaded into Conjur earlier in
this exercise echoed to the browser as planned. For fun, you can rotate the
values in Conjur and call
cf restage hello-world to watch the values change.
Developers love Cloud Foundry for the ease of deploying applications, and the Conjur integration enables them to do so securely. Once the Conjur Service Broker and Conjur Buildpack have been installed in Cloud Foundry by an admin user and the Conjur service listing has been made available in the marketplace, it is easy for developers to bind their applications to a Conjur service instance. This gives their application a unique Host identity in Conjur, and that Host identity can be granted access to the secrets that the application needs. At runtime the Conjur Buildpack will install Summon so that the secret values will automatically be loaded into the running application’s environment. With Cloud Foundry and Conjur together, developers can focus on releasing features, and security and operations teams will know that credentials are secure.