Crie credenciais de curta duração para várias contas de serviço

Esta página explica como criar credenciais de curta duração para uma conta de serviço com base numa cadeia de delegação de contas de serviço. Pode usar esta abordagem quando precisar de emitir uma série de chamadas de geração de tokens para obter um token com as autorizações necessárias para realizar a sua tarefa.

Depois de receber uma credencial de curta duração, pode usá-la para representar a conta de serviço.

Se puder gerar um token com as autorizações necessárias com uma única chamada de geração de tokens, deve criar credenciais de curta duração para essa conta de serviço diretamente.

Acerca da criação de credenciais de curta duração

Consoante o tipo de token que criar, pode usar credenciais de curta duração para autenticar chamadas para APIs Google, APIs de terceiros ou aplicações que exijam tokens de ID. As credenciais de curta duração têm um tempo de vida limitado, com durações de apenas algumas horas ou menos, e não são atualizadas automaticamente. As credenciais da conta de serviço de curta duração são úteis para cenários em que precisa de conceder acesso limitado a recursos para contas de serviço fidedignas. Também criam menos risco do que as credenciais de longa duração, como as chaves da conta de serviço.

Pode criar os seguintes tipos de credenciais de curta duração para uma conta de serviço:

  • Chaves de acesso OAuth 2.0

    Os tokens de acesso são aceites para autenticação pela maioria das APIs Google. Quando gera uma chave de acesso para uma conta de serviço, a chave de acesso é fornecida sem uma chave de atualização, o que significa que, quando a chave expira, tem de repetir o processo de criação da chave para gerar uma nova.

    Para mais informações, consulte o artigo Tokens de acesso.

  • Tokens de ID do OpenID Connect (OIDC)

    Os tokens de ID seguem a especificação do OpenID Connect (OIDC). Os tokens de ID são aceites por um número limitado de serviços e aplicações.

    Para mais informações, consulte os tokens de ID e a autenticação para aplicações alojadas no Cloud Run ou nas funções do Cloud Run.

  • Símbolos da Web JSON (JWTs) autoassinados

    Pode usar JWTs autoassinados para autenticar algumas APIs Google sem obter um token de acesso do servidor de autorização. As APIs implementadas com o API Gateway requerem-no.

  • Blobs binários autoassinados

    Os blobs autoassinados são úteis em cenários em que precisa de transmitir em segurança dados binários arbitrários, normalmente para fins de autenticação.

Fluxo de pedido delegado

O fluxo de pedidos delegados permite encadear pedidos diretos usando um único pedido, em vez de ter de fazer vários pedidos diretos em sequência. Neste fluxo, o pedido de uma credencial de conta de serviço é delegado a uma ou mais contas de serviço numa 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 e não as contas de serviço intermédias na cadeia de delegação.

Cada conta de serviço na cadeia de delegação tem de ter as autorizações necessárias na conta de serviço seguinte na cadeia para poder transmitir o pedido.

Se uma conta de serviço fornecer todas as autorizações de que precisa, deve usar o fluxo mais simples descrito no artigo Crie credenciais de curta duração a partir de uma conta de serviço.

Antes de começar

Conceda as autorizações necessárias

Um pedido delegado envolve mais de duas identidades: o autor da chamada, uma ou mais contas de serviço numa cadeia de delegação e, finalmente, a conta de serviço para a qual é criada uma credencial. Neste fluxo, considere as seguintes identidades:

  • Conta de serviço 1 (SA_1), o autor da chamada que emite um pedido de credenciais de curta duração.
  • Conta de serviço 2 (SA_2), uma conta de serviço intermediária que delega o pedido inicial a SA_3. Esta conta apenas reencaminha o pedido. Não concede acesso adicional ao SA_1 nem ao SA_3.
  • 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 tem de conceder a função de criador de tokens de conta de serviço (roles/iam.serviceAccountTokenCreator) à conta anterior na cadeia.

Neste exemplo específico, SA_1 tem de receber a função de criador de tokens de conta de serviço (roles/iam.serviceAccountTokenCreator) em SA_2. Este é um exemplo da conta de serviço SA_2 a ser tratada como um recurso: quando concede a função em SA_2, atualiza a respetiva política de autorização da mesma forma que atualizaria qualquer outro recurso.

Neste fluxo de exemplo, existe apenas uma conta de serviço intermediária. Para delegar o acesso através de mais de uma conta de serviço, também tem de atribuir esta função a qualquer outra conta de serviço na cadeia.

Em seguida, também tem de ser atribuída a SA_2 a função de criador de tokens da conta de serviço (roles/iam.serviceAccountTokenCreator) em SA_3. Isto permite que o SA_2 crie credenciais de curta duração para o SA_3.

