En esta página, se tratan las claves del código de autenticación de mensaje basado en hash (HMAC), que puedes usar para autenticar solicitudes en la API de XML de Cloud Storage. Las claves HMAC son útiles cuando deseas mover datos entre otros proveedores de almacenamiento en la nube y Cloud Storage, ya que las claves HMAC te permiten reutilizar tu código existente para acceder a Cloud Storage.
Descripción general
Una clave HMAC es un tipo de credencial asociada con una cuenta, por lo general, una cuenta de servicio. Usa una clave HMAC para crear firmas mediante el algoritmo de firma HMAC-SHA256. Las firmas que crees se incluyen en solicitudes a la API de XML de Cloud Storage. Las firmas muestran que la cuenta asociada con la clave HMAC autoriza una solicitud determinada.
Las claves HMAC constan de dos partes principales, un ID de acceso y un secreto.
ID de acceso: Una string alfanumérica vinculada con una cuenta específica.
Cuando la URL se vincula a una cuenta de servicio, la string tiene 61 caracteres.
Cuando la URL se vincula a una cuenta de usuario, la string tiene 24 caracteres.
A continuación, se muestra un ejemplo de un ID de acceso:
Secreto: Una string codificada en Base 64 de 40 caracteres que está vinculada a un ID de acceso específico. Un secreto es una clave compartida con anterioridad que solo tú y Cloud Storage conocen. Usas tu secreto para crear firmas como parte del proceso de autenticación. A continuación, se muestra un ejemplo de un secreto:
bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ
El ID de acceso y el secreto identifican de manera inequívoca una clave HMAC, pero el secreto cuenta con mucha más información sensible, ya que se usa para crear firmas.
De manera opcional, puedes habilitar la restricción restrictAuthTypes en un recurso, que restringe el acceso de solicitudes firmadas por claves HMAC.
Almacena secretos
Cuando creas una clave HMAC para una cuenta de servicio, se te proporciona el
objeto Secret de la clave una vez. Debes guardar el objeto Secret de forma segura junto con el
ID de acceso relacionado. Si pierdes el secreto, ni tú ni Google Cloudpueden recuperarlo, y debes crear una clave HMAC nueva para que la cuenta de servicio continúe autenticando las solicitudes.
Si deseas crear una clave HMAC para una cuenta de usuario, debes acceder a la consola deGoogle Cloud con la cuenta de usuario y dirigirte a la pestaña Interoperabilidad en el menú Configuración de Cloud Storage de un proyecto en el que tengas el permiso de IAM resourcemanager.projects.get. Una vez creado, puedes ver el objeto Secret de la clave en la pestaña Interoperabilidad de cualquier proyecto para el que tengas el permiso resourcemanager.projects.get.
Prácticas recomendadas para almacenar secretos
No compartas tu secreto de clave HMAC. Debes tratar los secretos de clave HMAC como lo harías con cualquier conjunto de credenciales de acceso.
Como práctica recomendada de seguridad, debes cambiar las claves con regularidad, como parte de una rotación de claves.
Si crees que alguien más usa tus claves HMAC, debes borrar las claves afectadas de inmediato y crear nuevas.
Cuando cambias las claves HMAC, debes actualizar el código con las claves nuevas antes de borrar las antiguas. Cuando borras las claves HMAC, se vuelven no válidas de inmediato y no se pueden recuperar.
Restricciones
Las claves HMAC solo se pueden usar para realizar solicitudes a la API de XML, no a la API de JSON.
Puedes tener un máximo de 10 claves HMAC por cuenta de servicio. Las claves borradas no cuentan en este límite.
Después de la creación, la clave HMAC de una cuenta de servicio puede tardar hasta 60 segundos en usarse. Después de borrar una cuenta de servicio, las claves HMAC que le pertenecen pueden seguir funcionando durante un máximo de 5 minutos. Por el contrario, las claves HMAC pueden tardar hasta 5 minutos en volver a usarse después de recuperar la cuenta de servicio que las posee.
Si habilitas la restricción restrictAuthTypes en un recurso, ya no podrás crear ni activar claves HMAC para el tipo de cuenta especificado en ese recurso.
Migración de claves HMAC de la cuenta de usuario
Por lo general, asociar claves HMAC con cuentas de servicio es una mejor opción que hacerlo con cuentas de usuario, en especial para cargas de trabajo de producción:
Las cuentas de servicio permiten una mejor supervisión administrativa y eliminan las implicaciones de seguridad y privacidad de las cuentas que mantienen los usuarios individuales.
Las cuentas de servicio reducen el riesgo de interrupciones del servicio asociado con depender de cuentas de usuario, como cuando una cuenta de usuario está inhabilitada porque el usuario abandona el proyecto o la empresa.
Si actualmente usas claves HMAC con cuentas de usuario, pero deseas migrar a cuentas de servicio, ten en cuenta lo siguiente:
La cuenta de servicio debe tener los permisos necesarios para realizar acciones en Cloud Storage.
La función Storage Object Admin contiene un permiso general para trabajar con objetos, pero puedes desear tener cuentas de servicio separadas a fin de realizar distintas acciones. Por ejemplo, puedes desear una cuenta de servicio con el propósito de leer, que tendrá la función Storage Object Viewer, y una segunda cuenta de servicio para escribir, que tendrá la función Storage Object Creator.
Debes probar para asegurarte de que la cuenta de servicio se comporte como se esperaba antes de enviar cualquier actualización a producción.
Después de que el trabajo de producción realice la transición a las claves HMAC de la cuenta de servicio, debes verificar la siguiente métrica de Cloud Monitoring para verificar que las claves HMAC asociadas con la cuenta de usuario ya no estén en uso:
Métrica
Descripción
storage.googleapis.com/authn/authentication_count
La cantidad de veces que se usaron las claves HMAC para autenticar solicitudes.
Puedes configurar las siguientes etiquetas para realizar un seguimiento de las claves de las cuentas de usuario que aún se usan durante el proceso de migración:
access_id: Identifica el ID de acceso que realizó la solicitud. También puedes usar access_id durante una rotación de clave para ver cómo el tráfico se traslada de una clave a otra.
authentication_method: Identifica si las claves son de una cuenta de usuario o de servicio.
Una vez que verificaste que las claves HMAC de la cuenta de usuario ya no se usan, debes borrarlas. Hacerlo reduce el riesgo de acceso inapropiado a los datos.
Si la cuenta de usuario ya no se usa para acceder a los recursos de Cloud Storage, revoca cualquier acceso a Cloud Storage que tenga.
[[["Fácil de comprender","easyToUnderstand","thumb-up"],["Resolvió mi problema","solvedMyProblem","thumb-up"],["Otro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Información o código de muestra incorrectos","incorrectInformationOrSampleCode","thumb-down"],["Faltan la información o los ejemplos que necesito","missingTheInformationSamplesINeed","thumb-down"],["Problema de traducción","translationIssue","thumb-down"],["Otro","otherDown","thumb-down"]],["Última actualización: 2025-09-05 (UTC)"],[],[],null,["# HMAC keys\n\n[Setup](/storage/docs/authentication/managing-hmackeys)\n\nThis page discusses hash-based message authentication code (HMAC) keys, which\nyou can use to authenticate requests to the [Cloud Storage XML API](/storage/docs/xml-api/overview). HMAC\nkeys are useful when you want to move data between other cloud storage providers\nand Cloud Storage, because HMAC keys allow you to\n[reuse your existing code](/storage/docs/aws-simple-migration) to access Cloud Storage.\n\nOverview\n--------\n\nAn HMAC key is a type of *credential* associated with an account, typically a\nservice account. You use an HMAC key to create [*signatures*](/storage/docs/authentication/signatures) using the\nHMAC-SHA256 [*signing algorithm*](/storage/docs/authentication/signatures#signing-process). The signatures you create are then\nincluded in requests to the Cloud Storage XML API. Signatures show that\na given request is authorized by the account associated with the HMAC key.\n| **Note:** HMAC keys are separate from the normal service account keys used by Google Cloud, which are RSA keys. HMAC keys cannot be used to generate OAuth 2.0 tokens; however, RSA keys can be used to generate both OAuth 2.0 tokens and Cloud Storage XML API signatures.\n\nHMAC keys have two primary pieces, an *access ID* and a *secret*.\n\n- **Access ID**: An alphanumeric string linked to a specific account.\n\n - When linked to a service account, the string is 61 characters in length.\n\n - When linked to a user account, the string is 24 characters in length.\n\n The following shows an example of an access ID:\n\n `GOOGTS7C7FUP3AIRVJTE2BCDKINBTES3HC2GY5CBFJDCQ2SYHV6A6XXVTJFSA`\n- **Secret**: A 40-character Base-64 encoded string that is linked to a specific\n access ID. A secret is a pre-shared key that only you and\n Cloud Storage know. You use your secret to create signatures as\n part of the authentication process. The following shows an example of a secret:\n\n `bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ`\n\nBoth the access ID and secret uniquely identify an HMAC key, but the secret is\nmuch more sensitive information, because it's used to create signatures.\n\nYou can optionally enable the [`restrictAuthTypes` constraint](/storage/docs/org-policy-constraints#restrict-auth-types) on a\nresource, which restricts access for requests signed by HMAC keys.\n| **Caution:** When you delete an account, any HMAC keys associated with the account are also deleted. To protect against outages, [disable an account](/iam/docs/service-accounts-disable-enable#disabling) and confirm that your traffic is unaffected prior to deleting the account.\n\n### Storing secrets\n\nWhen you [create an HMAC key for a service account](/storage/docs/authentication/managing-hmackeys#create), you are given\nthe secret for the key once. You must securely store the secret, along with the\nassociated *access ID*. If you lose the secret, it cannot be retrieved by you\nor Google Cloud, and you must create a new HMAC key for the service account\nto continue authenticating requests.\n\nTo create an HMAC key for a user account, you must be logged into the\nGoogle Cloud console with the user account and go to the **Interoperability**\ntab in the Cloud Storage **Settings** menu of a project for which you\nhave the `resourcemanager.projects.get` IAM permission. Once\ncreated, you can view the key's secret from the **Interoperability** tab of any\nproject for which you have the `resourcemanager.projects.get` permission.\n\n#### Best practices for storing secrets\n\n- Do not share your HMAC key secret. You should treat HMAC key secrets as you\n would any set of access credentials.\n\n- As a security best practice, you should regularly change your keys as part of\n a key rotation.\n\n- If you think someone else is using your HMAC keys, you should immediately\n delete the affected HMAC keys and create new ones.\n\n- When changing HMAC keys, you should update your code with the new HMAC keys\n before you delete the old keys. When you delete HMAC keys, they become\n immediately invalid, and they are not recoverable.\n\n### Restrictions\n\n- HMAC keys can only be used to make requests to the XML API, not the JSON API.\n\n- You can have a maximum of 10 HMAC keys per service account. Deleted\n keys do not count towards this limit.\n\n- After creation, it can take up to 60 seconds for a service account HMAC key\n to become useable. After [deleting](/iam/docs/service-accounts-delete-undelete) a service account, the HMAC keys\n that belong to it might continue to work for up to 5 minutes. Conversely,\n it can take up to 5 minutes for HMAC keys to become usable again after\n [undeleting](/iam/docs/service-accounts-delete-undelete) the service account that owns them.\n\n- If you enable the `restrictAuthTypes` constraint on a resource, you can no\n longer create or activate HMAC keys for the specified account\n type in that resource.\n\nMigration from user account HMAC keys\n-------------------------------------\n\nGenerally, associating HMAC keys with service accounts are a better option than\ndoing so with user accounts, particularly for production workloads:\n\n- Service accounts allow for better administrative oversight, and they\n eliminate the security and privacy implications of accounts held by\n individual users.\n\n- Service accounts reduce the risk of service outages associated with relying\n on user accounts, such as when a user account is disabled because the user\n leaves the project or company.\n\nIf you currently use HMAC keys with user accounts but want to migrate to\nservice accounts, keep the following in mind:\n\n- Your project must [have a service account](/iam/docs/creating-managing-service-accounts#creating_a_service_account) and [have an HMAC key](/storage/docs/authentication/managing-hmackeys#create)\n associated with it.\n\n- The service account must be granted the [required permissions](/storage/docs/access-control/iam-permissions) to perform\n actions in Cloud Storage.\n\n Broad permission to work with objects is contained in the\n `Storage Object Admin` role, but you may want to have separate service\n accounts for performing different actions. For example, you may want one\n service account for reading, which would have the `Storage Object Viewer`\n role and a second service account for writing, which would have the\n `Storage Object Creator` role.\n- You should test to make certain the service account behaves as expected\n before pushing any update out to production.\n\n- After your production work transitions to service account HMAC keys, you\n should check the following [Cloud Monitoring metric](/monitoring/api/metrics_gcp_p_z#gcp-storage) to verify that\n the HMAC keys associated with the user account are no longer in use:\n\n You can set the following labels to track user account keys that\n are still in use during the migration progress:\n - `access_id`: identifies which access ID made the request. You can also\n use `access_id` during a key rotation to watch traffic move from one key\n to another.\n\n - `authentication_method`: identifies if keys are user account or service\n account keys.\n\n- Once you've verified the user account HMAC keys are no longer used, you\n should delete those HMAC keys. Doing so reduces the risk of inappropriate\n data access.\n\n- If the user account is no longer used to access Cloud Storage\n resources, revoke any access to Cloud Storage that it has.\n\n- You can optionally [enable the `restrictAuthTypes` constraint](/resource-manager/docs/organization-policy/creating-managing-policies#creating_and_editing_policies)\n on user account HMAC keys for an extra layer of security.\n\nWhat's next\n-----------\n\n- [Create HMAC keys for your service accounts](/storage/docs/authentication/managing-hmackeys#create).\n- [Use an HMAC key in an authenticated request](/storage/docs/aws-simple-migration#authentication)."]]
