This page shows you how to create, disable and delete Hash-based Message Authentication Code (HMAC) keys associated with service accounts in your project. For general information, see HMAC keys.
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 asroles/storage.hmacKeyAdmin
, 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.
gsutil
Use the hmac create
command, replacing [VALUES_IN_BRACKETS]
with the appropriate values:
gsutil hmac create [SERVICE_ACCOUNT_EMAIL]
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, replacing[VALUES_IN_BRACKETS]
with the appropriate values:curl -X POST \ -H "Authorization: Bearer [OAUTH2_TOKEN]" \ "https://storage.googleapis.com/storage/v1/projects/[PROJECT_ID]/hmacKeys?serviceAccountEmail=[SERVICE_ACCOUNT_EMAIL]"
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=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, replacing[VALUES_IN_BRACKETS]
with the appropriate values:curl -X GET \ -H "Authorization: Bearer [OAUTH2_TOKEN]" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/projects/[PROJECT_ID]/hmacKeys"
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 pencil icon associated with the key you want to update.
Click the more options button (
) associated with the Status of the key.
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, replacing [VALUES_IN_BRACKETS]
with the appropriate values:
gsutil hmac update -s [STATE] [KEY_ACCESS_ID]
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, replacing
[VALUES_IN_BRACKETS]
with the appropriate values:{ "metadata": { "state": [STATE] } }
Use
cURL
to call the JSON API with aPUT
hmacKeys request, replacing[VALUES_IN_BRACKETS]
with the appropriate values: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_ID]"
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=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
.
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 pencil icon associated with the key you want to update.
Click the more options button (
) associated with the Status of the key.
Select Delete from the drop-down menu.
In the text box that appears, enter the access key ID for the HMAC key as it's given in the window.
Click Delete.
gsutil
Use the hmac delete
command, replacing [VALUES_IN_BRACKETS]
with the appropriate values:
gsutil hmac delete [KEY_ACCESS_ID]
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, replacing[VALUES_IN_BRACKETS]
with the appropriate values:curl -X DELETE \ -H "Authorization: Bearer [OAUTH2_TOKEN]" \ "https://storage.googleapis.com/storage/v1/projects/[PROJECT_ID]/hmacKeys/[ACCESS_ID]"
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=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.