Nesta página, explicamos como criar credenciais de curta duração para uma conta de serviço com base em uma cadeia de delegação de contas de serviço. Use essa abordagem quando precisar emitir uma série de chamadas de geração de token para receber um token com as permissões necessárias para realizar sua tarefa.
Depois de receber uma credencial de curta duração, use-a para representar a conta de serviço.
Se for possível gerar um token com as permissões necessárias com uma única chamada de geração de token, crie credenciais de curta duração para essa conta de serviço diretamente.
Sobre a criação de credenciais de curta duração
Dependendo do tipo de token criado, é possível usar credenciais de curta duração para autenticar chamadas para APIs do Google, APIs de terceiros ou aplicativos que exigem tokens de ID. As credenciais de curta duração têm uma vida útil limitada, com durações de apenas algumas horas ou menos, e não são atualizadas automaticamente. As credenciais de curta duração para contas de serviço são úteis quando você precisa atribuir acesso limitado a recursos para contas de serviço confiáveis. Elas também oferecem menos risco do que as credenciais de longa duração, como as chaves de conta de serviço.
É possível criar os seguintes tipos de credenciais de curta duração para uma conta de serviço:
Tokens de acesso do OAuth 2.0
Os tokens de acesso são aceitos para autenticação pela maioria das APIs do Google. Quando você gera um token de acesso para uma conta de serviço, o token de acesso vem sem o token de atualização. Isso significa que, quando o token expirar, será necessário repetir o processo de criação do token para gerar um novo.
Para mais informações, consulte Tokens de acesso.
Tokens de ID do OpenID Connect (OIDC)
Os tokens de ID seguem a especificação OpenID Connect (OIDC). Os tokens de ID são aceitos por um número limitado de serviços e aplicativos.
Para mais informações, consulte Tokens de ID e Autenticação para aplicativos hospedados no Cloud Run ou Cloud Functions.
JSON Web Tokens (JWTs) autoassinados
É possível usar JWTs autoassinados para autenticar algumas APIs do Google sem receber um token de acesso do servidor de autorização. As APIs implantadas com o gateway de API exigem isso.
Blobs binários autoassinados
Os blobs autoassinados são úteis em cenários em que você precisa transmitir com segurança dados binários arbitrários, geralmente para fins de autenticação.
Fluxo de solicitação delegada
Com o fluxo de solicitações delegadas, você pode encadear solicitações diretas usando uma única solicitação, em vez de precisar fazer várias solicitações diretas em sequência. Nesse fluxo, a solicitação de uma credencial de conta de serviço é delegada a uma ou mais contas de serviço em uma cadeia de delegação antes de gerar uma credencial para a conta de serviço final. A credencial resultante representa apenas a conta de serviço final, não as contas de serviço intermediárias na cadeia de delegação.
Cada conta de serviço na cadeia de delegação precisa ter as permissões necessárias na próxima conta de serviço na cadeia para que possa transmitir a solicitação.
Se uma conta de serviço fornecer todas as permissões necessárias, use o fluxo mais simples descrito em Criar credenciais de curta duração de uma conta de serviço.
Antes de começar
Enable the IAM and Service Account Credentials APIs.
Entenda as contas de serviço do IAM
Se ainda não tiver feito isto, ative o faturamento e a API IAM seguindo as etapas no guia de início rápido.
Identifique as contas de serviço que você usará na cadeia de delegação.
É possível criar uma nova conta de serviço e incluí-la na cadeia de delegação, se necessário.
Fornecer as permissões necessárias
Uma solicitação delegada envolve mais de duas identidades: o autor da chamada, uma ou mais contas de serviço em uma cadeia de delegação e, finalmente, a conta de serviço para a qual a credencial é criada. Nesse fluxo, pense nas seguintes identidades:
- Conta de serviço 1 (
SA_1
), o autor da chamada que emite a solicitação para as credenciais de curta duração. - Conta de serviço 2 (
SA_2
), uma conta de serviço intermediária que vai delegar a solicitação inicial aSA_3
. Essa conta apenas transmite a solicitação. Ela não concede aSA_1
ouSA_3
nenhum acesso adicional. - Conta de serviço 3 (
SA_3
), a conta com privilégios limitados para a qual a credencial é criada.
Para permitir a delegação, cada conta precisa conceder o papel Criador do token da conta de serviço (roles/iam.serviceAccountTokenCreator
) à conta anterior na cadeia.
Neste exemplo específico, é necessário atribuir a SA_1
o papel de "Criador de token da conta de serviço" (roles/iam.serviceAccountTokenCreator
) em SA_2
. Este
é um exemplo da conta de serviço SA_2
que está sendo tratada
como um recurso: quando você concede o papel em SA_2
, você
atualiza a política do IAM da mesma maneira que atualizaria qualquer outro recurso.
Nesse fluxo de exemplo, há apenas uma conta de serviço intermediária. Para delegar acesso por mais de uma conta de serviço, você também precisa atribuir esse papel a qualquer outra conta de serviço na cadeia.
Em seguida, SA_2
também precisa receber o papel "Criador de token da conta de serviço" (roles/iam.serviceAccountTokenCreator
) em SA_3
. Isso permite que SA_2
crie credenciais de curta duração para SA_3
.
As etapas a seguir usam a API REST para conceder os papéis. No entanto, também é possível usar o Console do Google Cloud ou a CLI gcloud.
API
Primeiro, veja a política do IAM para
SA_2
(a conta de serviço intermediária):
O método
serviceAccounts.getIamPolicy
recebe a política de permissão de uma conta de serviço.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_ID
: o ID do projeto do Google Cloud. Os IDs do projeto são strings alfanuméricas, comomy-project
.SA_2
: o nome da conta de serviço 2.POLICY_VERSION
: a versão da política a ser retornada. As solicitações precisam especificar a versão mais recente da política, que é a versão 3 da política. Para saber mais detalhes, consulte Como especificar uma versão da política ao receber uma política.
Método HTTP e URL:
POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_2@PROJECT_ID.iam.gserviceaccount.com:getIamPolicy
Corpo JSON da solicitação:
{ "options": { "requestedPolicyVersion": POLICY_VERSION } }
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
{ "version": 1, "etag": "BwWKmjvelug=", "bindings": [ { "role": "roles/serviceAccountAdmin", "members": [ "user:admin@example.com" ] } ] }
Se você não tiver concedido um papel à conta de serviço, a resposta
conterá apenas um valor etag
. Inclua esse valor etag
na próxima etapa.
Em seguida, modifique a política para atribuir a SA_1
o
papel "Criador de token da conta de serviço"
(roles/iam.serviceAccountTokenCreator
).
Por exemplo, para modificar a resposta de amostra da etapa anterior, adicione o seguinte:
{ "version": 1, "etag": "BwWKmjvelug=", "bindings": [ { "role": "roles/serviceAccountAdmin", "members": [ "user:admin@example.com" ] }, { "role": "roles/iam.serviceAccountTokenCreator", "members": [ "serviceAccount:SA_1@PROJECT_ID.iam.gserviceaccount.com" ] } ] }
Depois, escreva a política de permissão atualizada para SA_2
:
O método
serviceAccounts.setIamPolicy
define uma política de permissão atualizada para a conta de serviço.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_ID
: o ID do projeto do Google Cloud. Os IDs do projeto são strings alfanuméricas, comomy-project
.SA_2
: o nome da conta de serviço 2.-
POLICY
: uma representação JSON da política que você quer definir. Para mais informações sobre o formato de uma política, consulte a referência da política.Por exemplo, para definir a política de permissão mostrada na etapa anterior, substitua
POLICY
pelo seguinte:{ "version": 1, "etag": "BwWKmjvelug=", "bindings": [ { "role": "roles/serviceAccountAdmin", "members": [ "user:admin@example.com" ] }, { "role": "roles/iam.serviceAccountTokenCreator", "members": [ "serviceAccount:SA_1@PROJECT_ID.iam.gserviceaccount.com" ] } ] }
Método HTTP e URL:
POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_2@PROJECT_ID.iam.gserviceaccount.com:setIamPolicy
Corpo JSON da solicitação:
{ "policy": POLICY }
Para enviar a solicitação, expanda uma destas opções:
A resposta contém a política de permissão atualizada.
Agora, veja a política do IAM para SA_3
(a conta de serviço para quem a credencial é criada):
O método
serviceAccounts.getIamPolicy
recebe a política de permissão de uma conta de serviço.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_ID
: o ID do projeto do Google Cloud. Os IDs do projeto são strings alfanuméricas, comomy-project
.SA_3
: o nome da conta de serviço 3.POLICY_VERSION
: a versão da política a ser retornada. As solicitações precisam especificar a versão mais recente da política, que é a versão 3 da política. Para saber mais detalhes, consulte Como especificar uma versão da política ao receber uma política.
Método HTTP e URL:
POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_3@PROJECT_ID.iam.gserviceaccount.com:getIamPolicy
Corpo JSON da solicitação:
{ "options": { "requestedPolicyVersion": POLICY_VERSION } }
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
{ "version": 1, "etag": "BwWKmjvelug=", "bindings": [ { "role": "roles/serviceAccountAdmin", "members": [ "user:admin@example.com" ] } ] }
Se você não atribuiu um papel à conta de serviço, a resposta conterá
apenas um valor etag
. Inclua esse valor etag
na próxima etapa.
Em seguida, modifique a política para atribuir a SA_2
o
papel "Criador de token da conta de serviço"
(roles/iam.serviceAccountTokenCreator
).
Por exemplo, para modificar a resposta de amostra da etapa anterior, adicione o seguinte:
{ "version": 1, "etag": "BwWKmjvelug=", "bindings": [ { "role": "roles/serviceAccountAdmin", "members": [ "user:admin@example.com" ] }, { "role": "roles/iam.serviceAccountTokenCreator", "members": [ "serviceAccount:SA_2@PROJECT_ID.iam.gserviceaccount.com" ] } ] }
Por fim, escreva a política de permissão atualizada:
O método
serviceAccounts.setIamPolicy
define uma política de permissão atualizada para a conta de serviço.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
PROJECT_ID
: o ID do projeto do Google Cloud. Os IDs do projeto são strings alfanuméricas, comomy-project
.SA_3
: o nome da conta de serviço 3.-
POLICY
: uma representação JSON da política que você quer definir. Para mais informações sobre o formato de uma política, consulte a referência da política.Por exemplo, para definir a política de permissão mostrada na etapa anterior, substitua
POLICY
pelo seguinte:{ "version": 1, "etag": "BwWKmjvelug=", "bindings": [ { "role": "roles/serviceAccountAdmin", "members": [ "user:admin@example.com" ] }, { "role": "roles/iam.serviceAccountTokenCreator", "members": [ "serviceAccount:SA_2@PROJECT_ID.iam.gserviceaccount.com" ] } ] }
Método HTTP e URL:
POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_3@PROJECT_ID.iam.gserviceaccount.com:setIamPolicy
Corpo JSON da solicitação:
{ "policy": POLICY }
Para enviar a solicitação, expanda uma destas opções:
A resposta contém a política de permissão atualizada.
Solicitar credenciais de curta duração
Depois de conceder os papéis apropriados a cada identidade, solicite credenciais de curta duração para a conta de serviço pretendida. Os seguintes tipos de credenciais são aceitos:
- Tokens de acesso do OAuth 2.0
- Tokens de ID do OpenID Connect
- JSON Web Tokens (JWTs, na sigla em inglês) autoassinados
- Objetos binários (blobs) autoassinados
Para entender como especificar uma cadeia de delegação para essas solicitações, consulte a seção Como especificar uma cadeia de delegação nesta página.
Gerar um token de acesso do OAuth 2.0
Por padrão, os tokens de acesso do OAuth 2.0 são válidos por no máximo uma hora
(3.600 segundos). No entanto, é
possível estender o ciclo de vida máximo desses tokens para
12 horas
(43.200 segundos). Para fazer isso, identifique as contas de serviço
que precisam de um ciclo de vida estendido para tokens e
adicione essas contas de serviço a uma política da organização
que inclua a
restrição de lista constraints/iam.allowServiceAccountCredentialLifetimeExtension
. É possível especificar um ciclo de vida de até
43.200 segundos ao criar um token para essas
contas de serviço.
Para gerar um token de acesso do OAuth 2.0 para uma conta de serviço, faça o seguinte:
API
O método serviceAccounts.generateAccessToken
da API Service Account Credentials
gera
um token de acesso do OAuth 2.0 para uma conta de serviço.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
SA_NAME
: o nome da conta de serviço para a qual você quer criar um token.PROJECT_ID
: o ID do projeto do Google Cloud. Os IDs do projeto são strings alfanuméricas, comomy-project
.DELEGATES
: se você estiver usando um fluxo de solicitação delegada, consulte Como especificar uma cadeia de delegação nesta página. Se você estiver usando um fluxo de solicitação direta sem delegação, omita o campodelegates
no corpo da solicitação.-
LIFETIME
: o tempo até o token de acesso expirar, em segundos. Por exemplo,300s
.Por padrão, o ciclo de vida máximo do token é de uma hora (3,600 segundos). Para aumentar o ciclo de vida máximo desses tokens para 12 horas (43.200 segundos), adicione a conta de serviço a uma política da organização que inclua a restrição de lista
constraints/iam.allowServiceAccountCredentialLifetimeExtension
.
Método HTTP e URL:
POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com:generateAccessToken
Corpo JSON da solicitação:
{ "delegates": [ DELEGATES ], "scope": [ "https://www.googleapis.com/auth/cloud-platform" ], "lifetime": "LIFETIME" }
Para enviar a solicitação, expanda uma destas opções:
Se a solicitação generateAccessToken
for bem-sucedida, o corpo da resposta
conterá um token de acesso do OAuth 2.0 e um prazo de validade. O accessToken
poderá
ser usado para autenticar uma solicitação em nome da conta de serviço até que
o expireTime
seja atingido.
{ "accessToken": "eyJ0eXAi...NiJ9", "expireTime": "2020-04-07T15:01:23.045123456Z" }
Gerar tokens de ID do OpenID Connect
Os tokens de ID do OpenID Connect são válidos por 1 hora (3.600 segundos). Para gerar um token de ID para uma conta de serviço, faça o seguinte:
API
O método
serviceAccounts.generateIdToken
da API Service Account Credentials gera um token de ID do OIDC para uma conta de serviço.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
-
PRIV_SA
: o endereço de e-mail da conta de serviço com privilégios para o qual o token de curta duração foi criado. -
AUDIENCE_NAME
: o público-alvo do token, geralmente o URL do aplicativo ou serviço que o token será usado para acessar.
Método HTTP e URL:
POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/PRIV_SA:generateIdToken
Corpo JSON da solicitação:
{ "audience": "AUDIENCE_NAME", "includeEmail": "true" }
Para enviar a solicitação, expanda uma destas opções:
Se a solicitação generateId
for bem-sucedida, o corpo da resposta
conterá um token de ID válido por 1 hora: O token
pode ser usado para
autenticar uma solicitação em nome da conta de serviço:
{ "token": "eyJ0eXAi...NiJ9" }
Criar um JSON Web Token (JWT) autoassinado
Os JSON Web Tokens (JWTs) autoassinados são úteis em vários cenários, como:
- Autenticar uma chamada para uma API Google, conforme descrito no Guia de autenticação do Google.
- Comunicações seguras entre o Google Cloud ou serviços que não são do Google, como aplicativos do App Engine. Nesse cenário, um aplicativo pode assinar um token a ser verificado por outro aplicativo para fins de autenticação.
- Tratar uma conta de serviço como provedor de identidade assinando um JWT que contenha declarações arbitrárias sobre um usuário, uma conta ou um dispositivo.
Para gerar um JWT autoassinado para uma conta de serviço, faça o seguinte:
API
O método
serviceAccounts.signJwt
da API Service Account Credentials assina um JWT usando uma chave privada da conta de serviço gerenciada pelo sistema.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
SA_NAME
: o nome da conta de serviço para a qual você quer criar um token.PROJECT_ID
: o ID do projeto do Google Cloud. Os IDs do projeto são strings alfanuméricas, comomy-project
.DELEGATES
: se você estiver usando um fluxo de solicitação delegada, consulte Como especificar uma cadeia de delegação nesta página. Se você estiver usando um fluxo de solicitação direta sem delegação, omita o campodelegates
no corpo da solicitação.-
JWT_PAYLOAD
: o payload de JWT a ser assinado, que é um objeto JSON contendo um conjunto de declarações do JWT. Inclua as declarações necessárias para o caso de uso pretendido e para atender aos requisitos de validação do serviço que você está chamando. Se você estiver chamando uma API do Google, consulte o Guia de autenticação do Google para conhecer os requisitos da declaração.A declaração
exp
(prazo de validade) precisa ser definida como, no máximo, 12 horas no futuro. Se você estiver chamando uma API do Google, a declaraçãoexp
precisará ser definida como, no máximo, uma hora.O payload de exemplo a seguir contém declarações para chamar uma API do Google, em que
EXP
é um carimbo de data/hora inteiro que representa o prazo de validade:{ \"iss\": \"SA_NAME@PROJECT_ID.iam.gserviceaccount.com\", \"sub\": \"SA_NAME@PROJECT_ID.iam.gserviceaccount.com\", \"aud\": \"https://firestore.googleapis.com/\", \"iat\": 1529350000, \"exp\": EXP }
Método HTTP e URL:
POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com:signJwt
Corpo JSON da solicitação:
{ "delegates": [ DELEGATES ], "payload": "JWT_PAYLOAD" }
Para enviar a solicitação, expanda uma destas opções:
Se a solicitação signJwt
for bem-sucedida, o corpo da resposta conterá um blob assinado e
o ID da chave de assinatura que foi usada para assiná-lo. Use o valor signedJwt
como um token do portador para autenticar diretamente uma solicitação em nome da conta de serviço. O token será
válido até o prazo de validade especificado na solicitação:
{ "keyId": "42ba1e...fc0a", "signedJwt": "eyJ0eXAi...NiJ9" }
Criar um blob autoassinado
Os blobs autoassinados são úteis em cenários em que você precisa transmitir com segurança dados binários arbitrários, geralmente para fins de autenticação. Por exemplo, se você quiser usar um protocolo/tipo de token personalizado (não JWT), inclua esses dados em um blob assinado para uso por um serviço downstream.
Para gerar um blob autoassinado para uma conta de serviço, faça o seguinte:
API
O método
serviceAccounts.signBlob
da API Service Account Credentials assina um blob usando uma chave privada da conta de serviço gerenciada pelo sistema.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
SA_NAME
: o nome da conta de serviço para a qual você quer criar um token.PROJECT_ID
: o ID do projeto do Google Cloud. Os IDs do projeto são strings alfanuméricas, comomy-project
.DELEGATES
: se você estiver usando um fluxo de solicitação delegada, consulte Como especificar uma cadeia de delegação nesta página. Se você estiver usando um fluxo de solicitação direta sem delegação, omita o campodelegates
no corpo da solicitação.BLOB_PAYLOAD
: uma string de bytes codificada em base64. Por exemplo,VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2cu
.
Método HTTP e URL:
POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com:signBlob
Corpo JSON da solicitação:
{ "delegates": [ DELEGATES ], "payload": "BLOB_PAYLOAD" }
Para enviar a solicitação, expanda uma destas opções:
Se a solicitação signBlob
for bem-sucedida, o corpo da resposta conterá um blob assinado e
o ID da chave de assinatura que foi usada para assiná-lo. Use o valor signedBlob
como um token do portador para autenticar diretamente uma solicitação em nome da conta de serviço. O token
será válido até que a chave privada da conta de serviço gerenciada pelo sistema expire. O ID dessa chave é o
valor do campo keyId
na resposta.
{ "keyId": "42ba1e...fc0a", "signedBlob": "eyJ0eXAi...NiJ9" }
Especificar uma cadeia de delegação
Ao usar um fluxo de solicitações delegadas para criar credenciais de conta de serviço de curta duração, o corpo da solicitação de cada API precisa especificar a cadeia de delegação da conta de serviço na ordem correta e no seguinte formato:
projects/-/serviceAccounts/SA_ID
Substitua SA_ID
pelo ID numérico exclusivo
da conta de serviço ou pelo endereço de e-mail da conta de serviço.
Por exemplo, em uma cadeia de delegação que flui de SA_1
(autor da chamada) para SA_2
(delegada) para SA_3
(delegada) para SA_4
, o campo delegates[]
conteria SA_2
e SA_3
na seguinte ordem:
{ "delegates": [ "projects/-/serviceAccounts/SA_2@PROJECT_ID.iam.gserviceaccount.com", "projects/-/serviceAccounts/SA_3@PROJECT_ID.iam.gserviceaccount.com" ] }
O autor da chamada e a conta de serviço para a qual a credencial é criada não são incluídos na cadeia de delegação.