open-vault/website/pages/api-docs/auth/cf/index.mdx
Jeff Escalante 4f87851926 [website] Link Cleaning (#8205)
* update dependencies

* remove hard-coded vaultproject.io on local links

* remove 'index.html' from internal links

* remove '.html' at end of internal links

* manual review cleanup

Co-authored-by: Calvin Leung Huang <cleung2010@gmail.com>
2020-01-22 12:05:41 -08:00

338 lines
10 KiB
Plaintext

---
layout: api
page_title: Cloud Foundry - Auth Methods - HTTP API
sidebar_title: Cloud Foundry
description: This is the API documentation for the Vault Cloud Foundry auth method.
---
# Pivotal Cloud Foundry (CF) Auth Method (API)
This is the API documentation for the Vault CF auth method. For
general information about the usage and operation of the CF method, please
see the [Vault CF method documentation](/docs/auth/cf).
This documentation assumes the CF method is mounted at the `/auth/cf`
path in Vault. Since it is possible to enable auth methods at any location,
please update your API calls accordingly.
## Create Configuration
Configure the root CA certificate to be used for verifying instance identity
certificates, and configure access to the CF API. For detailed instructions
on how to obtain these values, please see the [Vault CF method
documentation](/docs/auth/cf).
| Method | Path |
| :----- | ----------------- |
| `POST` | `/auth/cf/config` |
### Parameters
- `identity_ca_certificates` `(array: [], required)` - The root CA certificate(s)
to be used for verifying that the `CF_INSTANCE_CERT` presented for logging in was
issued by the proper authority.
- `cf_api_addr` `(string: required)`: CF's full API address, to be used for verifying
that a given `CF_INSTANCE_CERT` shows an application ID, space ID, and organization ID
that presently exist.
- `cf_username` `(string: required)`: The username for authenticating to the CF API.
- `cf_password` `(string: required)`: The password for authenticating to the CF API.
- `cf_api_trusted_certificates` `(array: [])`: The certificate that's presented by the
CF API. This configures Vault to trust this certificate when making API calls, resolving
`x509: certificate signed by unknown authority` errors.
- `login_max_seconds_not_before` `(int: 300)`: The maximum number of seconds in the past when a
signature could have been created. The lower the value, the lower the risk of replay
attacks.
- `login_max_seconds_not_after` `(int: 60)`: In case of clock drift, the maximum number of
seconds in the future when a signature could have been created. The lower the value,
the lower the risk of replay attacks.
### Sample Payload
```json
{
"identity_ca_certificates": [
"-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----"
],
"cf_api_addr": "https://api.sys.somewhere.cf-app.com",
"cf_username": "vault",
"cf_password": "pa55w0rd",
"cf_api_trusted_certificates": [
"-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----"
],
"login_max_seconds_not_before": 5,
"login_max_seconds_not_after": 1
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/cf/config
```
## Read Config
Returns the present CF configuration.
| Method | Path |
| :----- | ----------------- |
| `GET` | `/auth/cf/config` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/cf/config
```
### Sample Response
```json
{
"identity_ca_certificates": [
"-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----"
],
"cf_api_addr": "https://api.sys.somewhere.cf-app.com",
"cf_username": "vault",
"cf_api_trusted_certificates": [
"-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----"
],
"login_max_seconds_not_before": 5,
"login_max_seconds_not_after": 1
}
```
## Delete Config
Deletes the present CF configuration.
| Method | Path |
| :------- | ----------------- |
| `DELETE` | `/auth/cf/config` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/cf/config
```
## Create Role
Create a role in Vault granting a particular level of access to a particular group
of CF instances. We recommend using the CF API or the CF CLI to gain the IDs you
wish to target.
If you list no `bound` parameters, then any entity with a valid
`CF_INSTANCE_CERT` that's been issued by any configured `identity_ca_certificates`
will be able to authenticate against this role.
| Method | Path |
| :----- | ---------------------- |
| `POST` | `/auth/cf/roles/:role` |
### Parameters
- `role` `(string: required)` - The name of the role.
- `bound_application_ids` `(array: [])` - An optional list of application IDs
an instance must be a member of to qualify as a member of this role.
- `bound_space_ids` `(array: [])` - An optional list of space IDs
an instance must be a member of to qualify as a member of this role.
- `bound_organization_ids` `(array: [])` - An optional list of organization IDs
an instance must be a member of to qualify as a member of this role.
- `bound_instance_ids` `(array: [])` - An optional list of instance IDs
an instance must be a member of to qualify as a member of this role. Please note that
every time you use `cf push` on an app, its instance ID changes. Also, instance IDs
are not verifiable as being presently alive using the CF API. Thus, we recommend against
using this setting for most use cases.
- `disable_ip_matching` `(bool: false)` - If set to true, disables the default behavior
that logging in must be performed from an acceptable IP address described by the
certificate presented. Should only be set to true if required, generally when a proxy
is used to perform logins.
@include 'partials/tokenfields.mdx'
### Sample Payload
```json
{
"bound_application_ids": ["09d7eb6a-afc2-49a0-bb32-858c22f2b346"],
"bound_space_ids": ["21005ebb-8943-433e-84e6-d9d9d7338853"],
"bound_organization_ids": ["9785a884-5e93-49bd-97ee-57bf7c2b20e0"],
"bound_instance_ids": ["f3e0f176-3f83-4efb-5842-2ff4"],
"bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"],
"policies": ["default"],
"ttl": "1h",
"max_ttl": "1h",
"period": "1h"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/cf/roles/:role
```
## Read Role
Returns a CF role.
| Method | Path |
| :----- | ---------------------- |
| `GET` | `/auth/cf/roles/:role` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/cf/roles/:role
```
### Sample Response
```json
{
"bound_application_ids": ["09d7eb6a-afc2-49a0-bb32-858c22f2b346"],
"bound_space_ids": ["21005ebb-8943-433e-84e6-d9d9d7338853"],
"bound_organization_ids": ["9785a884-5e93-49bd-97ee-57bf7c2b20e0"],
"bound_instance_ids": ["f3e0f176-3f83-4efb-5842-2ff4"],
"bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"],
"policies": ["default"],
"ttl": 2764790,
"max_ttl": 2764790,
"period": 2764790
}
```
## Delete Role
Deletes a CF role.
| Method | Path |
| :------- | ---------------------- |
| `DELETE` | `/auth/cf/roles/:role` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/cf/roles/:role
```
## List Roles
Returns a CF role.
| Method | Path |
| :----- | ---------------- |
| `LIST` | `/auth/cf/roles` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request LIST
http://127.0.0.1:8200/v1/auth/cf/roles
```
### Sample Response
```json
{
"data": {
"keys": ["role1", "role2"]
}
}
```
## Login
Log in to CF.
Vault provides both an agent and a CLI tool for logging in that
eliminates the need to build a signature yourself. However, if you do wish to
build the signature, its signing algorithm is viewable [here](https://github.com/hashicorp/vault-plugin-auth-cf/tree/master/signatures).
The [plugin repo](https://github.com/hashicorp/vault-plugin-auth-cf) also contains
a command-line tool (`generate-signature`) that can be compiled as a binary for generating a signature,
and a test that outputs steps in generating the signature so they can be duplicated.
However, at a high level, these are the steps for generating a signature:
- Get and format the current time, ex. `2006-01-02T15:04:05Z`.
- Get the full body of the file located at `CF_INSTANCE_CERT`.
- Get the name of the role.
- Concatenate them together in the above order, with no extra string used for joining them.
- Create a SHA256 checksum of the resulting string (`checksum` below).
- Sign the string using the key located at `CF_INSTANCE_KEY`. In Go, this is performed using
the following line of code which you can more deeply inspect:
```
rsa.SignPSS(rand.Reader, rsaPrivateKey, crypto.SHA256, checksum, nil)
```
- Convert the signature to a string.
| Method | Path |
| :----- | ---------------- |
| `POST` | `/auth/cf/login` |
### Parameters
- `role` `(string: required)` - The name of the role.
- `cf_instance_cert` `(string: required)` - The full body of the file available at
the path denoted by `CF_INSTANCE_CERT`.
- `signing_time` `(string: required)` - The date and time used to construct the signature.
- `signature` `(string: required)` - The signature generated by the algorithm described
above using the `CF_INSTANCE_KEY`.
### Sample Payload
```json
{
"role": "test-role",
"cf_instance_cert": "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----",
"signing_time": "2006-01-02T15:04:05Z",
"signature": "MmyUjQ1OqxQmF0W6raVQDL-hlqqe1oG-7abA6Oi3NHwT-9lMfrYxsCwMnd2HKGMly2tCgetcoA2orfquoe6MkMuksx_KGH_KLObcAykt53z4rHceHKGvm7eGj60cjWFYtiNPic-lzUGERLbUeKLMi6NlThm9ueb7hhpyTUpEYtphV3gorbVxvlkrnuYSbgy2NGpOUY1N8dRzcxmHkYjh12XoWEw4Is5aFr6eFKbZ0vmLWBzhJ7_w20CFyTpRYB-6heGz1iR9qEG8mZk3_x4rZpT5mejJ5zmH2xlUjBJMndfcz47btEi2BO9pFVxK2wK-tKeUUFgx6RcomAopTskkmg=="
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/cf/login
```
### Sample Response
```json
{
"auth": {
"renewable": true,
"lease_duration": 1800000,
"policies": ["default", "dev"],
"accessor": "20b89871-e6f2-1160-fb29-31c2f6d4645e",
"client_token": "c9368254-3f21-aded-8a6f-7c818e81b17a"
}
}
```