Managing HMAC keys for service accounts

ベータ版です。

このプロダクトまたは機能はプレリリース版の状態であり、変更されたりサポートが制限されたりする可能性があります。詳細については、プロダクトのリリース ステージをご覧ください。

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:

1. 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 roles/storage.hmacKeyAdmin, that has these permissions.

2. 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

Important: When you create an HMAC key, you are given the secret for that key, which you must store securely. If you lose the secret, you are no longer able to use the HMAC key to authorize requests.

To create an HMAC key for a service account:

Console

1. Open the Cloud Storage browser in the Google Cloud Platform Console.
   Open the Cloud Storage browser

2. Click Settings.

3. Select the Interoperability tab.

4. Click + Create a key for a service account.

5. Select the service account you want the HMAC key to be associated with.

6. 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

REST APIs

JSON API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Use cURL to call the JSON API with a POST hmacKeys request, replacing [VALUES_IN_BRACKETS] with the appropriate values:

   curl -X POST \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     "https://www.googleapis.com/storage/v1/projects/[PROJECT_ID]/hmacKeys?serviceAccountEmail=[SERVICE_ACCOUNT_EMAIL]"

XML API

The XML API cannot be used to create HMAC keys. Use one of the other Cloud Storage tools, such as gsutil, instead.

Getting HMAC key information

To list the HMAC keys for a project, and get information about the keys:

Console

1. Open the Cloud Storage browser in the Google Cloud Platform Console.
   Open the Cloud Storage browser

2. Click Settings.

3. Select the Interoperability tab.

gsutil

1. 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.

2. 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.

REST APIs

JSON API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Use cURL to call the JSON API with a LIST hmacKeys request, replacing [VALUES_IN_BRACKETS] with the appropriate values:

   curl -X GET \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     -H "Content-Type: application/json" \
     "https://www.googleapis.com/storage/v1/projects/[PROJECT_ID]/hmacKeys"

XML API

The XML API cannot be used to get or list HMAC keys. Use one of the other Cloud Storage tools, such as gsutil, instead.

Updating the state of an HMAC key

To switch an HMAC key between being active and inactive:

Console

1. Open the Cloud Storage browser in the Google Cloud Platform Console.
   Open the Cloud Storage browser

2. Click Settings.

3. Select the Interoperability tab.

4. Click the pencil icon associated with the key you want to update.

5. Click the more options button () associated with the Status of the key.

6. Select the state you want to apply to the key.

7. 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.

REST APIs

JSON API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create a .json file that contains the following information, replacing [VALUES_IN_BRACKETS] with the appropriate values:

   {
     "metadata": {
         "state": [STATE]
     }
   }

3. Use cURL to call the JSON API with a PUT 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://www.googleapis.com/storage/v1/projects/[PROJECT_ID]/hmacKeys/[ACCESS_ID]"

XML API

The XML API cannot be used to update HMAC keys. Use one of the other Cloud Storage tools, such as gsutil, instead.

Deleting an HMAC key

Caution: HMAC keys cannot be recovered once you delete them. If you want to keep an HMAC key but prevent it from being used, set its state to INACTIVE.

An HMAC key must be in an inactive state in order to delete it. To delete an inactive HMAC key:

Console

1. Open the Cloud Storage browser in the Google Cloud Platform Console.
   Open the Cloud Storage browser

2. Click Settings.

3. Select the Interoperability tab.

4. Click the pencil icon associated with the key you want to update.

5. Click the more options button () associated with the Status of the key.

6. Select Delete from the drop-down menu.

7. In the text box that appears, enter the access key ID for the HMAC key as it's given in the window.

8. 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.

REST APIs

JSON API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Use cURL to call the JSON API with a DELETE hmacKeys request, replacing [VALUES_IN_BRACKETS] with the appropriate values:

   curl -X DELETE \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     "https://www.googleapis.com/storage/v1/projects/[PROJECT_ID]/hmacKeys/[ACCESS_ID]"

XML API

The XML API cannot be used to delete HMAC keys. Use one of the other Cloud Storage tools, such as gsutil, instead.

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.