The objective of this document is to provide a thorough understanding of how Vault interacts with CF using the CF Authentication Method. It will also provide various methods for utilizing the CF auth method in the CF platform.
It is assumed that there is a Cloud Foundry (or Pivotal Platform) instance available and a Vault (Open Source or Enterprise) cluster available. The CF platform must also support Instance Identity Credentials
An App is a Cloud Foundry application that is deployed using a Cloud Foundry manifest file. This manifest file defines things like how much memory the application requires, how many instances the application should use, and any service brokers or user provided services. There are a variety of configuration parameters that can be added to this manifest.
Instance Identity Credentials are provided by the CF platform to container instances running the app. These credentials are used to configure the authentication with Vault. For more information on how CF Instance Identity Credentials work and how they are delivered to app instances, see the Instance Identity Credentialsdocumentation.
User Provided Service Instance are used to deliver information about external services to app instances via environment variables. For more information on how to configure and use User Provided Service Instances, see the User Provided Service Instance documentation. In the context of Apps utilizing the Vault CF auth method, normally the CF manifest will include a User Provided Service Instance configuration for Vault to retrieve the Vault service endpoint.
The Vault cluster is a production level cluster that is reachable from the CF Foundation. This deployment will typically be deployed outside of the CF Foundation and provided as a service via User Provided Service Instance configurations.
The CF authentication method for Vault allows Vault administrators to allow application instances in CF to authenticate to Vault using the built-in instance identity credentials to login to Vault and get a token scoped to the application, space, and/or org policies. The token received can then be used by CF applications to retrieve data from secrets engines allowed using the policies attached to that token.
The Vault policies can be bound to Vault roles scoped to the CF Organization, Space, or Application. This is done using Vault role bindings to the associated Org/Space/App GUID.
To configure Vault to use the CF authentication method the CF auth method must be enabled.
$ vault auth enable cfOnce the auth method is enabled it must be configured with the CF instance identity certificate authority, trusted API certificates, the CF api address and username/password credentials. See the CF authentication documentation to configure the auth method.
Once the authentication method is configured, a role must be assigned to 1 or more of the CF instance identity certificate Organization Unit property values: Organization GUID, Space GUID, and/or App GUID. Typically all three values are used to properly scope access to the secrets for the application.
One thing to note here is that the CF application GUID is not available until the app is pushed; however, in order to bind the specific application role to the application it needs the GUID. So, in order to properly handle this scenario it is recommended that the application be pushed with the --no-start flag first, the application GUID retrieved and used to create the application role, then start the application. This allows the application to authenticate to Vault at application startup time.
If the role bindings only include an Organization GUID and/or Space GUID, this is not required, but use caution if not doing so. If the Vault role is not scoped to a specific application GUID, the associated policies that are mapped to the role will be available to all applications in that Space and/or Organization.
There are a few methods to integrate Vault CF authentication into a CF application, but there is a standard workflow that all apps will have to adhere to.
Using Spring Vault is the preferred method of integrating with the Vault CF auth method as it easily integrated into Spring apps.
Vault agent is a tool that allows apps to authenticate using the CF auth plugin as well as securely manage the reauthentication and manage the authentication token renewal.
Cloud Foundry has a capability to provide sidecar processes to CF apps. With this capability, Vault can be provided as a sidecar process to apps to provide a low touch method of providing secrets to the app. Vault agent can be configured to write the secrets associated with the app policy to a local file. Apps can then consume this file without having to manage the lifecycle of the Vault authentication token. Care must be used when consuming these secrets as they could potentially change based on the type of secret or how the secret is managed in Vault. If this file changes, the app must be aware of that change and do what is necessary to consume these new secrets.