Os passos seguintes usam a API REST para conceder as funções. No entanto, também pode usar a Trusted Cloud consola ou a CLI gcloud.

API

Primeiro, obtenha a política de permissão para SA_2 (a conta de serviço intermediária):

O método serviceAccounts.getIamPolicy obtém a política de autorização de uma conta de serviço.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: O ID do seu Trusted Cloud projeto. Os IDs dos projetos são strings alfanuméricas, como my-project.
  • SA_2: o nome da conta de serviço 2.
  • POLICY_VERSION: a versão da política a ser devolvida. Os pedidos devem especificar a versão da política mais recente, que é a versão 3 da política. Consulte o artigo Especificar uma versão da política ao obter uma política para ver detalhes.

Método HTTP e URL: 

POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_2@PROJECT_ID.s3ns-system.iam.gserviceaccount.com:getIamPolicy

Corpo JSON do pedido: 

{
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}

Para enviar o seu pedido, expanda uma destas opções:

Deve receber uma resposta JSON semelhante à seguinte:

{
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/my-user@example.com"
      ]
    }
  ]
}

Se não tiver concedido uma função à conta de serviço, a resposta contém apenas um valor etag. Inclua esse valor de etag no passo seguinte.

Em seguida, modifique a política de autorização para conceder a SA_1 a função de criador de tokens de contas de serviço (roles/iam.serviceAccountTokenCreator).

Por exemplo, para modificar a resposta de exemplo do passo anterior, adicione o seguinte:

{
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/my-user@example.com"
      ]
    },
    {
      "role": "roles/iam.serviceAccountTokenCreator",
      "members": [
        "serviceAccount:SA_1@PROJECT_ID.s3ns-system.iam.gserviceaccount.com"
      ]
    }
  ]
}

Em seguida, 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 qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: O ID do seu Trusted Cloud projeto. Os IDs dos projetos são strings alfanuméricas, como my-project.
  • SA_2: o nome da conta de serviço 2.

  • POLICY: Uma representação JSON da política que quer definir. Para mais informações sobre o formato de uma política, consulte a referência de políticas.

    Por exemplo, para definir a política de permissão apresentada no passo anterior, substitua POLICY pelo seguinte:

    {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/my-user@example.com"
      ]
    },
    {
      "role": "roles/iam.serviceAccountTokenCreator",
      "members": [
        "serviceAccount:SA_1@PROJECT_ID.s3ns-system.iam.gserviceaccount.com"
      ]
    }
  ]
}

Método HTTP e URL: 

POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_2@PROJECT_ID.s3ns-system.iam.gserviceaccount.com:setIamPolicy

Corpo JSON do pedido: 

{
  "policy": POLICY
}

Para enviar o seu pedido, expanda uma destas opções:

A resposta contém a política de permissão atualizada.

Agora, obtenha a política de permissão para SA_3 (a conta de serviço para a qual a credencial é criada):

O método serviceAccounts.getIamPolicy obtém a política de autorização de uma conta de serviço.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: O ID do seu Trusted Cloud projeto. Os IDs dos projetos são strings alfanuméricas, como my-project.
  • SA_3: o nome da conta de serviço 3.
  • POLICY_VERSION: a versão da política a ser devolvida. Os pedidos devem especificar a versão da política mais recente, que é a versão 3 da política. Consulte o artigo Especificar uma versão da política ao obter uma política para ver detalhes.

Método HTTP e URL: 

POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_3@PROJECT_ID.s3ns-system.iam.gserviceaccount.com:getIamPolicy

Corpo JSON do pedido: 

{
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}

Para enviar o seu pedido, expanda uma destas opções:

Deve receber uma resposta JSON semelhante à seguinte:

{
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/my-user@example.com"
      ]
    }
  ]
}

Se não tiver atribuído uma função à conta de serviço, a resposta contém apenas um valor etag. Inclua esse valor de etag no passo seguinte.

Em seguida, modifique a política de autorização para conceder a SA_2 a função de criador de tokens de contas de serviço (roles/iam.serviceAccountTokenCreator).

Por exemplo, para modificar a resposta de exemplo do passo anterior, adicione o seguinte:

{
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/my-user@example.com"
      ]
    },
    {
      "role": "roles/iam.serviceAccountTokenCreator",
      "members": [
        "serviceAccount:SA_2@PROJECT_ID.s3ns-system.iam.gserviceaccount.com"
      ]
    }
  ]
}

Por último, 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 qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: O ID do seu Trusted Cloud projeto. Os IDs dos projetos são strings alfanuméricas, como my-project.
  • SA_3: o nome da conta de serviço 3.

  • POLICY: Uma representação JSON da política que quer definir. Para mais informações sobre o formato de uma política, consulte a referência de políticas.

    Por exemplo, para definir a política de permissão apresentada no passo anterior, substitua POLICY pelo seguinte:

    {
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/my-user@example.com"
      ]
    },
    {
      "role": "roles/iam.serviceAccountTokenCreator",
      "members": [
        "serviceAccount:SA_2@PROJECT_ID.s3ns-system.iam.gserviceaccount.com"
      ]
    }
  ]
}

