2018-03-21 19:02:38 +00:00
---
layout: "api"
2018-07-11 19:52:22 +00:00
page_title: "Google Cloud - Secrets Engines - HTTP API"
New Docs Website (#5535)
* conversion stage 1
* correct image paths
* add sidebar title to frontmatter
* docs/concepts and docs/internals
* configuration docs and multi-level nav corrections
* commands docs, index file corrections, small item nav correction
* secrets converted
* auth
* add enterprise and agent docs
* add extra dividers
* secret section, wip
* correct sidebar nav title in front matter for apu section, start working on api items
* auth and backend, a couple directory structure fixes
* remove old docs
* intro side nav converted
* reset sidebar styles, add hashi-global-styles
* basic styling for nav sidebar
* folder collapse functionality
* patch up border length on last list item
* wip restructure for content component
* taking middleman hacking to the extreme, but its working
* small css fix
* add new mega nav
* fix a small mistake from the rebase
* fix a content resolution issue with middleman
* title a couple missing docs pages
* update deps, remove temporary markup
* community page
* footer to layout, community page css adjustments
* wip downloads page
* deps updated, downloads page ready
* fix community page
* homepage progress
* add components, adjust spacing
* docs and api landing pages
* a bunch of fixes, add docs and api landing pages
* update deps, add deploy scripts
* add readme note
* update deploy command
* overview page, index title
* Update doc fields
Note this still requires the link fields to be populated -- this is solely related to copy on the description fields
* Update api_basic_categories.yml
Updated API category descriptions. Like the document descriptions you'll still need to update the link headers to the proper target pages.
* Add bottom hero, adjust CSS, responsive friendly
* Add mega nav title
* homepage adjustments, asset boosts
* small fixes
* docs page styling fixes
* meganav title
* some category link corrections
* Update API categories page
updated to reflect the second level headings for api categories
* Update docs_detailed_categories.yml
Updated to represent the existing docs structure
* Update docs_detailed_categories.yml
* docs page data fix, extra operator page remove
* api data fix
* fix makefile
* update deps, add product subnav to docs and api landing pages
* Rearrange non-hands-on guides to _docs_
Since there is no place for these on learn.hashicorp, we'll put them
under _docs_.
* WIP Redirects for guides to docs
* content and component updates
* font weight hotfix, redirects
* fix guides and intro sidenavs
* fix some redirects
* small style tweaks
* Redirects to learn and internally to docs
* Remove redirect to `/vault`
* Remove `.html` from destination on redirects
* fix incorrect index redirect
* final touchups
* address feedback from michell for makefile and product downloads
2018-10-19 15:40:11 +00:00
sidebar_title: "Google Cloud"
sidebar_current: "api-http-secret-gcp"
2018-03-21 19:02:38 +00:00
description: |-
2018-07-11 19:52:22 +00:00
This is the API documentation for the Vault Google Cloud secrets engine.
2018-03-21 19:02:38 +00:00
---
2018-07-11 19:52:22 +00:00
# Google Cloud Secrets Engine (API)
2018-03-21 19:02:38 +00:00
2018-07-11 19:52:22 +00:00
This is the API documentation for the Vault Google Cloud Platform (GCP)
2018-05-10 20:58:22 +00:00
secrets engine. For general information about the usage and operation of
2018-03-21 19:02:38 +00:00
the GCP secrets engine, please see [these docs ](/docs/secrets/gcp/index.html ).
This documentation assumes the GCP secrets engine is enabled at the `/gcp` path
in Vault. Since it is possible to mount secrets engines at any path, please
update your API calls accordingly.
## Write Config
| Method | Path | Produces |
| :------- | :------------------------| :------------------------ |
| `POST` | `/gcp/config` | `204 (empty body)` |
2018-05-10 20:58:22 +00:00
This endpoint configures shared information for the secrets engine.
2018-03-21 19:02:38 +00:00
### Parameters
- `credentials` (`string:""`) - JSON credentials (either file contents or '@path/to/file')
2018-05-10 20:58:22 +00:00
See docs for [alternative ways ](/docs/secrets/gcp/index.html#passing-credentials-to-vault )
to pass in to this parameter, as well as the
2018-03-21 19:02:38 +00:00
[required permissions ](/docs/secrets/gcp/index.html#required-permissions ).
- `ttl` (`int: 0 || string:"0s"`) – Specifies default config TTL for long-lived credentials
(i.e. service account keys). Accepts integer number of seconds or Go duration format string.
2018-05-17 15:54:25 +00:00
- `max_ttl` (`int: 0 || string:"0s"`)– Specifies the maximum config TTL for long-lived credentials
2018-03-21 19:02:38 +00:00
(i.e. service account keys). Accepts integer number of seconds or Go duration format string.**
2018-05-10 20:58:22 +00:00
2018-03-21 19:02:38 +00:00
### Sample Payload
```json
{
"credentials": "< JSON string > ",
"ttl": 3600,
"max_ttl": 14400
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload .json \
2018-07-10 14:47:30 +00:00
https://127.0.0.1:8200/v1/gcp/config
2018-03-21 19:02:38 +00:00
```
## Read Config
| Method | Path | Produces |
| :------- | :------------------------| :------------------------ |
| `GET` | `/gcp/config` | `200 application/json` |
2018-05-10 20:58:22 +00:00
Credentials will be omitted from returned data.
2018-03-21 19:02:38 +00:00
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
2018-07-10 14:47:30 +00:00
https://127.0.0.1:8200/v1/gcp/config
2018-03-21 19:02:38 +00:00
```
### Sample Response
```json
{
"data": {
"ttl": "1h",
"max_ttl": "4h"
}
}
```
## Create/Update Roleset
| Method | Path | Produces |
| :------- | :------------------------| :------------------------ |
| `POST` | `/gcp/roleset/:name` | `204 (empty body)` |
This method allows you to create a roleset or update an existing roleset. See [roleset docs ](/docs/secrets/gcp/index.html#rolesets ) for the GCP secrets backend
2018-05-10 20:58:22 +00:00
to learn more about what happens when you create or update a roleset.
2018-03-21 19:02:38 +00:00
2018-05-10 20:58:22 +00:00
**If you update a roleset's bindings, this will effectively revoke any secrets
generated under this roleset.**
2018-03-21 19:02:38 +00:00
### Parameters
- `name` (`string: < required > `): Required. Name of the role. Cannot be updated.
- `secret_type` (`string: "access_token"`): Type of secret generated for this role set. Accepted values: `access_token` , `service_account_key` . Cannot be updated.
2018-05-10 20:58:22 +00:00
- `project` (`string: < required > `): Name of the GCP project that this roleset's service account will belong to. Cannot be updated.
2018-03-21 19:02:38 +00:00
- `bindings` (`string: < required > `): Bindings configuration string (expects HCL or JSON format in raw or base64-encoded string)
- `token_scopes` (`array: []`): List of OAuth scopes to assign to `access_token` secrets generated under this role set (`access_token` role sets only)
### Sample Payload
```json
{
"secret_type": "access_token",
"project": "mygcpproject",
"bindings": "...",
2018-05-10 20:58:22 +00:00
"token_scopes": [
"https://www.googleapis.com/auth/cloud-platform",
2018-03-21 19:02:38 +00:00
"https://www.googleapis.com/auth/bigquery"
]
}
```
#### Sample Bindings:
See [bindings format docs ](/docs/secrets/gcp/index.html#roleset-bindings ) for more information.
```hcl
2018-12-18 00:22:02 +00:00
resource "//cloudresourcemanager.googleapis.com/projects/mygcpproject" {
2018-03-21 19:02:38 +00:00
roles = [
"roles/viewer"
2018-05-10 20:58:22 +00:00
],
2018-03-21 19:02:38 +00:00
}
resource "https://selflink/to/my/resource" {
roles = [
"project/mygcpproject/roles/projcustomrole",
"organizations/myorg/roles/orgcustomrole"
2018-05-10 20:58:22 +00:00
],
2018-03-21 19:02:38 +00:00
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload .json \
2018-07-10 14:47:30 +00:00
https://127.0.0.1:8200/v1/gcp/roleset/my-token-roleset
2018-03-21 19:02:38 +00:00
```
## Rotate Roleset Account
| Method | Path | Produces |
| :------- | :--------------------------------| :--------------------- |
| `POST` | `/gcp/roleset/:name/rotate` | `204 (empty body)` ` |
2018-05-10 20:58:22 +00:00
This will rotate the service account this roleset uses to generate secrets.
2018-03-21 19:02:38 +00:00
(this also replaces the key `access_token` roleset). This can be used to invalidate
old secrets generated by the roleset or fix issues if a roleset's service account
2018-05-10 20:58:22 +00:00
(and/or keys) was changed outside of Vault (i.e. through GCP APIs/cloud console).
2018-03-21 19:02:38 +00:00
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
2018-07-10 14:47:30 +00:00
https://127.0.0.1:8200/v1/consul/gcp/roleset/my-token-roleset/rotate
2018-03-21 19:02:38 +00:00
```
## Rotate Roleset Account Key (`access_token` Roleset Only)
| Method | Path | Produces |
| :------- | :--------------------------------| :--------------------- |
| `POST` | `/gcp/roleset/:name/rotate-key` | `204 (empty body)` ` |
This will rotate the service account key this roleset uses to generate
access tokens. This does not recreate the roleset service account.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
2018-07-10 14:47:30 +00:00
https://127.0.0.1:8200/v1/consul/gcp/roleset/my-token-roleset/rotate-key
2018-03-21 19:02:38 +00:00
```
## Read Roleset
| Method | Path | Produces |
| :------- | :------------------------| :------------------------ |
| `GET` | `/gcp/roleset/:name` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
2018-07-10 14:47:30 +00:00
https://127.0.0.1:8200/v1/consul/gcp/roleset/my-token-roleset
2018-03-21 19:02:38 +00:00
```
### Sample Response
```json
{
"data": {
"secret_type": "access_token",
"service_account_email": "vault-myroleset-XXXXXXXXXX@myproject.gserviceaccounts.com",
2018-09-21 17:31:49 +00:00
"service_account_project": "service-account-project",
2018-03-21 19:02:38 +00:00
"bindings": {
"project/mygcpproject": [
"roles/viewer"
2018-05-10 20:58:22 +00:00
],
2018-03-21 19:02:38 +00:00
"https://selflink/to/my/resource": [
"project/mygcpproject/roles/projcustomrole",
"organizations/myorg/roles/orgcustomrole"
]
},
"token_scopes" : [
"https://www.googleapis.com/auth/cloud-platform"
]
}
}
```
## List Rolesets
| Method | Path | Produces |
| :------- | :------------------------| :------------------------ |
| `LIST` | `/gcp/rolesets` | `200 application/json` |
| Method | Path | Produces |
| :------- | :------------------------| :------------------------ |
| `LIST` | `/gcp/roleset` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
2018-07-10 14:47:30 +00:00
https://127.0.0.1:8200/v1/gcp/rolesets
2018-03-21 19:02:38 +00:00
```
### Sample Response
```json
{
"data": {
"keys": [
"my-token-roleset",
"my-sakey-roleset"
]
}
}
```
## Generate Secret (IAM Service Account Creds): OAuth2 Access Token
| Method | Path | Produces |
| :---------------- | :----------------------------- | :------------------------ |
| `GET` | `POST` | `/gcp/token/:roleset` | `200 application/json` |
Generates an OAuth2 token with the scopes defined on the roleset. This OAuth access token can
2018-05-10 20:58:22 +00:00
be used in GCP API calls, e.g. `curl -H "Authorization: Bearer $TOKEN" ...`
2018-03-21 19:02:38 +00:00
2018-09-21 17:31:49 +00:00
Tokens are non-revocable and non-renewable and have a static TTL of an hour. The TTL configured
for the backend (either through the default system TTLs or through the `config/` endpoint)
do not apply.
2018-03-21 19:02:38 +00:00
### Parameters
- `roleset` (`string:< required > `): Name of an roleset with secret type `access_token` to generate access_token under.
### Sample Request
```sh
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
2018-07-10 14:47:30 +00:00
https://127.0.0.1:8200/v1/consul/gcp/roleset/my-token-roleset
2018-03-21 19:02:38 +00:00
```
### Sample Response
```json
{
"request_id":"< uuid > ",
"data": {
2018-09-21 17:31:49 +00:00
"token":"ya29.c.Elp5Be3ga87...",
"expires_at_seconds": 1537400046,
"token_ttl": 3599
2018-03-21 19:02:38 +00:00
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Generate Secret (IAM Service Account Creds): Service Account Key
| Method | Path | Produces |
| :---------------- | :----------------------------- | :------------------------ |
| `GET` | `POST` | `/gcp/key/:roleset` | `200 application/json` |
If using `GET` ('read'), the optional parameters will be set to their defaults. Use `POST` if you
want to specify different values for these params.
These keys are renewable and have TTL/max TTL as defined by either the backend config
2018-05-10 20:58:22 +00:00
or the system default if config was not defined.
2018-03-21 19:02:38 +00:00
### Parameters
- `roleset` (`string:< required > `): Name of an roleset with secret type `service_account_key` to generate key under.
2018-05-10 20:58:22 +00:00
- `key_algorithm` (`string:"KEY_ALG_RSA_2048"`): Key algorithm used to generate key. Defaults to 2k RSA key
You probably should not choose other values (i.e. 1k), but accepted values are
2018-03-21 19:02:38 +00:00
`enum(` [`ServiceAccountKeyAlgorithm` ](https://cloud.google.com/iam/reference/rest/v1/projects.serviceAccounts.keys#ServiceAccountKeyAlgorithm )`)`
- `key_type` (`string:"TYPE_GOOGLE_CREDENTIALS_FILE`): Private key type to generate. Defaults to JSON credentials file.
Accepted values are `enum(` [`ServiceAccountPrivateKeyType` ](https://cloud.google.com/iam/reference/rest/v1/projects.serviceAccounts.keys#ServiceAccountPrivateKeyType )`)`
2018-05-10 20:58:22 +00:00
### Sample Payload
2018-03-21 19:02:38 +00:00
```json
{
"key_algorithm": "TYPE_GOOGLE_CREDENTIALS_FILE",
"key_type": "KEY_ALG_RSA_2048"
}
```
### Sample Request
```sh
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
2018-07-10 14:47:30 +00:00
https://127.0.0.1:8200/v1/gcp/roleset/my-token-roleset
2018-03-21 19:02:38 +00:00
```
```sh
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload .json \
2018-07-10 14:47:30 +00:00
https://127.0.0.1:8200/v1/gcp/roleset/my-token-roleset
2018-03-21 19:02:38 +00:00
```
### Sample Response
```json
{
"request_id":"< uuid > ",
"lease_id":"gcp/key/my-key-roleset/< uuid > ",
"renewable":true,
"lease_duration":3600,
"data": {
"private_key_data":"< base64-encoded private key data > ",
"key_algorithm": "TYPE_GOOGLE_CREDENTIALS_FILE",
2018-05-10 20:58:22 +00:00
"key_type": "KEY_ALG_RSA_2048"
2018-03-21 19:02:38 +00:00
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Revoking/Renewing Secrets
2018-05-10 20:58:22 +00:00
See docs on how to [renew ](/api/system/leases.html#renew-lease ) and [revoke ](/api/system/leases.html#revoke-lease ) leases.
2018-09-21 17:31:49 +00:00
Note this only applies to service account keys.