From a420b966bb7b63dadb13cbfcc392f0911045eb8a Mon Sep 17 00:00:00 2001 From: Becca Petrin Date: Mon, 17 Jun 2019 15:00:30 -0700 Subject: [PATCH] add docs --- website/source/api/auth/pcf/index.html.md | 1 + .../docs/agent/autoauth/methods/pcf.html.md | 3 + website/source/docs/auth/pcf.html.md | 295 ++++++++++++++++++ 3 files changed, 299 insertions(+) create mode 100644 website/source/api/auth/pcf/index.html.md create mode 100644 website/source/docs/agent/autoauth/methods/pcf.html.md create mode 100644 website/source/docs/auth/pcf.html.md diff --git a/website/source/api/auth/pcf/index.html.md b/website/source/api/auth/pcf/index.html.md new file mode 100644 index 000000000..0ffdd02fc --- /dev/null +++ b/website/source/api/auth/pcf/index.html.md @@ -0,0 +1 @@ +// TODO \ No newline at end of file diff --git a/website/source/docs/agent/autoauth/methods/pcf.html.md b/website/source/docs/agent/autoauth/methods/pcf.html.md new file mode 100644 index 000000000..476581cec --- /dev/null +++ b/website/source/docs/agent/autoauth/methods/pcf.html.md @@ -0,0 +1,3 @@ +package methods + +// TODO diff --git a/website/source/docs/auth/pcf.html.md b/website/source/docs/auth/pcf.html.md new file mode 100644 index 000000000..f65301c5f --- /dev/null +++ b/website/source/docs/auth/pcf.html.md @@ -0,0 +1,295 @@ +--- +layout: "docs" +page_title: "PCF - Auth Methods" +sidebar_title: "PCF" +sidebar_current: "docs-auth-pcf" +description: |- +The pcf auth method allows automated authentication of PCF instances. +--- + +# Pivotal Cloud Foundry (PCF) Auth Method + +The `pcf` auth method provides an automated mechanism to retrieve a Vault token +for PCF instances. It leverages PCF's [App and Container Identity Assurance](https://content.pivotal.io/blog/new-in-pcf-2-1-app-container-identity-assurance-via-automatic-cert-rotation). +At a high level, this works as follows: + +1. You construct a request to Vault including your `CF_INSTANCE_CERT`, signed by your `CF_INSTANCE_KEY`. +2. Vault validates that the signature is no more than 5 minutes old, or 1 minute in the future. +3. Vault validates that the cert was issued by the CA certificate authority you've pre-configured. +4. Vault validates that the request was signed by the private key for the `CF_INSTANCE_CERT`. +5. Vault validates that the `CF_INSTANCE_CERT`'s shown application ID, space ID, and org ID presently exist. +6. If all checks pass, Vault issues a token with that appropriate scopes you have designated. + +## Known Risks + +This authentication engine uses PCF's instance identity service to authenticate users to Vault. Because +PCF 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. + +## Usage + +### Preparing to Configure the Plugin + +To configure this plugin, you'll need to gather the CA certificate that PCF uses to issue each `CF_INSTANCE_CERT`, +and you'll need to configure it to access the PCF API. + +To gain your instance identity CA certificate, in the [cf dev](https://github.com/cloudfoundry-incubator/cfdev) +environment it can be found using: + +``` +$ 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](https://docs.pivotal.io/tiledev/2-2/pcf-command.html) and authenticate to it +using the `metadata` file it describes. These instructions also use [jq](https://stedolan.github.io/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: + +``` +$ pcf settings | jq '.products[0].director_credhub_client_credentials' +``` + +SSH into your Ops Manager VM: + +``` +ssh -i ops_mgr.pem ubuntu@$OPS_MGR_URL +``` + +Please note that the above OPS_MGR_URL shouldn't be prepended with `https://`. + +Log into CredHub with the credentials you obtained earlier: + +``` +$ credhub login --client-name=director_to_credhub --client-secret=some-secret +``` + +And view the root certificate PCF uses to issue instance identity certificates: + +``` +$ 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: + +``` +$ cat ca.crt +-----BEGIN CERTIFICATE----- +MIIDNDCCAhygAwIBAgITPqTy1qvfHNEVuxsl9l1glY85OTANBgkqhkiG9w0BAQsF +ADAqMSgwJgYDVQQDEx9EaWVnbyBJbnN0YW5jZSBJZGVudGl0eSBSb290IENBMB4X +DTE5MDYwNjA5MTIwMVoXDTIyMDYwNTA5MTIwMVowKjEoMCYGA1UEAxMfRGllZ28g +SW5zdGFuY2UgSWRlbnRpdHkgUm9vdCBDQTCCASIwDQYJKoZIhvcNAQEBBQADggEP +ADCCAQoCggEBALa8xGDYT/q3UzEKAsLDajhuHxPpIPFlCXwp6u8U5Qrf427Xof7n +rXRKzRu3g7E20U/OwzgBi3VZs8T29JGNWeA2k0HtX8oQ+Wc8Qngz9M8t1h9SZlx5 +fGfxPt3x7xozaIGJ8p4HKQH1ZlirL7dzun7Y+7m6Ey8cMVsepqUs64r8+KpCbxKJ +rV04qtTNlr0LG3yOxSHlip+DDvUVL3jSFz/JDWxwCymiFBAh0QjG1LKp2FisURoX +GY+HJbf2StpK3i4dYnxQXQlMDpipozK7WFxv3gH4Q6YMZvlmIPidAF8FxfDIsYcq +TgQ5q0pr9mbu8oKbZ74vyZMqiy+r9vLhbu0CAwEAAaNTMFEwHQYDVR0OBBYEFAHf +pwqBhZ8/A6ZAvU+p5JPz/omjMB8GA1UdIwQYMBaAFAHfpwqBhZ8/A6ZAvU+p5JPz +/omjMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBADuDJev+6bOC +v7t9SS4Nd/zeREuF9IKsHDHrYUZBIO1aBQbOO1iDtL4VA3LBEx6fOgN5fbxroUsz +X9/6PtxLe+5U8i5MOztK+OxxPrtDfnblXVb6IW4EKhTnWesS7R2WnOWtzqRQXKFU +voBn3QckLV1o9eqzYIE/aob4z0GaVanA9PSzzbVPsX79RCD1B7NmV0cKEQ7IrCrh +L7ElDV/GlNrtVdHjY0mwz9iu+0YJvxvcHDTERi106b28KXzJz+P5/hyg2wqRXzdI +faXAjW0kuq5nxyJUALwxD/8pz77uNt4w6WfJoSDM6XrAIhh15K3tZg9EzBmAZ/5D +jK0RcmCyaXw= +-----END CERTIFICATE----- +``` + +An easy way to verify that your CA certificate is properly formatted is using OpenSSL like so: + +``` +$ openssl x509 -in ca.crt -text -noout +Certificate: + Data: + Version: 3 (0x2) + Serial Number: + 3e:a4:f2:d6:ab:df:1c:d1:15:bb:1b:25:f6:5d:60:95:8f:39:39 + Signature Algorithm: sha256WithRSAEncryption + Issuer: CN=Diego Instance Identity Root CA + Validity + Not Before: Jun 6 09:12:01 2019 GMT + Not After : Jun 5 09:12:01 2022 GMT + Subject: CN=Diego Instance Identity Root CA + Subject Public Key Info: + Public Key Algorithm: rsaEncryption + Public-Key: (2048 bit) + Modulus: + 00:b6:bc:c4:60:d8:4f:fa:b7:53:31:0a:02:c2:c3: + 6a:38:6e:1f:13:e9:20:f1:65:09:7c:29:ea:ef:14: + e5:0a:df:e3:6e:d7:a1:fe:e7:ad:74:4a:cd:1b:b7: + 83:b1:36:d1:4f:ce:c3:38:01:8b:75:59:b3:c4:f6: + f4:91:8d:59:e0:36:93:41:ed:5f:ca:10:f9:67:3c: + 42:78:33:f4:cf:2d:d6:1f:52:66:5c:79:7c:67:f1: + 3e:dd:f1:ef:1a:33:68:81:89:f2:9e:07:29:01:f5: + 66:58:ab:2f:b7:73:ba:7e:d8:fb:b9:ba:13:2f:1c: + 31:5b:1e:a6:a5:2c:eb:8a:fc:f8:aa:42:6f:12:89: + ad:5d:38:aa:d4:cd:96:bd:0b:1b:7c:8e:c5:21:e5: + 8a:9f:83:0e:f5:15:2f:78:d2:17:3f:c9:0d:6c:70: + 0b:29:a2:14:10:21:d1:08:c6:d4:b2:a9:d8:58:ac: + 51:1a:17:19:8f:87:25:b7:f6:4a:da:4a:de:2e:1d: + 62:7c:50:5d:09:4c:0e:98:a9:a3:32:bb:58:5c:6f: + de:01:f8:43:a6:0c:66:f9:66:20:f8:9d:00:5f:05: + c5:f0:c8:b1:87:2a:4e:04:39:ab:4a:6b:f6:66:ee: + f2:82:9b:67:be:2f:c9:93:2a:8b:2f:ab:f6:f2:e1: + 6e:ed + Exponent: 65537 (0x10001) + X509v3 extensions: + X509v3 Subject Key Identifier: + 01:DF:A7:0A:81:85:9F:3F:03:A6:40:BD:4F:A9:E4:93:F3:FE:89:A3 + X509v3 Authority Key Identifier: + keyid:01:DF:A7:0A:81:85:9F:3F:03:A6:40:BD:4F:A9:E4:93:F3:FE:89:A3 + + X509v3 Basic Constraints: critical + CA:TRUE + Signature Algorithm: sha256WithRSAEncryption + 3b:83:25:eb:fe:e9:b3:82:bf:bb:7d:49:2e:0d:77:fc:de:44: + 4b:85:f4:82:ac:1c:31:eb:61:46:41:20:ed:5a:05:06:ce:3b: + 58:83:b4:be:15:03:72:c1:13:1e:9f:3a:03:79:7d:bc:6b:a1: + 4b:33:5f:df:fa:3e:dc:4b:7b:ee:54:f2:2e:4c:3b:3b:4a:f8: + ec:71:3e:bb:43:7e:76:e5:5d:56:fa:21:6e:04:2a:14:e7:59: + eb:12:ed:1d:96:9c:e5:ad:ce:a4:50:5c:a1:54:be:80:67:dd: + 07:24:2d:5d:68:f5:ea:b3:60:81:3f:6a:86:f8:cf:41:9a:55: + a9:c0:f4:f4:b3:cd:b5:4f:b1:7e:fd:44:20:f5:07:b3:66:57: + 47:0a:11:0e:c8:ac:2a:e1:2f:b1:25:0d:5f:c6:94:da:ed:55: + d1:e3:63:49:b0:cf:d8:ae:fb:46:09:bf:1b:dc:1c:34:c4:46: + 2d:74:e9:bd:bc:29:7c:c9:cf:e3:f9:fe:1c:a0:db:0a:91:5f: + 37:48:7d:a5:c0:8d:6d:24:ba:ae:67:c7:22:54:00:bc:31:0f: + ff:29:cf:be:ee:36:de:30:e9:67:c9:a1:20:cc:e9:7a:c0:22: + 18:75:e4:ad:ed:66:0f:44:cc:19:80:67:fe:43:8c:ad:11:72: + 60:b2:69:7c +``` + +You will also need to configure access to the PCF API. To prepare for this, we will now +use the [cf](https://docs.cloudfoundry.org/cf-cli/install-go-cli.html) command-line tool. + +First, while in the directory containing the `metadata` file you used earlier to authenticate +to PCF, 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. + +``` +$ cf create-user vault pa55w0rd +$ cf orgs +$ cf org-users my-example-org +$ cf set-org-role Alice my-example-org OrgManager +``` + +Next, PCF often uses a self-signed certificate for TLS, which can be rejected at first +with an error like: + +``` +x509: certificate signed by unknown authority +``` + +If you encounter this error, you will need to first gain a copy of the certificate that PCF +is using for the API via: + +``` +$ openssl s_client -showcerts -servername domain.com -connect domain.com:443 +``` + +Here is an example of a real call: + +``` +$ openssl s_client -showcerts -servername api.sys.somewhere.cf-app.com -connect api.sys.somewhere.cf-app.com:443 +``` + +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 `pcfapi.crt`. + +### Walkthrough + +After obtaining the information described above, a Vault operator will configure the PCF auth method +like so: + +``` +$ vault auth enable pcf + +$ vault write auth/pcf/config \ + identity_ca_certificates=@ca.crt \ + pcf_api_addr=https://api.dev.cfdev.sh \ + pcf_username=vault \ + pcf_password=pa55w0rd \ + pcf_api_trusted_certificates=@pcfapi.crt + +$ vault write auth/pcf/roles/my-role \ + bound_application_ids=2d3e834a-3a25-4591-974c-fa5626d5d0a1 \ + bound_space_ids=3d2eba6b-ef19-44d5-91dd-1975b0db5cc9 \ + bound_organization_ids=34a878d0-c2f9-4521-ba73-a9f664e82c7bf \ + policies=my-policy +``` + +Once configured, from a PCF instance containing real values for the `CF_INSTANCE_CERT` and +`CF_INSTANCE_KEY`, login can be performed using: + +``` +$ vault login -method=pcf role=test-role +``` + +For PCF, we do also offer an agent that, once configured, can be used to obtain a Vault token on +your behalf. + +### Maintenance + +In testing we found that PCF instance identity CA certificates were set to expire in 3 years. Some +PCF 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-by +valid. + +``` +$ CURRENT=$(cat /path/to/current-ca.crt) +$ FUTURE=$(cat /path/to/future-ca.crt) +$ vault write auth/vault-plugin-auth-pcf/config identity_ca_certificates="$CURRENT,$FUTURE" +``` + +If Vault receives a `CF_INSTANCE_CERT` matching _any_ of the `identity_ca_certificates`, +the instance cert will be considered valid. + +A similar approach can be taken to update the `pcf_api_trusted_certificates`. + +### Troubleshooting At-A-Glance + +If you receive an error containing `x509: certificate signed by unknown authority`, set +`pcf_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 +``` + +Then, verify that +the certificates are properly chained to the `ca.crt` you've configured: + +``` +$ openssl verify -CAfile ca.crt -untrusted intermediate.crt identity.crt +``` + +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. + +## API + +The PCF auth method has a full HTTP API. Please see the [PCF Auth API](/api/auth/pcf/index.html) +for more details.