Método HTTP e URL: 

POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_3@PROJECT_ID.s3ns-system.iam.gserviceaccount.com:setIamPolicy

Corpo JSON do pedido: 

{
  "policy": POLICY
}

Para enviar o seu pedido, expanda uma destas opções:

A resposta contém a política de permissão atualizada.

Peça credenciais de curta duração

Depois de conceder as funções adequadas a cada identidade, pode pedir credenciais de curta duração para a conta de serviço pretendida. São suportados os seguintes tipos de credenciais:

Para saber como especificar uma cadeia de delegação para estes pedidos, consulte a secção Especificar uma cadeia de delegação nesta página.

Gere uma chave de acesso OAuth 2.0

Por predefinição, as chaves de acesso de OAuth 2.0 são válidas durante 1 hora (3600 segundos) no máximo. No entanto, pode prolongar a duração total máxima destas chaves de acesso para 12 horas (43 200 segundos). Para tal, identifique as contas de serviço que precisam de uma duração total máxima para as chaves de acesso e, em seguida, adicione estas contas de serviço a uma política da organização que inclua a restrição da constraints/iam.allowServiceAccountCredentialLifetimeExtension lista. Em seguida,pode especificar uma duração total máxima de 43 200 segundos ao criar uma chave de acesso para estas contas de serviço.

Para gerar um token de acesso 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 uma chave de acesso do OAuth 2.0 para uma conta de serviço.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • SA_NAME: o nome da conta de serviço para a qual quer criar um token.
  • PROJECT_ID: O ID do seu Trusted Cloud projeto. Os IDs dos projetos são strings alfanuméricas, como my-project.
  • DELEGATES: se estiver a usar um fluxo de pedidos delegados, consulte a secção Especificar uma cadeia de delegação nesta página. Se estiver a usar um fluxo de pedidos diretos sem delegação, omita o campo delegates no corpo do pedido.

  • LIFETIME: o tempo até o token de acesso expirar, em segundos. Por exemplo, 300s.

    Por predefinição, a duração máxima do token é de 1 hora (3600 segundos). Para prolongar a duração total máxima destas chaves de acesso 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.s3ns-system.iam.gserviceaccount.com:generateAccessToken

Corpo JSON do pedido: 

{
  "delegates": [
    DELEGATES
  ],
  "scope": [
    "https://www.googleapis.com/auth/cloud-platform"
  ],
  "lifetime": "LIFETIME"
}

Para enviar o seu pedido, expanda uma destas opções:

Se o pedido generateAccessToken for bem-sucedido, o corpo da resposta contém uma chave de acesso OAuth 2.0 e um prazo de validade. Em seguida, o accessToken pode ser usado para autenticar um pedido em nome da conta de serviço até atingir o expireTime: 

{
  "accessToken": "eyJ0eXAi...NiJ9",
  "expireTime": "2020-04-07T15:01:23.045123456Z"
}

Gere tokens de ID do OpenID Connect

