layout | page_title | sidebar_title | description |
---|---|---|---|
api |
Google Cloud - Auth Methods - HTTP API |
Google Cloud |
This is the API documentation for the Vault Google Cloud authentication
method. |
This is the API documentation for the Vault Google Cloud auth method. To learn more about the usage and operation, see the Vault Google Cloud method documentation.
This documentation assumes the plugin method is mounted at the
/auth/gcp
path in Vault. Since it is possible to enable auth methods
at any location, please update your API calls accordingly.
Configures the credentials required for the plugin to perform API calls to Google Cloud. These credentials will be used to query the status of IAM entities and get service account or other Google public certificates to confirm signed JWTs passed in during login.
Method | Path |
---|---|
POST |
/auth/gcp/config |
-
credentials
(string: "")
- A JSON string containing the contents of a GCP credentials file. The credentials file must have the following permissions:iam.serviceAccounts.get iam.serviceAccountKeys.get
If this value is empty, Vault will try to use Application Default Credentials from the machine on which the Vault server is running.
The project must have the
iam.googleapis.com
API enabled. -
iam_alias
(string: "unique_id")
- Must be eitherunique_id
orrole_id
. Ifunique_id
is specified, the service account's unique ID will be used for alias names during login. Ifrole_id
is specified, the ID of the Vault role will be used. Only used if roletype
isiam
. -
iam_metadata
(string: "default")
- The metadata to include on the token returned by thelogin
endpoint. This metadata will be added to both audit logs, and on theiam_alias
. By default, it includesproject_id
,role
,service_account_id
, andservice_account_email
. To include no metadata, set to""
via the CLI or[]
via the API. To use only particular fields, select the explicit fields. To restore to defaults, send only a field ofdefault
. Only select fields that will have a low rate of change for youriam_alias
because each change triggers a storage write and can have a performance impact at scale. Only used if roletype
isiam
. -
gce_alias
(string: "instance_id")
- Must be eitherinstance_id
orrole_id
. Ifinstance_id
is specified, the GCE instance ID will be used for alias names during login. Ifrole_id
is specified, the ID of the Vault role will be used. Only used if roletype
isgce
. -
gce_metadata
(string: "default")
- The metadata to include on the token returned by thelogin
endpoint. This metadata will be added to both audit logs, and on thegce_alias
. By default, it includesinstance_creation_timestamp
,instance_id
,instance_name
,project_id
,project_number
,role
,service_account_id
,service_account_email
, andzone
. To include no metadata, set to""
via the CLI or[]
via the API. To use only particular fields, select the explicit fields. To restore to defaults, send only a field ofdefault
. Only select fields that will have a low rate of change for yourgce_alias
because each change triggers a storage write and can have a performance impact at scale. Only used if roletype
isgce
.
{
"credentials": "{ \"type\": \"service_account\", \"project_id\": \"project-123456\", ...}"
}
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/gcp/config
Returns the configuration, if any, including credentials.
Method | Path |
---|---|
GET |
/auth/gcp/config |
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/gcp/config
{
"data": {
"client_email": "service-account@project-123456.iam.gserviceaccount.com",
"client_id": "123456789101112131415",
"private_key_id": "97fd7ba59a96e1f3830296aedb4f50879e4d5382",
"project_id": "project-123456"
}
}
Registers a role in the method. Role types have specific entities that can perform login operations against this endpoint. Constraints specific to the role type must be set on the role. These are applied to the authenticated entities attempting to login.
Method | Path |
---|---|
POST |
/auth/gcp/role/:name |
-
name
(string: <required>)
- The name of the role. -
type
(string: <required>)
- The type of this role. Certain fields correspond to specific roles and will be rejected otherwise. Please see below for more information. -
bound_service_accounts
(array: <required for iam>)
- An array of service account emails or IDs that login is restricted to, either directly or through an associated instance. If set to*
, all service accounts are allowed (you can bind this further usingbound_projects
.) -
bound_projects
(array: [])
- An array of GCP project IDs. Only entities belonging to this project can authenticate under the role. -
add_group_aliases
(bool: false)
- If true, any auth token generated under this token will have associated group aliases, namelyproject-$PROJECT_ID
,folder-$PROJECT_ID
, andorganization-$ORG_ID
for the entities project and all its folder or organization ancestors. This requires Vault to have IAM permissionresourcemanager.projects.get
.
@include 'partials/tokenfields.mdx'
The following parameters are only valid when the role is of type "iam"
:
-
max_jwt_exp
(string: "15m")
- The number of seconds past the time of authentication that the login param JWT must expire within. For example, if a user attempts to login with a token that expires within an hour and this is set to 15 minutes, Vault will return an error prompting the user to create a new signed JWT with a shorterexp
. The GCE metadata tokens currently do not allow theexp
claim to be customized. -
allow_gce_inference
(bool: true)
- A flag to determine if this role should allow GCE instances to authenticate by inferring service accounts from the GCE identity metadata token.
The following parameters are only valid when the role is of type "gce"
:
-
bound_zones
(array: [])
: The list of zones that a GCE instance must belong to in order to be authenticated. Ifbound_instance_groups
is provided, it is assumed to be a zonal group and the group must belong to this zone. -
bound_regions
(array: [])
: The list of regions that a GCE instance must belong to in order to be authenticated. Ifbound_instance_groups
is provided, it is assumed to be a regional group and the group must belong to this region. Ifbound_zones
are provided, this attribute is ignored. -
bound_instance_groups
(array: [])
: The instance groups that an authorized instance must belong to in order to be authenticated. If specified, eitherbound_zones
orbound_regions
must be set too. -
bound_labels
(array: [])
: A comma-separated list of GCP labels formatted as "key:value" strings that must be set on authorized GCE instances. Because GCP labels are not currently ACL'd, we recommend that this be used in conjunction with other restrictions.
Example iam
role:
{
"type": "iam",
"project_id": "project-123456",
"policies": ["prod"],
"ttl": "30m",
"max_ttl": "24h",
"max_jwt_exp": "5m",
"bound_service_accounts": ["dev-1@project-123456.iam.gserviceaccount.com"]
}
Example gce
role:
{
"type": "gce",
"project_id": "project-123456",
"policies": ["prod"],
"bound_zones": ["us-east1-b", "eu-west2-a"],
"ttl": "30m",
"max_ttl": "24h",
"bound_service_accounts": ["dev-1@project-123456.iam.gserviceaccount.com"]
}
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/gcp/role/my-role
Edit service accounts for an existing IAM role in the method. This allows you to add or remove service accounts from the list of service accounts on the role.
Method | Path |
---|---|
POST |
/auth/gcp/role/:name/service-accounts |
-
name
(string: <required>)
- The name of an existingiam
type role. This will return an error if role is not aniam
type role. -
add
(array: [])
- The list of service accounts to add to the role's service accounts. -
remove
(array: [])
- The list of service accounts to remove from the role's service accounts.
{
"add": ["dev-1@project-123456.iam.gserviceaccount.com", "123456789"],
"remove": ["dev-2@project-123456.iam.gserviceaccount.com"]
}
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/gcp/role/my-role
Edit labels for an existing GCE role in the backend. This allows you to add or remove labels (keys, values, or both) from the list of keys on the role.
Method | Path |
---|---|
POST |
/auth/gcp/role/:name/labels |
-
name
(string: <required>)
- The name of an existinggce
role. This will return an error if role is not agce
type role. -
add
(array: [])
- The list ofkey:value
labels to add to the GCE role's bound labels. -
remove
(array: [])
- The list of label keys to remove from the role's bound labels. If any of the specified keys do not exist, no error is returned (idempotent).
{
"add": ["foo:bar", "env:dev", "key:value"],
"remove": ["key1", "key2"]
}
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/gcp/role/my-role
Returns the previously registered role configuration.
Method | Path |
---|---|
GET |
/auth/gcp/role/:name |
name
(string: <required>)
- The name of the role to read.
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/gcp/role/my-role
{
"data": {
"bound_labels": {
"env": "dev",
"foo": "bar",
"key": "value"
},
"bound_service_accounts": ["dev-1@project-123456.iam.gserviceaccount.com"],
"bound_zones": ["eu-west2-a", "us-east1-b"],
"gce_alias": "instance_id",
"max_ttl": 86400,
"policies": ["prod"],
"project_id": "project-123456",
"role_id": "6bbfab2b-ca32-6044-4829-4515728d87b1",
"type": "gce",
"ttl": 1800
}
}
Lists all the roles that are registered with the plugin.
Method | Path |
---|---|
LIST |
/auth/gcp/roles |
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/gcp/roles
{
"data": {
"keys": ["my-role", "my-other-role"]
}
}
Deletes the previously registered role.
Method | Path |
---|---|
DELETE |
/auth/gcp/role/:role |
role
(string: <required>)
- The name of the role to delete.
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/gcp/role/my-role
Login to retrieve a Vault token. This endpoint takes a signed JSON Web Token (JWT) and a role name for some entity. It verifies the JWT signature with Google Cloud to authenticate that entity and then authorizes the entity for the given role.
Method | Path |
---|---|
POST |
/auth/gcp/login |
-
role
(string: <required>)
- The name of the role against which the login is being attempted. -
jwt
(string: <required>)
- A Signed JSON Web Token.-
For
iam
type roles, this is a JWT signed with thesignJwt
method or a self-signed JWT. -
For
gce
type roles, this is an identity metadata token.
-
{
"role": "my-role",
"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/gcp/login
{
"auth": {
"client_token": "f33f8c72-924e-11f8-cb43-ac59d697597c",
"accessor": "0e9e354a-520f-df04-6867-ee81cae3d42d",
"policies": ["default", "dev", "prod"],
"metadata": {
"project_id": "my-project",
"role": "my-role",
"service_account_email": "dev1@project-123456.iam.gserviceaccount.com",
"service_account_id": "111111111111111111111"
},
"lease_duration": 2764800,
"renewable": true
}
}