The Conjur Service Broker makes it easy to secure credentials used by applications in Cloud Foundry (CF) with CyberArk Conjur. Using the Conjur Service Broker, applications are given a Conjur identity automatically when deployed, allowing them to securely retrieve secrets stored in Conjur.
You need a Conjur installation accessible by Cloud Foundry in order to use the Conjur Service Broker; for more information about installing Conjur, please visit conjur.org or check out our GitHub repository.
The Conjur Service Broker is an implementation of the Open Service Broker API (version 2.13).
Conjur Service Broker is part of the CyberArk Conjur Open Source Suite of tools.
This repo is a Trusted level project. It is supported by CyberArk and has been verified to work with Conjur Enterprise. For more detailed information on our certification levels, see our community guidelines.
These instructions guide you through installing the Conjur Service Broker and the Conjur Buildpack. The Conjur Buildpack is a supply buildpack that provides a lightweight binary based on Summon to Cloud Foundry applications. This allows secrets to be securely injected into your application's environment at startup. Using the Conjur Buildpack is a convenient way to securely deliver the secrets that your application needs.
The Conjur Buildpack and Conjur Service Broker should be installed by an admin
Cloud Foundry user. Follow the instructions below to configure your CF installation
so that CF users in any org / space are able to see the
Conjur service listing when they run cf marketplace
. For more information on how
to use the Conjur Service Broker when deploying applications, see the
usage instructions.
IMPORTANT: Before you begin, ensure you are logged into your CF deployment via the CF CLI as an admin.
-
cf target -o cyberark-conjur -s conjur-service-broker
-
unzip conjur-service-broker-go.zip # Push the Service Broker app cf push --no-start --random-route
NOTE: For Service Broker versions pre-1.1.0, the release will not include a ZIP file. Instead of downloading the release ZIP you can clone the repository itself.
-
The Conjur Service Broker uses HTTP basic authentication, and the credentials it uses must be stored as environment variables in the Service Broker app:
NOTE: The username and password may be any values you choose. These are used by the Service Broker to verify that requests are coming from the Cloud Foundry foundation.
cf set-env conjur-service-broker SECURITY_USER_NAME [value] cf set-env conjur-service-broker SECURITY_USER_PASSWORD [value]
To configure the Service Broker to communicate with your external Conjur instance, the Service Broker app requires the following environment variables:
-
CONJUR_ACCOUNT
: the account name for the Conjur instance you are connecting to. -
CONJUR_APPLIANCE_URL
: the URL of the Conjur appliance instance you are connecting to. When using an HA Conjur master cluster, this should be the URL of the master load balancer. -
CONJUR_FOLLOWER_URL
(HA only): If using high availability, this should be the URL of a load balancer for the cluster's Follower instances. This is the URL that applications use to communicate with Conjur. -
CONJUR_POLICY
: the Policy branch where new Host identities should be added. The Conjur identity specified inCONJUR_AUTHN_LOGIN
must havecreate
andupdate
permissions on this policy branch.NOTE: The
CONJUR_POLICY
is optional, but is strongly recommended. If this value is not specified, the Service Broker uses theroot
Conjur policy.NOTE: If you use multiple CloudFoundry foundations, this policy branch should include an identifier for the foundation to distinguish applications deployed in each foundation. For example, if you have both a
production
anddevelopment
foundation, then your policy branches for each Conjur Service Broker might becf/prod
andcf/dev
. -
CONJUR_AUTHN_LOGIN
: the identity of a Conjur Host (of the formhost/host-id
) withcreate
andupdate
privileges onCONJUR_POLICY
. This account is used to add and remove Hosts from Conjur policy as apps are deployed to or removed from the platform.If you are using Enterprise Conjur, you should add an annotation on the Service Broker Host in policy to indicate which platform the Service Broker is used on. The policy you load should similar to:
- !host id: cf-service-broker annotations: platform: cloudfoundry
You may elect to set
platform
tocloudfoundry
or topivotalcloudfoundry
, for example. This annotation is used to set annotations on Hosts added by the Service Broker, so that they show in the Conjur UI with the appropriate platform logo.NOTE: The
CONJUR_AUTHN_LOGIN
value for the Host created in policy above ishost/cf-service-broker
. -
CONJUR_AUTHN_API_KEY
: the API Key of the Conjur Host whose identity you have provided inCONJUR_AUTHN_LOGIN
. -
CONJUR_SSL_CERTIFICATE
: the PEM-encoded x509 CA certificate chain for Conjur. This is required if your Conjur installation uses SSL (e.g. Conjur Enterprise).This value may be obtained by running the command:
$ openssl s_client -showcerts -servername [CONJUR_DNS_NAME] \ -connect [CONJUR_DNS_NAME]:443 < /dev/null 2> /dev/null \ | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----
-
CONJUR_FOLLOWER_SSL_CERTIFICATE
(HA only): If using high availability, this should be the SSL certificate chain of a load balancer for the cluster's Follower instances. It can be retrieved the same way as theCONJUR_SSL_CERTIFICATE
. If not provided the value ofCONJUR_SSL_CERTIFICATE
will be used. -
ENABLE_SPACE_IDENTITY
: When set totrue
, the service broker provides applications with a Space-levelhost
identity, rather than create a newhost
identity for each application in Conjur at bind time. This allows the broker to use a Conjur follower for application binding, rather than the Conjur master.
To load these environment variables into the Service Broker's environment, run:
cf set-env conjur-service-broker CONJUR_VERSION [value] cf set-env conjur-service-broker CONJUR_ACCOUNT [value] cf set-env conjur-service-broker CONJUR_APPLIANCE_URL [value] cf set-env conjur-service-broker CONJUR_AUTHN_LOGIN [value] cf set-env conjur-service-broker CONJUR_AUTHN_API_KEY [value] cf set-env conjur-service-broker CONJUR_POLICY [value] cf set-env conjur-service-broker CONJUR_SSL_CERTIFICATE [value] cf set-env conjur-service-broker ENABLE_SPACE_IDENTITY [value]
-
-
cf start conjur-service-broker
NOTE: When the Service Broker application is started, it runs a health check that validates its connection to your Conjur instance.
-
Use the same Basic Auth credentials specified in your environment variables:
APP_URL="http://`cf app conjur-service-broker | grep -E -w 'urls:|routes:' | awk '{print $2}'`" cf create-service-broker conjur-service-broker "[username value]" "[password value]" $APP_URL
-
cf enable-service-access cyberark-conjur
The CyberArk Conjur Service Broker is now installed and ready to use!
The Conjur Buildpack uses a lightweight Go binary based on Summon to load secrets into the environment of CF-deployed applications using the app's secrets.yml
file.
For instructions on installing and using the Conjur Buildpack, please see the Conjur Buildpack documentation.
-
Once the Service Broker is installed, you should see the service listing from any org / space:
$ cf marketplace Getting services from marketplace in org cyberark-conjur-org / space cyberark-conjur-space as admin... OK service plans description cyberark-conjur community An open source security service that provides secrets management, machine-identity based authorization, and more. TIP: Use 'cf marketplace -s SERVICE' to view descriptions of individual plans of a given service.
-
When you are ready to use the Conjur Service Broker, you can create a Conjur service instance under the
community
plan in the org / space where you are deploying your application:cf create-service cyberark-conjur community conjur
NOTE: Service instances cannot be shared between spaces. A Conjur service instance must be created in each space where apps retrieve secrets from Conjur.
For VMWare Tanzu Application Service (TAS) or Pivotal Cloud Foundry (PCF) 2.0+, when the service broker is provisioned in a space, it automatically creates policy branches and groups for the org and space. See below for more information on using these org and space groups to permit access to secrets in Conjur.
The policy the service broker loads to define these groups is similar to:
--- # Policy for the Organization - !policy # Organization GUID from the platform. # This may be obtained by running `cf org --guid {org name} id: cbd7a05a-b304-42a9-8f66-6827ae6f78a1 annotations: pcf/orgName: my-organization # note that this is only added for Service Broker API 2.15 and up pcf/type: org body: # Group to privilege an entire organzation to a resource - !group # Policy for the Space - !policy # Space GUID from the platform. # This may be obtained by running `cf space --guid {space name} id: 8bf39f4a-ebde-437b-9c38-3d234b80631a annotations: #note that this only gets added on service broker api version 2.15 and up, when the attribute is made available to us. pcf/orgName: my-organization # note that this is only added for Service Broker API 2.15 and up pcf/spaceName: my-space pcf/type: space body: # Group to privilege an entire space to a resource # The service broker adds applications to this group automatically. - !group # Grant to add the Space group to the Org Group - !grant role: !group member: !group 8bf39f4a-ebde-437b-9c38-3d234b80631a
When an application is bound to the Conjur service, it receives an identity in Conjur and credentials to authenticate to Conjur.
The service broker may be configured to either create a single Conjur identity shared by all applications in a space, or to create a Conjur identity for each application separately.
In TAS or PCF version 2.0+, when the service broker creates the identity for your application in Conjur, it automatically adds it to a Conjur Group representing the
Organization
andSpace
where the application is deployed. These groups may be used to control secret access at the org or space level, rather than the application host itself.Space-scoped identities are enabled by configuring the service broker with
ENABLE_SPACE_IDENTITY
set totrue
. This means that when a service instance is created in a space, the service broker creates a Conjur Host for that space. When an application is bound to the service, the service broker gives it the credentials of the space identity, rather than create a new host identity for the application.The advantage to this is the bind operation only requires access to a Conjur follower and not the Conjur master. This promotes high-availability and scalability of app binding and secret retrieval.
When using space host identities, only the org and space groups should be used for permitting access to secrets. More information on this is available below.
When space identities are not enabled, the service broker creates a new Conjur host identity for each application bound to the service. This requires that the service broker is able to communicate with the Conjur master for each bind request.
The advantage to this is finer-grained access control and audit logs in Conjur.
Application host identities may be permitted to access secrets at the org and space level or at the application level.
-
To leverage the Conjur Buildpack so that secret values are automatically injected into your application's environment at runtime, your application needs a
secrets.yml
file is. Thesecrets.yml
file gives a mapping of environment variable name to a location where a secret is stored in Conjur. For more information about creating this file, see the Summon documentation. -
Binding your application to the
conjur
service instance provides the application with an identity in Conjur, and credentials that it may use to retrieve secrets.-
To bind your application to the
conjur
service using the CLI, run the command:cf bind-service my-app conjur
-
Alternatively you can specify the conjur service in your application manifest:
--- applications: - name: my-app services: - conjur
-
-
TAS applications can be granted access to secrets using either the Org and Space groups, or with the application host identity.
Applications can be granted access to secrets by privileging the Org or Space groups to read secrets using Conjur policy.
The group Ids use the Org and Space GUID identifiers, which may be obtained using the Cloud Foundry CLI:
$ cf org --guid <org-name> 6b40649e-331b-424d-afa0-6d569f016f51 $ cf space --guid <space-name> 72a928f6-bf7c-4732-a195-896f67bd1133
For example, the policy to privilege a space group to access a secret is:
- !permit resource: my-secret-id role: !group cf/prod/6b40649e-331b-424d-afa0-6d569f016f51/72a928f6-bf7c-4732-a195-896f67bd1133 privileges: [ read, execute ]
NOTE: Application Host identity permissions are not available when using Space Host Identies.
After your application has been pushed to the platform, you can use its host identity in Conjur policy to grant it access to secrets. The application does not have access to secrets and should not be started until this step is completed. To prevent the app from starting when it is first pushed, use the
--no-start
flag:cf push my-app --no-start
The host identity of the application is stored in the
authn_login
field in thecyberark-conjur
credentials in the application's environment, and might look something likehost/cf/prod/0299a19d-7de4-4e98-89f6-372ac7c0521f
.NOTE: In TAS or PCF version 2.0+, the host identity includes the Organization and Space GUIDs in the Host identity, for example:
host/cf/prod/cbd7a05a-b304-42a9-8f66-6827ae6f78a1/8bf39f4a-ebde-437b-9c38-3d234b80631a/c363669e-e43b-40b9-b650-493d3bdb4663
-
NOTE: If you use the Org and Space groups to permit access to secrets, and those permissions are granted before pushing your application, this step is not required. Your application will already have access to the secrets when it is initially pushed.
Now that your application is privileged to access the secrets it needs in Conjur, start or restage the app so that the Conjur Buildpack can inject the secret values into the running application's environment.
cf start my-app # or cf restage my-app
The secrets are now available to be used by the application, but are not visible
when you run cf env my-app
or if you cf ssh my-app
and run printenv
.
When using application host identities (ENABLE_SPACE_IDENTITY=false
), the host API
key may be rotated by simply re-binding the application to the Conjur service:
cf unbind-service <app-name> conjur
cf bind-service <app-name> conjur
NOTE: This will issue a new identity to the application, not just a new API key, so any application specific permissions will need to be granted again. Any permissions granted to the org or space groups will be automatically inherited by the new identity.
Rotating the host API key when Space Host Identities are enabled (ENABLE_SPACE_IDENTITY=true
)
requires coordinating the host credential update with all apps in a space.
-
Rotate the Space Host API key using the Conjur CLI. This will return the new API key for the host:
conjur host rotate_api_key --host <cf policy root>/<org-guid>/<space-guid> # for example $ conjur host rotate_api_key --host cf/prod/6b40649e-331b-424d-afa0-6d569f016f51/72a928f6-bf7c-4732-a195-896f67bd1133 1p9c5443sy1bg93ek2e062wsnmvy3p9k9j83nq841sj1sp2vasze1r
-
Update the Space API key secret in Conjur:
conjur variable values add "<cf policy root>/<org-guid>/<space-guid>/space-host-api-key" "<api-key-value>" # For example: conjur variable values add "cf/prod/6b40649e-331b-424d-afa0-6d569f016f51/72a928f6-bf7c-4732-a195-896f67bd1133/space-host-api-key" "1p9c5443sy1bg93ek2e062wsnmvy3p9k9j83nq841sj1sp2vasze1r"
-
Re-bind each application in the space to Conjur
This will provide the updated credentials to each application
cf unbind-service <app-name> conjur cf bind-service <app-name> conjur
-
Re-stage each application in the space
This causes each app to retrieve its secrets using the rotated credentials
cf restage <app-name>
The Conjur Service Broker is most frequently used with the Conjur Buildpack, but you can also use the identity and authentication credentials provided by the service broker to authenticate with Conjur using different tools. In this example we retrieve a secret value using the Conjur API for Java.
Credentials are provided to the API via JSON stored in the VCAP_SERVICES
environment variable.
package net.conjur.sample;
import java.io.StringReader;
import javax.json.Json;
import javax.json.JsonReader;
import javax.json.JsonObject;
import net.conjur.api.Endpoints;
import net.conjur.api.clients.ResourceClient;
public class App {
public static void main(String[] args) {
String vcapServices = System.getenv("VCAP_SERVICES");
JsonReader jsonReader = Json.createReader(new StringReader(vcapServices));
JsonObject credentials = jsonReader.readObject()
.getJsonArray("cyberark-conjur")
.getJsonObject(0)
.getJsonObject("credentials");
String account = credentials.getString("account");
String apiKey = credentials.getString("authn_api_key");
String applianceUrl = credentials.getString("appliance_url");
String hostId = credentials.getString("authn_login");
String authnUrl = String.format("%s/authn/%s", applianceUrl, account);
String variableUrl = String.format("%s/secrets/%s/variable", applianceUrl, account);
Endpoints conjurEndpoints = new Endpoints(authnUrl, variableUrl);
ResourceClient conjurApi = new ResourceClient(hostId, apiKey, conjurEndpoints);
String mySecretValue = conjurApi.retrieveSecret("dev/test-app/secret-key");
System.out.println(mySecretValue);
}
}
NOTE: The
conjur-api-java
does not manage certificate trust. It is up to you to import the Conjur CA certificate viakeytool
or otherwise.
NOTE:
ResourceClient
should be used as the API client instead ofConjur
(as in the example above). This differs slightly from what's documented in thecyberark/conjur-api-java
repository. The recommendation given here is different from the Java client library documentation because the Conjur configuration is not stored in the standardCONJUR_X
environment variables in this case.
Information for developing and testing the service broker can be found in the Contributing Guide.
This repository is licensed under Apache License 2.0 - see LICENSE
for more details.