This page shows you how to create, disable, and delete Hash-based Message Authentication Code (HMAC) keys associated with service accounts in your project.
Prerequisites
Before using this feature in Cloud Storage, you should:
Have sufficient permission to work with HMAC keys in the desired project:
If you own the project, you most likely have the necessary permissions.
You should have the IAM permissions that are prefixed with
storage.hmacKeys
for the project. See Using IAM Permissions for instructions on how to get a role, such as Storage HMAC Key Admin, that has these permissions.
Have a service account in your project that you intend to create HMAC keys for. See Creating a service account if you don't currently have one.
Creating an HMAC key
To create an HMAC key for a service account:
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser Click Settings.
Select the Interoperability tab.
Click + Create a key for a service account.
Select the service account you want the HMAC key to be associated with.
Click Create key.
See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.
gsutil
Use the hmac create
command:
gsutil hmac create SERVICE_ACCOUNT_EMAIL
Where SERVICE_ACCOUNT_EMAIL
is the email address
associated with your service account. For example,
service-7550275089395@my-pet-project.iam.gserviceaccount.com
.
If successful, the response looks like:
AccessId: GOOGTS7C7FUP3AIRVJTE2BCD SecretKey: de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the JSON API with aPOST
hmacKeys request,:curl -X POST \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/storage/v1/projects/PROJECT_ID/hmacKeys?serviceAccountEmail=SERVICE_ACCOUNT_EMAIL"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.PROJECT_ID
is the ID for the project associated with the key you want to create. For example,my-pet-project
.SERVICE_ACCOUNT_EMAIL
is the email address associated with your service account. For example,service-7550275089395@my-pet-project.iam.gserviceaccount.com
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the XML API with aPOST
HMAC Key request:curl -X POST \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/?Action=CreateAccessKey&UserName=SERVICE_ACCOUNT_EMAIL"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.SERVICE_ACCOUNT_EMAIL
is the email address associated with your service account. For example,service-7550275089395@my-pet-project.iam.gserviceaccount.com
.
Getting HMAC key information
To list the HMAC keys for a project, and get information about the keys:
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser Click Settings.
Select the Interoperability tab.
gsutil
Use the
hmac list
command to list hmac keys in your project:gsutil hmac list
If successful, gsutil returns a list of hmac key access IDs, along with the service account associated with each key.
Use the
hmac get
command to retrieve metadata for a specific key:gsutil hmac get KEY_ACCESS_ID
Where
KEY_ACCESS_ID
is the access ID for the desired key.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
The following sample retrieves a list of HMAC keys associated with a project: The following sample retrieves information for a specific HMAC key:
For more information, see the
Cloud Storage C# API reference documentation.
The following sample retrieves a list of HMAC keys associated with a project: The following sample retrieves information for a specific HMAC key:
For more information, see the
Cloud Storage Go API reference documentation.
The following sample retrieves a list of HMAC keys associated with a project: The following sample retrieves information for a specific HMAC key:
For more information, see the
Cloud Storage Java API reference documentation.
The following sample retrieves a list of HMAC keys associated with a project: The following sample retrieves information for a specific HMAC key:
For more information, see the
Cloud Storage Node.js API reference documentation.
The following sample retrieves a list of HMAC keys associated with a project: The following sample retrieves information for a specific HMAC key:
For more information, see the
Cloud Storage PHP API reference documentation.
The following sample retrieves a list of HMAC keys associated with a project: The following sample retrieves information for a specific HMAC key:
For more information, see the
Cloud Storage Python API reference documentation.
The following sample retrieves a list of HMAC keys associated with a project: The following sample retrieves information for a specific HMAC key:
For more information, see the
Cloud Storage Ruby API reference documentation.
The following sample retrieves a list of HMAC keys associated with a project: The following sample retrieves information for a specific HMAC key:C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the JSON API with aLIST
hmacKeys request:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/projects/PROJECT_ID/hmacKeys"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.PROJECT_ID
is the ID for the project associated with the keys you want to list. For example,my-pet-project
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the XML API with aGET
HMAC Key request:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/?Action=ListAccessKeys&UserName=SERVICE_ACCOUNT_EMAIL"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.SERVICE_ACCOUNT_EMAIL
is the email address associated with your service account. For example,service-7550275089395@my-pet-project.iam.gserviceaccount.com
.
Updating the state of an HMAC key
To switch an HMAC key between being active and inactive:
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser Click Settings.
Select the Interoperability tab.
Click the name of the service account associated with the key you want to update.
Click the more actions menu (
) associated with the key you want to update.
Select the state you want to apply to the key.
In the confirmation window that appears, confirm you want to change the state of the key.
gsutil
Use the hmac update
command:
gsutil hmac update -s STATE ACCESS_KEY_ID
Where:
STATE
is the desired state for the key. For example,INACTIVE
.ACCESS_KEY_ID
is the access ID associated with the key you are updating.
If successful, gsutil returns the updated metadata of the HMAC key.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
The following sample deactivates an HMAC key: The following sample activates an HMAC key:
For more information, see the
Cloud Storage C# API reference documentation.
The following sample deactivates an HMAC key: The following sample activates an HMAC key:
For more information, see the
Cloud Storage Go API reference documentation.
The following sample deactivates an HMAC key: The following sample activates an HMAC key:
For more information, see the
Cloud Storage Java API reference documentation.
The following sample deactivates an HMAC key: The following sample activates an HMAC key:
For more information, see the
Cloud Storage Node.js API reference documentation.
The following sample deactivates an HMAC key: The following sample activates an HMAC key:
For more information, see the
Cloud Storage PHP API reference documentation.
The following sample deactivates an HMAC key: The following sample activates an HMAC key:
For more information, see the
Cloud Storage Python API reference documentation.
The following sample deactivates an HMAC key: The following sample activates an HMAC key:
For more information, see the
Cloud Storage Ruby API reference documentation.
The following sample deactivates an HMAC key: The following sample activates an HMAC key:C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create a .json file that contains the following information:
{"state": "STATE"}
Where
STATE
is the desired state for the key. For example,INACTIVE
.Use
cURL
to call the JSON API with aPUT
hmacKeys request:curl -X PUT --data-binary @JSON_FILE_NAME.json \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/projects/PROJECT_ID/hmacKeys/ACCESS_KEY_ID"
Where:
JSON_FILE_NAME
is the file you created in Step 2.OAUTH2_TOKEN
is the access token you generated in Step 1.PROJECT_ID
is the ID for the project associated with the key you want to update. For example,my-pet-project
.ACCESS_KEY_ID
is the access ID associated with the key you are updating.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the XML API with aPOST
HMAC Key request:curl -X POST \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/?Action=UpdateAccessKey&AccessKeyId=ACCESS_KEY_ID&Status=STATUS"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.ACCESS_KEY_ID
is the access ID associated with the key you are updating.STATUS
is the desired status for the key. For example,Inactive
.
When you change the state of an HMAC key, it takes up to 3 minutes for the state change to propagate through the Cloud Storage system. For this reason, you should wait at least 3 minutes between making an HMAC key inactive and deleting the key.
Deleting an HMAC key
An HMAC key must be in an inactive state in order to delete it. To delete an inactive HMAC key:
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser Click Settings.
Select the Interoperability tab.
Click the name of the service account associated with the key you want to update.
Click the more actions menu (
) associated with the key you want to update.
Select Delete from the drop-down menu.
In the text box that appears, enter the first 10 chracters of the access key ID as they are given in the window.
Click Delete.
gsutil
Use the hmac delete
command:
gsutil hmac delete ACCESS_KEY_ID
Where ACCESS_KEY_ID
is the access ID associated
with the key you are deleting.
If successful, gsutil does not return a response.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the JSON API with aDELETE
hmacKeys request:curl -X DELETE \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/storage/v1/projects/PROJECT_ID/hmacKeys/ACCESS_KEY_ID"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.PROJECT_ID
is the ID for the project associated with the key you want to delete. For example,my-pet-project
.ACCESS_KEY_ID
is the access ID associated with the key you are deleting.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the XML API with aPOST
HMAC Key request:curl -X POST \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/?Action=DeleteAccessKey&AccessKeyId=ACCESS_KEY_ID"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.ACCESS_KEY_ID
is the access ID associated with the key you are deleting.
What's next
- Follow the guidelines for migrating from user account HMAC keys to service account HMAC keys.
- Use an HMAC key in an authenticated request.