Setup

This page discusses hash-based message authentication code (HMAC) keys, whichyou can use to authenticate requests to theCloud Storage XML API. HMACkeys are useful when you want to move data between other cloud storage providersand Cloud Storage, because HMAC keys allow you toreuse your existing code to access Cloud Storage.

Overview

An HMAC key is a type ofcredential associated with an account, typically aservice account. You use an HMAC key to createsignatures using theHMAC-SHA256signing algorithm. The signatures you create are thenincluded in requests to the Cloud Storage XML API. Signatures show thata given request is authorized by the account associated with the HMAC key.

Note: HMAC keys are separate from the normal service account keys used byGoogle Cloud, which are RSA keys. HMAC keys cannot be used to generateOAuth 2.0 tokens; however, RSA keys can be used to generate both OAuth 2.0tokens and Cloud Storage XML API signatures.

HMAC keys have two primary pieces, anaccess ID and asecret.

• Access ID: An alphanumeric string linked to a specific account.

  • When linked to a service account, the string is 61 characters in length.

  • When linked to a user account, the string is 24 characters in length.

  The following shows an example of an access ID:

  GOOGTS7C7FUP3AIRVJTE2BCDKINBTES3HC2GY5CBFJDCQ2SYHV6A6XXVTJFSA

• Secret: A 40-character Base-64 encoded string that is linked to a specificaccess ID. A secret is a pre-shared key that only you andCloud Storage know. You use your secret to create signatures aspart of the authentication process. The following shows an example of a secret:

  bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ

Both the access ID and secret uniquely identify an HMAC key, but the secret ismuch more sensitive information, because it's used to create signatures.

You can optionally enable therestrictAuthTypes constraint on aresource, which restricts access for requests signed by HMAC keys.

Caution: When you delete an account, any HMAC keys associated with theaccount are also deleted. To protect against outages,disable an accountand confirm that your traffic is unaffected prior to deleting the account.

Storing secrets

When youcreate an HMAC key for a service account, you are giventhe secret for the key once. You must securely store the secret, along with theassociatedaccess ID. If you lose the secret, it cannot be retrieved by youor Google Cloud, and you must create a new HMAC key for the service accountto continue authenticating requests.

To create an HMAC key for a user account, you must be logged into theGoogle Cloud console with the user account and go to theInteroperabilitytab in the Cloud StorageSettings menu of a project for which youhave theresourcemanager.projects.get IAM permission. Oncecreated, you can view the key's secret from theInteroperability tab of anyproject for which you have theresourcemanager.projects.get permission.

Best practices for storing secrets

• Do not share your HMAC key secret. You should treat HMAC key secrets as youwould any set of access credentials.

• As a security best practice, you should regularly change your keys as part ofa key rotation.

• If you think someone else is using your HMAC keys, you should immediatelydelete the affected HMAC keys and create new ones.

• When changing HMAC keys, you should update your code with the new HMAC keysbefore you delete the old keys. When you delete HMAC keys, they becomeimmediately invalid, and they are not recoverable.

Restrictions

• HMAC keys can only be used to make requests to the XML API, not the JSON API.

• You can have a maximum of 10 HMAC keys per service account. Deletedkeys do not count towards this limit.

• After creation, it can take up to 60 seconds for a service account HMAC keyto become useable. Afterdeleting a service account, the HMAC keysthat belong to it might continue to work for up to 5 minutes. Conversely,it can take up to 5 minutes for HMAC keys to become usable again afterundeleting the service account that owns them.

• If you enable therestrictAuthTypes constraint on a resource, you can nolonger create or activate HMAC keys for the specified accounttype in that resource.

Migration from user account HMAC keys

Generally, associating HMAC keys with service accounts are a better option thandoing so with user accounts, particularly for production workloads:

• Service accounts allow for better administrative oversight, and theyeliminate the security and privacy implications of accounts held byindividual users.

• Service accounts reduce the risk of service outages associated with relyingon user accounts, such as when a user account is disabled because the userleaves the project or company.

If you currently use HMAC keys with user accounts but want to migrate toservice accounts, keep the following in mind:

• Your project musthave a service account andhave an HMAC keyassociated with it.

• The service account must be granted therequired permissions to performactions in Cloud Storage.

  Broad permission to work with objects is contained in theStorage Object Admin role, but you may want to have separate serviceaccounts for performing different actions. For example, you may want oneservice account for reading, which would have theStorage Object Viewerrole and a second service account for writing, which would have theStorage Object Creator role.

• You should test to make certain the service account behaves as expectedbefore pushing any update out to production.

• After your production work transitions to service account HMAC keys, youshould check the followingCloud Monitoring metric to verify thatthe HMAC keys associated with the user account are no longer in use:

  Metric	Description
  storage.googleapis.com/authn/authentication_count	The number of times HMAC keys have been used to authenticate requests.

  You can set the following labels to track user account keys thatare still in use during the migration progress:

  • access_id: identifies which access ID made the request. You can alsouseaccess_id during a key rotation to watch traffic move from one keyto another.

  • authentication_method: identifies if keys are user account or serviceaccount keys.

• Once you've verified the user account HMAC keys are no longer used, youshould delete those HMAC keys. Doing so reduces the risk of inappropriatedata access.

• If the user account is no longer used to access Cloud Storageresources, revoke any access to Cloud Storage that it has.

• You can optionallyenable therestrictAuthTypes constraint on user account HMAC keys for an extra layer of security.

What's next

• Create HMAC keys for your service accounts.
• Use an HMAC key in an authenticated request.