The cf auth method provides an automated mechanism to retrieve a Vault token
for CF instances. It leverages CF's App and Container Identity Assurance.
At a high level, this works as follows:
You construct a request to Vault including your CF_INSTANCE_CERT, signed by your CF_INSTANCE_KEY.
Vault validates that the signature is no more than 300 seconds old, or 60 seconds in the future.
Vault validates that the cert was issued by the CA certificate you've pre-configured.
Vault validates that the request was signed by the private key for the CF_INSTANCE_CERT.
Vault validates that the CF_INSTANCE_CERT application ID, space ID, and org ID presently exist.
If all checks pass, Vault issues an appropriately-scoped token.
This authentication engine uses CF's instance identity service to authenticate users to Vault. Because
CF makes its CA certificate and private key available to certain users at any time, it's possible for
someone with access to them to self-issue identity certificates that meet the criteria for a Vault role,
allowing them to gain unintended access to Vault.
For this reason, we recommend that if you enable this auth method, you carefully guard access to the
private key for your instance identity CA certificate. In CredHub, it can be obtained through the
following call: $ credhub get -n /cf/diego-instance-identity-root-ca.
Take extra steps to limit access to that path in CredHub, whether it be through use of CredHub's ACL
system, or through carefully limiting the users who can access CredHub.
To configure this plugin, you'll need to gather the CA certificate that CF uses to issue each CF_INSTANCE_CERT,
and you'll need to configure it to access the CF API.
To gain your instance identity CA certificate, in the cf dev
environment it can be found using:
$bosh int --path /diego_instance_identity_ca ~/.cfdev/state/bosh/creds.yml
$bosh int --path /diego_instance_identity_ca ~/.cfdev/state/bosh/creds.yml
In environments containing Ops Manager, it can be found in CredHub. To gain access to CredHub, first install
the PCF command-line utility and authenticate to it
using the metadata file it describes. These instructions also use jq for
ease of drilling into the particular part of the response you'll need.
Once those steps are complete, get the credentials you'll use for CredHub:
And view the root certificate CF uses to issue instance identity certificates:
$credhub get -n /cf/diego-instance-identity-root-ca
$credhub get -n /cf/diego-instance-identity-root-ca
The output to that call will include two certificates and one RSA key. You will need to copy the certificate
under ca: | and place it into a file on your local machine that's properly formatted. Here's an example of
a properly formatted CA certificate:
You will also need to configure access to the CF API. To prepare for this, we will now
use the cf command-line tool.
First, while in the directory containing the metadata file you used earlier to authenticate
to CF, run $ pcf target. This points the cf tool at the same place as the pcf tool. Next,
run $ cf api to view the API endpoint that Vault will use.
Next, configure a user for Vault to use. This plugin was tested with Org Manager level
permissions, but lower level permissions may be usable.
Part of the response will contain a certificate, which you'll need to copy and paste to
a well-formatted local file. Please see ca.crt above for an example of how the certificate
should look, and how to verify it can be parsed using openssl. The walkthrough below presumes
you name this file cfapi.crt.
In testing we found that CF instance identity CA certificates were set to expire in 3 years. Some
CF docs indicate they expire every 4 years. However long they last, at some point you may need
to add another CA certificate - one that's soon to expire, and one that is currently or soon-to-be
valid.
If you receive an error containing x509: certificate signed by unknown authority, set
cf_api_trusted_certificates as described above.
If you're unable to authenticate using the CF_INSTANCE_CERT, first obtain a current copy
of your CF_INSTANCE_CERT and copy it to your local environment. Then divide it into two
files, each being a distinct certificate. The first certificate tends to be the actual
identity.crt, and the second one tends to be the intermediate.crt. Verify each are
properly named and formatted using a command like:
$openssl x509 -in ca.crt -text -noout
$openssl x509 -in ca.crt -text -noout
Then, verify that the certificates are properly chained to the ca.crt you've configured:
This should show a success response. If it doesn't, try to identify the root cause, be it
an expired certificate, an incorrect ca.crt, or a Vault configuration that doesn't
match the certificates you're checking.
