»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.
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.
| Method | Path |
|---|---|
POST | /auth/cf/config |
»Parameters
identity_ca_certificates(array: [], required)- The root CA certificate(s) to be used for verifying that theCF_INSTANCE_CERTpresented 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 givenCF_INSTANCE_CERTshows 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, resolvingx509: certificate signed by unknown authorityerrors.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
»Sample Request
»Read Config
Returns the present CF configuration.
| Method | Path |
|---|---|
GET | /auth/cf/config |
»Sample Request
»Sample Response
»Delete Config
Deletes the present CF configuration.
| Method | Path |
|---|---|
DELETE | /auth/cf/config |
»Sample Request
»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 usecf pushon 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.
token_ttl(integer: 0 or string: "")- The incremental lifetime for generated tokens. This current value of this will be referenced at renewal time.token_max_ttl(integer: 0 or string: "")- The maximum lifetime for generated tokens. This current value of this will be referenced at renewal time.token_policies(array: [] or comma-delimited string: "")- List of policies to encode onto generated tokens. Depending on the auth method, this list may be supplemented by user/group/other values.
token_bound_cidrs(array: [] or comma-delimited string: "")- List of CIDR blocks; if set, specifies blocks of IP addresses which can authenticate successfully, and ties the resulting token to these blocks as well.token_explicit_max_ttl(integer: 0 or string: "")- If set, will encode an explicit max TTL onto the token. This is a hard cap even iftoken_ttlandtoken_max_ttlwould otherwise allow a renewal.token_no_default_policy(bool: false)- If set, thedefaultpolicy will not be set on generated tokens; otherwise it will be added to the policies set intoken_policies.token_num_uses(integer: 0)- The maximum number of times a generated token may be used (within its lifetime); 0 means unlimited. If you require the token to have the ability to create child tokens, you will need to set this value to 0.token_period(integer: 0 or string: "")- The period, if any, to set on the token.token_type(string: "")- The type of token that should be generated. Can beservice,batch, ordefaultto use the mount's tuned default (which unless changed will beservicetokens). For token store roles, there are two additional possibilities:default-serviceanddefault-batchwhich specify the type to return unless the client requests a different type at generation time.
»Sample Payload
»Sample Request
»Read Role
Returns a CF role.
| Method | Path |
|---|---|
GET | /auth/cf/roles/:role |
»Sample Request
»Sample Response
»Delete Role
Deletes a CF role.
| Method | Path |
|---|---|
DELETE | /auth/cf/roles/:role |
»Sample Request
»List Roles
Returns a CF role.
| Method | Path |
|---|---|
LIST | /auth/cf/roles |
»Sample Request
»Sample Response
»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.
The plugin repo 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 (
checksumbelow). - 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:
- 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 byCF_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 theCF_INSTANCE_KEY.
»Sample Payload
»Sample Request
»Sample Response