Os tokens de ID do OpenID Connect são válidos durante 1 hora (3600 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 OIDC para uma conta de serviço.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PRIV_SA: o endereço de email da conta de serviço com privilégios para a qual o token de curta duração é criado.
  • AUDIENCE_NAME: o público-alvo do token, normalmente o URL da aplicação ou do serviço que o token vai usar para aceder.

Método HTTP e URL: 

POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/PRIV_SA:generateIdToken

Corpo JSON do pedido: 

{
  "audience": "AUDIENCE_NAME",
  "includeEmail": "true"
}

Para enviar o seu pedido, expanda uma destas opções:

Se o pedido generateId for bem-sucedido, o corpo da resposta contém um token de ID válido durante 1 hora. Em seguida, o token pode ser usado para autenticar um pedido em nome da conta de serviço: 

{
  "token": "eyJ0eXAi...NiJ9"
}

Crie um símbolo da Web JSON (JWT) autoassinado

Os símbolos da Web JSON (JWTs) autoassinados são úteis em vários cenários, como:

  • Autenticar uma chamada a uma API Google, conforme descrito no guia de autenticação da Google.
  • Comunicar de forma segura entre Trusted Cloud ou serviços não pertencentes à Google, como aplicações do App Engine. Neste cenário, uma aplicação pode assinar um token que pode ser validado por outra aplicação para fins de autenticação.
  • Tratar uma conta de serviço como um fornecedor de identidade ao assinar um JWT que contém reivindicações arbitrárias sobre um utilizador, 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 com a chave privada gerida pelo sistema de uma conta de serviço.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • SA_NAME: o nome da conta de serviço para a qual quer criar um token.
  • PROJECT_ID: O ID do seu Trusted Cloud projeto. Os IDs dos projetos são strings alfanuméricas, como my-project.
  • DELEGATES: se estiver a usar um fluxo de pedidos delegados, consulte a secção Especificar uma cadeia de delegação nesta página. Se estiver a usar um fluxo de pedidos diretos sem delegação, omita o campo delegates no corpo do pedido.

  • JWT_PAYLOAD: o payload JWT a assinar, que é um objeto JSON que contém um conjunto de afirmações JWT. Inclua as reivindicações necessárias para o exemplo de utilização pretendido e para cumprir os requisitos de validação do serviço que está a chamar. Se estiver a chamar uma API Google, consulte o guia de autenticação da Google para ver os requisitos de reivindicação.

    A reivindicação exp (hora de validade) não pode ser superior a 12 horas no futuro. Se estiver a chamar uma API Google, a reivindicação exp tem de ser definida no máximo 1 hora no futuro.

    A carga útil de exemplo seguinte contém reivindicações para chamar uma API Google, em que EXP é uma data/hora com indicação de tempo inteiro que representa a hora de validade: 

    { \"iss\": \"SA_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com\", \"sub\": \"SA_NAME@PROJECT_ID.s3ns-system.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.s3ns-system.iam.gserviceaccount.com:signJwt

Corpo JSON do pedido: 

{
  "delegates": [
    DELEGATES
  ],
  "payload": "JWT_PAYLOAD"
}

Para enviar o seu pedido, expanda uma destas opções:

Se o pedido signJwt for bem-sucedido, o corpo da resposta contém um JWT assinado e o ID da chave de assinatura que foi usado para assinar o JWT. Pode usar o valor signedJwt como um token de autorização para autenticar diretamente um pedido em nome da conta de serviço. O token é válido até à hora de validade especificada no pedido: 

{
  "keyId": "42ba1e...fc0a",
  "signedJwt": "eyJ0eXAi...NiJ9"
}

Crie um blob autoassinado

Os blobs autoassinados são úteis em cenários em que precisa de transmitir em segurança dados binários arbitrários, normalmente para fins de autenticação. Por exemplo, se quiser usar um protocolo/tipo de token personalizado (não JWT), pode incluir esses dados num blob assinado para uso por um serviço a jusante.

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 com a chave privada gerida pelo sistema de uma conta de serviço.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • SA_NAME: o nome da conta de serviço para a qual quer criar um token.
  • PROJECT_ID: O ID do seu Trusted Cloud projeto. Os IDs dos projetos são strings alfanuméricas, como my-project.
  • DELEGATES: se estiver a usar um fluxo de pedidos delegados, consulte a secção Especificar uma cadeia de delegação nesta página. Se estiver a usar um fluxo de pedidos diretos sem delegação, omita o campo delegates no corpo do pedido.
  • BLOB_PAYLOAD: uma string de bytes com codificação base64. Por exemplo, VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2cu.

Método HTTP e URL: 

POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SA_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com:signBlob

Corpo JSON do pedido: 

{
  "delegates": [
    DELEGATES
  ],
  "payload": "BLOB_PAYLOAD"
}

Para enviar o seu pedido, expanda uma destas opções:

Se o pedido signBlob for bem-sucedido, o corpo da resposta contém um blob assinado e o ID da chave de assinatura que foi usado para assinar o blob. Pode usar o valor signedBlob como um token de portador para autenticar diretamente um pedido em nome da conta de serviço. O token é válido até a chave privada gerida pelo sistema da conta de serviço expirar. O ID desta chave é o valor do campo keyId na resposta. 

{
  "keyId": "42ba1e...fc0a",
  "signedBlob": "eyJ0eXAi...NiJ9"
}

Especifique uma cadeia de delegação

Quando usar um fluxo de pedidos delegados para criar credenciais de conta de serviço de curta duração, o corpo do pedido para cada API tem de especificar a cadeia de delegação da conta de serviço pela 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 email da conta de serviço.

Por exemplo, numa cadeia de delegação que flui de SA_1 (autor da chamada) para SA_2 (delegado) para SA_3 (delegado) para SA_4, o campo delegates[] conteria SA_2 e SA_3 pela seguinte ordem:

{
  "delegates": [
    "projects/-/serviceAccounts/SA_2@PROJECT_ID.s3ns-system.iam.gserviceaccount.com",
    "projects/-/serviceAccounts/SA_3@PROJECT_ID.s3ns-system.iam.gserviceaccount.com"
  ]
}

O autor da chamada e a conta de serviço para a qual a credencial é criada não estão incluídos na cadeia de delegação.