Nesta página, explicamos como usar os limites de acesso a credenciais para criar um token de acesso do OAuth 2.0 com permissões reduzidas do Cloud Storage.
O processo para criar um token com permissões de diminuição de escopo inclui as seguintes etapas:
- Conceda os papéis apropriados do IAM a um usuário ou conta de serviço.
- Defina um limite de acesso a credenciais que estabeleça um limite superior para as permissões disponíveis para o usuário ou a conta de serviço.
- Crie um token de acesso do OAuth 2.0 para o usuário ou a conta de serviço.
- Troque o token de acesso do OAuth 2.0 por um novo token que respeite o limite de acesso a credenciais.
Em seguida, você pode usar o novo token de acesso do OAuth 2.0 com escopo reduzido para autenticar solicitações para o Cloud Storage.
Antes de começar
Antes de usar limites de acesso a credenciais, certifique-se de que você atende aos seguintes requisitos:
Você precisa diminuir o escopo de permissões apenas para o Cloud Storage, não para outros Google Cloud serviços.
Se você precisar diminuir o escopo de permissões para outros serviços do Google Cloud, crie várias contas de serviço e conceda um conjunto diferente de funções a cada conta de serviço.
Você consegue usar tokens de acesso do OAuth 2.0 para autenticação. Outros tipos de credenciais de curta duração não são compatíveis com os limites de acesso a credenciais.
Além disso, você precisa ativar as APIs necessárias:
-
Enable the IAM and Security Token Service APIs.
Conceder papéis do IAM
Um limite de acesso a credenciais configura um limite superior para as permissões disponíveis para um recurso. Ele consegue tirar permissões de um principal, mas não consegue adicionar permissões que o principal ainda não tenha.
Dessa maneira, também é necessário conceder ao principal papéis que garantam as permissões de que ele precisa, seja em um intervalo do Cloud Storage, seja em um recurso de nível superior, como o projeto.
Por exemplo, suponha que você precise criar uma credencial de curta duração com escopo diminuído que permita que uma conta de serviço crie objetos em um bucket:
- No mínimo, é necessário conceder um papel à conta de serviço que inclua a permissão
storage.objects.create
, como o papel Criador de objetos do Storage (roles/storage.objectCreator
). Também é necessário que o limite de acesso a credenciais inclua essa permissão. - Também é possível conceder um papel que inclua mais permissões, como o de Administrador de objetos do Storage (
roles/storage.objectAdmin
). A conta de serviço poderá usar apenas as permissões que aparecem na concessão do papel e no limite de acesso a credenciais.
Consulte Papéis do Cloud Storage para saber mais.
Definir o limite de acesso a credenciais
Um limite de acesso a credenciais é um objeto que contém uma lista de regras de limite de acesso. As regras são compostas por parâmetros que especificam o limite superior das permissões disponíveis para o usuário ou a conta de serviço. Para definir um limite de acesso a credenciais, crie um objeto JSON que liste as regras de limite de acesso e os parâmetros delas.
Confira um exemplo de limite de acesso a credenciais:
{
"accessBoundary": {
"accessBoundaryRules": [
{
"availablePermissions": [
"inRole:ROLE_ID"
],
"availableResource": "//storage.googleapis.com/projects/_/buckets/BUCKET_NAME"
"availabilityCondition": {
"expression" : "CONDITION"
}
]
}
}
Substitua:
ROLE_ID
: o ID de uma função predefinida ou personalizada que define o limite máximo das permissões disponíveis para o recurso. Por exemplo,roles/storage.objectViewer
. Para especificar várias funções, adicione uma nova linha com um prefixoinRole:
seguido pelo ID da função. Somente as permissões nos papéis especificados estarão disponíveis.BUCKET_NAME
: o nome do bucket do Cloud Storage a que a regra se aplica.CONDITION
: opcional. Uma expressão de condição que especifica os objetos do Cloud Storage em que as permissões estão disponíveis. Por exemplo, a condição a seguir disponibiliza permissões para objetos cujo nome começa comcustomer-a
:resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a')
Para saber mais sobre como criar e personalizar limites de acesso para credenciais, consulte Componentes de um limite de acesso para credenciais.
Para exemplos de possíveis casos de uso de limites de acesso a credenciais, consulte Exemplos de limites de acesso a credenciais.
Criar um token de acesso do OAuth 2.0
Antes de criar uma credencial de curta duração com escopo diminuído, é necessário criar um token de acesso normal do OAuth 2.0. Em seguida, será possível trocar a credencial normal por uma credencial com escopo diminuído. Ao criar o token de acesso, use o escopo https://www.googleapis.com/auth/cloud-platform
do OAuth 2.0.
Para criar um token de acesso para uma conta de serviço, conclua o fluxo do OAuth 2.0 de servidor para servidor ou use a API Service Account Credentials para gerar um token de acesso do OAuth 2.0.
Para criar um token de acesso para um usuário, consulte Como receber tokens de acesso do OAuth 2.0. Também é possível usar o OAuth 2.0 Playground para criar um token de acesso para sua própria Conta do Google.
Trocar o token de acesso do OAuth 2.0
Depois de criar um token de acesso do OAuth 2.0, é possível trocá-lo por um token com escopo diminuído que respeite o limite de acesso a credenciais. Esse processo normalmente envolve um agente de tokens e um consumidor de token:
O agente de tokens é responsável por definir o limite de acesso a credenciais e trocar um token de acesso por um token com escopo diminuído.
O agente de token pode usar uma biblioteca de autenticação compatível para trocar tokens de acesso automaticamente ou pode chamar o Security Token Service para trocar tokens manualmente.
O consumidor de token solicita um token de acesso com escopo diminuído do agente de token e, em seguida, usa o token de acesso com escopo diminuído para executar outra ação.
O consumidor de token pode usar uma biblioteca de autenticação compatível para atualizar automaticamente os tokens de acesso antes que eles expirem. Como alternativa, é possível atualizar tokens manualmente ou permitir que os tokens expirem sem atualizá-los.
Há duas maneiras de trocar o token de acesso por um token com escopo reduzido:
Troca de token do lado do cliente (recomendada): os clientes recebem materiais criptográficos do servidor da API Security Token Service. Os materiais criptográficos permitem que os clientes gerem tokens com escopo reduzido com várias regras de limite de acesso a credenciais de forma independente no lado do cliente por um período definido (por exemplo, uma hora). Essa abordagem reduz a latência e melhora a eficiência, especialmente para clientes que exigem atualizações frequentes das regras de limite de acesso às credenciais. Também é mais eficiente para aplicativos que precisam gerar muitos tokens exclusivos com escopo reduzido. Essa é a abordagem recomendada porque oferece melhor desempenho, escalonabilidade e compatibilidade com recursos futuros.
Troca de token do lado do servidor: os clientes solicitam um novo token com escopo reduzido do servidor da API Security Token Service sempre que uma regra de limite de acesso a credenciais muda. Essa abordagem é simples, mas exige uma ida e volta ao servidor da API Security Token Service para cada solicitação de token com escopo reduzido. Essa abordagem é recomendada apenas para clientes que precisam de uma biblioteca de cliente que não ofereça suporte à troca de tokens do lado do cliente, devido à ida e volta para a API Security Token Service em cada solicitação de token com escopo reduzido.
Troca de token do lado do cliente
Se você criar o agente e o consumidor de token com a seguinte linguagem, poderá usar a biblioteca de autenticação do Google para trocar e atualizar tokens automaticamente usando a abordagem do lado do cliente.
Java
Para Java, é possível trocar e atualizar tokens automaticamente com a versão 1.32.1
ou mais recente do
artefato com.google.auth:google-auth-library-cab-token-generator
.
Para verificar a versão do artefato, execute o seguinte comando do Maven no diretório do aplicativo:
mvn dependency:list -DincludeArtifactIds=google-auth-library-cab-token-generator
O exemplo a seguir mostra como um agente de token pode gerar tokens com escopo diminuído:
O exemplo a seguir mostra como um consumidor de token pode usar um gerenciador de atualização para receber e atualizar automaticamente tokens com escopo diminuído:
Troca de token do lado do servidor
Esta seção descreve os seguintes métodos que podem ser usados para trocar tokens pela abordagem do lado do serviço:
- Trocar e atualizar o token de acesso automaticamente
- Trocar e atualizar o token de acesso manualmente
Trocar e atualizar o token de acesso automaticamente usando a abordagem do lado do servidor
Se você criar o agente e o consumidor de token com uma das seguintes linguagens, poderá usar a biblioteca de autenticação do Google para trocar e atualizar tokens automaticamente usando a abordagem de geração de token do lado do servidor:
Go
Para o Go, é possível trocar e atualizar tokens automaticamente com a versão
v0.0.0-20210819190943-2bc19b11175f ou posterior do
pacote golang.org/x/oauth2
.
Para verificar a versão do pacote, execute o seguinte comando no diretório do aplicativo:
go list -m golang.org/x/oauth2
O exemplo a seguir mostra como um agente de token pode gerar tokens com escopo diminuído:
O exemplo a seguir mostra como um consumidor de token pode usar um gerenciador de atualização para receber e atualizar automaticamente tokens com escopo diminuído:
Java
Para Java, é possível trocar e atualizar tokens automaticamente com a versão 1.1.0
ou mais recente do
artefato com.google.auth:google-auth-library-oauth2-http
.
Para verificar a versão do artefato, execute o seguinte comando do Maven no diretório do aplicativo:
mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
O exemplo a seguir mostra como um agente de token pode gerar tokens com escopo diminuído:
O exemplo a seguir mostra como um consumidor de token pode usar um gerenciador de atualização para receber e atualizar automaticamente tokens com escopo diminuído:
Node.js
Para Node.js, é possível trocar e atualizar tokens automaticamente com a versão
7.9.0 ou posterior do pacote google-auth-library
.
Para verificar a versão do pacote, execute o seguinte comando no diretório do aplicativo:
npm list google-auth-library
O exemplo a seguir mostra como um agente de token pode gerar tokens com escopo diminuído:
O exemplo a seguir mostra como um consumidor de token pode fornecer um gerenciador de atualização que automaticamente recebe e atualiza tokens com escopo diminuído:
Python
Para o Python, é possível trocar e atualizar tokens automaticamente com a versão 2.0.0 ou posterior do pacote google-auth
.
Para verificar a versão do pacote, execute o seguinte comando no ambiente em que ele está instalado:
pip show google-auth
O exemplo a seguir mostra como um agente de token pode gerar tokens com escopo diminuído:
O exemplo a seguir mostra como um consumidor de token pode fornecer um gerenciador de atualização que automaticamente recebe e atualiza tokens com escopo diminuído:
Trocar e atualizar o token de acesso manualmente
Um agente de token pode usar a API Security Token Service para trocar um token de acesso por um token de acesso com escopo diminuído. Em seguida, ele pode fornecer o token com escopo diminuído a um consumidor de token.
Para trocar o token de acesso, use o método HTTP e URL a seguir:
POST https://sts.googleapis.com/v1/token
Defina o cabeçalho Content-Type
na solicitação como
application/x-www-form-urlencoded
. Inclua os seguintes campos no corpo
da solicitação:
Campos | |
---|---|
grant_type |
Use o valor |
options |
Um limite de acesso a credenciais no formato JSON, codificado com codificação percentual. |
requested_token_type |
Use o valor |
subject_token |
O token de acesso do OAuth 2.0 que você quer trocar. |
subject_token_type |
Use o valor |
A resposta é um objeto JSON que contém os seguintes campos:
Campos | |
---|---|
access_token |
Um token de acesso do OAuth 2.0 com escopo diminuído que respeita o limite de acesso a credenciais. |
expires_in |
O tempo até o token com escopo diminuído expirar, em segundos. Esse campo só será incluído se o token de acesso original representar uma conta de serviço. Se esse campo não for incluído, o token com escopo reduzido terá o mesmo tempo de validade do token de acesso original. |
issued_token_type |
Contém o valor |
token_type |
Contém o valor |
Por exemplo, se um limite de acesso a credenciais no formato JSON estiver armazenado no arquivo ./access-boundary.json
, use o comando curl
a seguir para trocar o token de acesso. Substitua original-token
pelo token de acesso original:
curl -H "Content-Type:application/x-www-form-urlencoded" \ -X POST \ https://sts.googleapis.com/v1/token \ -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange&subject_token_type=urn:ietf:params:oauth:token-type:access_token&requested_token_type=urn:ietf:params:oauth:token-type:access_token&subject_token=original-token" \ --data-urlencode "options=$(cat ./access-boundary.json)"
A resposta será semelhante ao seguinte exemplo:
{
"access_token": "ya29.dr.AbCDeFg-123456...",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 3600
}
Quando um consumidor de token solicita um token com escopo diminuído, o agente de token responde com o token com escopo diminuído e o número de segundos até que ele expire. Se o token tiver expirado, o servidor vai rejeitar a solicitação. Para atualizar o token com escopo diminuído, o consumidor pode solicitar um token com escopo reduzido do agente antes que o token atual expire.
A seguir
- Saiba mais sobre o controle de acesso para Cloud Storage.
- Crie uma credencial de conta de serviço de curta duração.
- Crie um token de acesso do OAuth 2.0 para uma conta de serviço usando um dos seguintes métodos:
- Crie um token de acesso do OAuth 2.0 para um usuário.
- Consulte as permissões em cada papel predefinido.
- Saiba mais sobre papéis personalizados.