The Secrets Manager Service Broker makes it easy to secure credentials used by applications in Cloud Foundry (CF) with CyberArk Secrets Manager. Using the Secrets Manager Service Broker, applications are given a Secrets Manager identity automatically when deployed, allowing them to securely retrieve secrets stored in Secrets Manager.
This service broker supports both CyberArk Secrets Manager, Self-Hosted and Secrets Manager Open Source. You need a Secrets Manager, Self-Hosted or Conjur OSS installation accessible by Cloud Foundry in order to use the Secrets Manager Service Broker.
The Secrets Manager Service Broker is an implementation of the Open Service Broker API (version 2.13).
Secrets Manager Service Broker is part of the CyberArk Secrets Manager Open Source Suite of tools.
This repo is a Trusted level project. It is supported by CyberArk and has been verified to work with Secrets Manager, Self-Hosted. For more detailed information on our certification levels, see our community guidelines.
These instructions guide you through installing the Secrets Manager Service Broker and the Secrets Manager Buildpack. The Secrets Manager 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 Secrets Manager Buildpack is a convenient way to securely deliver the secrets that your application needs.
The Secrets Manager Buildpack and Secrets Manager 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
Secrets Manager service listing when they run cf marketplace. For more information on how
to use the Secrets Manager 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-routeNOTE: 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 Secrets Manager 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 Secrets Manager instance, the Service Broker app requires the following environment variables:
-
CONJUR_ACCOUNT: the account name for the Secrets Manager instance you are connecting to. -
CONJUR_APPLIANCE_URL: the URL of the Secrets Manager appliance instance you are connecting to. When using an HA Secrets Manager 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 Secrets Manager. -
CONJUR_POLICY: the Policy branch where new Host identities should be added. The Secrets Manager identity specified inCONJUR_AUTHN_LOGINmust havecreateandupdatepermissions on this policy branch.NOTE: The
CONJUR_POLICYis optional, but is strongly recommended. If this value is not specified, the Service Broker uses therootSecrets Manager 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
productionanddevelopmentfoundation, then your policy branches for each Secrets Manager Service Broker might becf/prodandcf/dev. -
CONJUR_AUTHN_LOGIN: the identity of a Secrets Manager Host (of the formhost/host-id) withcreateandupdateprivileges onCONJUR_POLICY. This account is used to add and remove Hosts from Secrets Manager policy as apps are deployed to or removed from the platform.If you are using Secrets Manager, Self-Hosted, 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
platformtocloudfoundryor topivotalcloudfoundry, for example. This annotation is used to set annotations on Hosts added by the Service Broker, so that they show in the Secrets Manager UI with the appropriate platform logo.NOTE: The
CONJUR_AUTHN_LOGINvalue for the Host created in policy above ishost/cf-service-broker. -
CONJUR_AUTHN_API_KEY: the API Key of the Secrets Manager Host whose identity you have provided inCONJUR_AUTHN_LOGIN. -
CONJUR_SSL_CERTIFICATE: the PEM-encoded x509 CA certificate chain for Secrets Manager. This is required if your Secrets Manager installation uses SSL (e.g. Secrets Manager, Self-Hosted).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_CERTIFICATEwill be used. -
ENABLE_SPACE_IDENTITY: When set totrue, the service broker provides applications with a Space-levelhostidentity, rather than create a newhostidentity for each application in Secrets Manager at bind time. This allows the broker to use a Secrets Manager follower for application binding, rather than the Secrets Manager 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 Secrets Manager 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 Secrets Manager Service Broker is now installed and ready to use!
The Secrets Manager 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 Secrets Manager Buildpack, please see the Secrets Manager Buildpack documentation.
- Creating a Service Instance
- Connecting an Application to Secrets Manager
- Rotating App Host Credentials
-
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 Secrets Manager Service Broker, you can create a Secrets Manager service instance under the
communityplan 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 Secrets Manager service instance must be created in each space where apps retrieve secrets from Secrets Manager.
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 Secrets Manager.
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 Secrets Manager service, it receives an identity in Secrets Manager and credentials to authenticate to Secrets Manager.
The service broker may be configured to either create a single Secrets Manager identity shared by all applications in a space, or to create a Secrets Manager identity for each application separately.
In TAS or PCF version 2.0+, when the service broker creates the identity for your application in Secrets Manager, it automatically adds it to a Secrets Manager Group representing the
OrganizationandSpacewhere 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_IDENTITYset totrue. This means that when a service instance is created in a space, the service broker creates a Secrets Manager 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 Secrets Manager follower and not the Secrets Manager 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 Secrets Manager host identity for each application bound to the service. This requires that the service broker is able to communicate with the Secrets Manager master for each bind request.
The advantage to this is finer-grained access control and audit logs in Secrets Manager.
Application host identities may be permitted to access secrets at the org and space level or at the application level.
-
To leverage the Secrets Manager Buildpack so that secret values are automatically injected into your application's environment at runtime, your application needs a
secrets.ymlfile is. Thesecrets.ymlfile gives a mapping of environment variable name to a location where a secret is stored in Secrets Manager. For more information about creating this file, see the Summon documentation. -
Binding your application to the
secrets managerservice instance provides the application with an identity in Secrets Manager, and credentials that it may use to retrieve secrets.-
To bind your application to the
secrets managerservice using the CLI, run the command:cf bind-service my-app conjur
-
Alternatively you can specify the secrets manager 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 Secrets Manager 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 Secrets Manager 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-startflag:cf push my-app --no-start
The host identity of the application is stored in the
authn_loginfield in thecyberark-conjurcredentials 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 Secrets Manager, start or restage the app so that the Secrets Manager 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 Secrets Manager service:
cf unbind-service <app-name> conjur
cf bind-service <app-name> conjurNOTE: 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 Secrets Manager 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 Secrets Manager:
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 Secrets Manager
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 Secrets Manager Service Broker is most frequently used with the Secrets Manager Buildpack, but you can also use the identity and authentication credentials provided by the service broker to authenticate with Secrets Manager using different tools. In this example we retrieve a secret value using the Secrets Manager 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-javadoes not manage certificate trust. It is up to you to import the Secrets Manager CA certificate viakeytoolor otherwise.
NOTE:
ResourceClientshould be used as the API client instead ofConjur(as in the example above). This differs slightly from what's documented in thecyberark/conjur-api-javarepository. The recommendation given here is different from the Java client library documentation because the Secrets Manager configuration is not stored in the standardCONJUR_Xenvironment 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.