Nesta página, você encontrará informações sobre as chaves de código de autenticação de mensagem baseado em hash (HMAC, na sigla em inglês), que
podem ser usadas para autenticar solicitações para a API Cloud Storage XML. As chaves HMAC são úteis
quando você quer mover dados entre outros provedores de armazenamento em nuvem e o Cloud Storage. As chaves HMAC permitem reutilizar seu código existente para acessar o Cloud Storage.
Visão geral
Uma chave HMAC é um tipo de credencial associada a uma conta, normalmente uma
conta de serviço. Use uma chave HMAC para criar assinaturas usando o
algoritmo de assinatura HMAC-SHA256. As assinaturas criadas são incluídas
nas solicitações para a API XML do Cloud Storage. As assinaturas mostram que uma determinada solicitação foi autorizada pela conta associada à chave HMAC.
As chaves HMAC têm dois componentes principais: um ID de acesso e uma chave secreta.
ID de acesso: uma string alfanumérica vinculada a uma conta específica.
Quando vinculada a uma conta de serviço, a string tem 61 caracteres.
Quando vinculada a uma conta de usuário, a string tem 24 caracteres.
Secret: uma string codificada com Base-64 de 40 caracteres vinculada a um ID de acesso
específico. Trata-se de uma chave pré-compartilhada que apenas você e o
Cloud Storage conhecem. Você usa seu secret para criar assinaturas como
parte do processo de autenticação. Veja a seguir um exemplo de secret:
bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ
Tanto o ID de acesso quanto a chave secreta identificam uma chave HMAC de modo único. No entanto, o secret é
uma informação extremamente confidencial porque é usada para criar assinaturas.
Também é possível ativar a restrição restrictAuthTypes em um recurso, o que restringe o acesso a solicitações assinadas por chaves HMAC.
Como armazenar chaves secretas
Ao criar uma chave HMAC para uma conta de serviço, você recebe uma chave secreta
apenas uma vez. É necessário armazená-la em segurança, junto com o respectivo ID de acesso. Se você perder o secret, ele não poderá ser recuperado por você
ou pelo Google Cloud, e você precisará criar uma nova chave HMAC para a conta de serviço
para continuar a autenticar solicitações.
Para criar uma chave HMAC para uma conta de usuário, faça login no
consoleGoogle Cloud com a conta de usuário e acesse a guia Interoperabilidade
no menu Configurações do Cloud Storage de um projeto em que você
tem a permissão do IAM resourcemanager.projects.get. Depois de
criado, é possível visualizar o secret da chave na guia Interoperabilidade de qualquer
projeto em que você tenha a permissão resourcemanager.projects.get.
Práticas recomendadas para armazenar secrets
Não compartilhe o secret da sua chave HMAC. Trate os secrets da chave HMAC como faria
com qualquer conjunto de credenciais de acesso.
Como prática de segurança recomendada, altere regularmente suas chaves como parte do processo de rotação de chaves.
Se você acha que outra pessoa está usando suas chaves HMAC, exclua
imediatamente as chaves HMAC afetadas e crie novas.
Quando você alterar suas chaves HMAC, atualize o código com as chaves novas antes de excluir as antigas. Depois de excluídas, as chaves HMAC se tornam
inválidas imediatamente e não podem ser recuperadas.
Restrições
As chaves HMAC podem ser usadas para fazer solicitações à API XML, mas não à API JSON.
Cada conta de serviço pode ter no máximo 10 chaves HMAC. As chaves excluídas não contam nesse limite.
Após a criação, pode levar até 60 segundos para uma chave HMAC da conta de serviço
ficar utilizável. Depois de excluir uma conta de serviço, as chaves HMAC
que pertencem a ela podem continuar funcionando por até cinco minutos. Por outro lado,
pode levar até cinco minutos para que as chaves HMAC se tornem utilizáveis novamente após
cancelar a exclusão da conta de serviço proprietária delas.
Se a restrição restrictAuthTypes for ativada em um recurso, não será mais
possível criar ou ativar chaves HMAC para o tipo
de conta especificado nesse recurso.
Migração das chaves HMAC de conta de usuário para contas de serviço
Em geral, associar chaves HMAC a contas de serviço é uma opção melhor do que associá-las a contas de usuário, principalmente no caso das cargas de trabalho em produção:
As contas de serviço proporcionam uma melhor supervisão administrativa porque elas não têm as mesmas restrições de privacidade e segurança das contas pertencentes a usuários individuais.
As contas de serviço reduzem o risco de interrupções no serviço devido à dependência em contas de usuário como, por exemplo, quando uma conta de usuário é desativada porque a pessoa não faz mais parte do projeto ou da empresa.
Se você atualmente usa chaves HMAC com contas de usuário, mas quer migrar para contas de serviço, lembre-se das seguintes orientações:
A conta de serviço precisa receber as permissões necessárias para realizar ações no Cloud Storage.
A permissão mais abrangente para trabalhar com objetos está no papel Storage Object Admin, mas convém ter contas de serviço separadas para executar ações diferentes. Por exemplo, é recomendável ter uma conta de serviço para leitura com o papel Storage Object Viewer e uma segunda conta de serviço para gravação com o papel Storage Object Creator.
Faça testes para ter certeza de que a conta de serviço está se comportando conforme o esperado antes de enviar qualquer atualização para a produção.
Depois que o trabalho de produção fizer a transição para as chaves HMAC da conta de serviço, verifique
a seguinte métrica do Cloud Monitoring para verificar se
as chaves HMAC associadas à conta de usuário não estão mais em uso:
Métrica
Descrição
storage.googleapis.com/authn/authentication_count
O número de vezes que chaves HMAC foram usadas para autenticar solicitações.
É possível definir os seguintes rótulos para rastrear chaves de contas de usuário que ainda estão em uso durante o andamento da migração:
access_id: identifica qual código de acesso fez a solicitação. Use access_id
durante uma rotação de chaves para acompanhar o tráfego de uma chave
para outra.
authentication_method: identifica se as chaves são de contas de usuário ou de serviço.
Exclua as chaves HMAC de conta de usuário depois de verificar que elas não estão mais em uso. Essa ação reduz o risco de acessos indevidos aos dados.
Se a conta de usuário não estiver mais sendo usada para acessar os recursos do Cloud Storage, revogue todos os acessos que ela tem ao produto.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-18 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)."]]
