Registros de exemplo para a federação de identidade de colaboradores

A federação de identidade de colaboradores permite que identidades de terceiros acessem recursos do Google Cloud sem usar uma chave de conta de serviço. Ao usar a federação de identidade de colaboradores, é possível analisar os registros de auditoria gerados para monitorar o gerenciamento de pools de colaboradores, trocas de tokens, eventos de login federado e chamadas de API do Google Cloud . Cada exemplo mostra apenas os campos mais relevantes nas entradas de registro.

Para mais informações sobre como ativar e visualizar registros de auditoria, consulte Geração de registros de auditoria do IAM.

Configuração do registro de auditoria

O IAM pode gerar registros de auditoria quando você cria e gerencia pools de força de trabalho. Para ativar os registros de auditoria ao gerenciar pools de forças de trabalho, é preciso ativar os registros de auditoria de atividades de acesso a dados para a seguinte API:

  • API Identity and Access Management (IAM) (ative o tipo de registro "Admin Read")

Para configurar os registros de auditoria do processo de troca de tokens ou do processo de login no console doGoogle Cloud (federado), você também precisa ativar os registros de auditoria para a atividade de acesso a dados para as seguintes APIs:

  • Security Token Service (ative o tipo de registro "Leitura de administradores")
  • API Cloud OAuth (ative o tipo de registro "Leitura de administradores")

Registros para criar um pool de funcionários

O exemplo a seguir mostra uma entrada de registro para criar um pool de forças de trabalho. Neste exemplo, o usuário sam@example.com criou um pool de forças de trabalho com o ID my-pool na organização com o ID 123456789012.

{
  "logName": "organizations/123456789012/logs/cloudaudit.googleapis.com%2Factivity",
  "protoPayload": {
    "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
    "authenticationInfo": {
      "principalEmail": "sam@example.com",
    },
    "methodName": "google.iam.admin.v1.WorkforcePools.CreateWorkforcePool",
    "resourceName": "locations/global/workforcePools/my-pool",
    "serviceName": "iam.googleapis.com",
    "request": {
      "@type": "type.googleapis.com/google.iam.admin.v1.CreateWorkforcePoolRequest",
      "workforcePool": {
        "parent": "organizations/123456789012"
      },
      "workforcePoolId": "my-pool"
    }
  },
  "resource": {
    "type": "audited_resource"
  }
}

Registros para a troca de um token do IdP por um token federado

Depois de configurar o pool de identidades e o provedor de pool de identidades da força de trabalho, é possível criar um token para o provedor de identidade (IdP) e trocá-lo por um token federado.

Depois que você ativa os registros de auditoria do Cloud para a atividade de acesso a dados, o IAM gera uma entrada de registro de auditoria sempre que um principal troca um token. A entrada de registro inclui os seguintes campos:

  • protoPayload.authenticationInfo.principalSubject: o assunto do token do IdP.
    • Para IdPs OIDC, esse campo contém o valor da declaração sub ou assunto do token OIDC.
    • Para IdPs de SAML, este campo contém o valor do subatributo NameID do atributo Subject na declaração SAML.
  • protoPayload.metadata.mapped_principal: o assunto do token, usando a sintaxe do IAM para identificar o principal:

    principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/IDENTIFIER
    
  • protoPayload.resourceName: o provedor do pool de forças de trabalho a que o token está associado.

Troca de token bem-sucedida com o Security Token Service

O exemplo a seguir mostra uma entrada de registro de auditoria para uma solicitação de troca de um token usando o Security Token Service (sts.googleapis.com). Neste exemplo, um token OIDC é trocado por um token federado:

{
  "logName": "organizations/123456789012/logs/cloudaudit.googleapis.com%2Fdata_access",
  "protoPayload": {
    "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
    "authenticationInfo": {
      "principalSubject": "b6112abb-5791-4507-adb5-7e8cc306eb2e"
    },
    "metadata": {
      "mapped_principal": "principal://iam.googleapis.com/locations/global/workforcePools/oidc-pool/subject/a1234bcd-5678-9012-efa3-4b5cd678ef9a"
    },
    "methodName": "google.identity.sts.v1.SecurityTokenService.ExchangeToken",
    "resourceName": "locations/global/workforcePools/oidc-pool/providers/oidc-provider",
    "serviceName": "sts.googleapis.com",
    "request": {
      "@type": "type.googleapis.com/google.identity.sts.v1.SecurityTokenService.ExchangeTokenRequest",
      "audience": "//iam.googleapis.com/locations/global/workforcePools/oidc-pool/providers/oidc-provider",
      "grantType": "urn:ietf:params:oauth:grant-type:token-exchange",
      "requestedTokenType": "urn:ietf:params:oauth:token-type:access_token",
      "subjectTokenType": "urn:ietf:params:oauth:token-type:id_token"
    }
  },
  "resource": {
    "type": "audited_resource"
  }
}

Falha na troca de tokens: muitos grupos

O registro de exemplo a seguir descreve uma troca de token que falhou porque o número de grupos excedeu o máximo de 400.

Para registrar os atributos recebidos pela federação de identidade de colaboradores, é necessário ativar o registro de auditoria detalhado ao criar o provedor de pool de identidade de colaboradores.

Para saber como resolver problemas de mapeamento de atributos com registros de auditoria detalhados, consulte Erros gerais de mapeamento de atributos.

No exemplo a seguir, mappedAttributes contém atributos que foram recebidos do IdP, incluindo uma lista de grupos. Nesse caso, o número de grupos excedeu o limite da federação de identidade de colaboradores.

{
  "protoPayload": {
    "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
    "status": {
      "code": 3,
      "message": "The current count of 800 mapped attribute google.groups exceeds the 400 count limit. Either modify your attribute mapping or the incoming assertion to produce a mapped attribute that is less than 400."
    },
    "authenticationInfo": {
      "principalSubject": "3Kn-kJQal4N-WXVjxMqcOF1tQcCdBliu97lV-2P-Khc"
    },
    "requestMetadata": {
      "callerIp": "2601:647:4680:9140:9d68:88c9:cab9:a908",
      "callerSuppliedUserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36",
      "requestAttributes": {
        "time": "2025-04-09T18:32:34.979311Z",
        "auth": {}
      },
      "destinationAttributes": {}
    },
    "serviceName": "sts.googleapis.com",
    "methodName": "google.identity.sts.SecurityTokenService.WebSignIn",
    "authorizationInfo": [
      {
        "permission": "sts.identityProviders.checkLogging",
        "granted": false,
        "permissionType": "ADMIN_READ"
      }
    ],
    "resourceName": "locations/global/workforcePools/my-pool/providers/my-provider",
    "request": {
      "@type": "type.googleapis.com/google.identity.sts.SecurityTokenService.WebSignInRequest",
      "provider": "//iam.googleapis.com/locations/global/workforcePools/my-pool/providers/my-provider",
      "host": "auth-staging.corp.cloud.google"
    },
    "metadata": {
      "mappedAttributes": {
        "google.subject": "3Nk-kJQal4N-WXVjxMqcOF1tQcCdBliu97lV-2P-Khc",
        "google.providerId": "my-provider-id",
        "google.groups": "[group-claim-1, group-claim-2, ..., group-claim-800]"
      }
    }
  },
  "insertId": "-llnhbmck3a",
  "resource": {
    "type": "audited_resource",
    "labels": {
      "service": "sts.googleapis.com",
      "method": "google.identity.sts.SecurityTokenService.WebSignIn"
    }
  },
  "timestamp": "2025-04-09T18:32:34.208412Z",
  "severity": "ERROR",
  "logName": "organizations/123456789012/logs/cloudaudit.googleapis.com%2Fdata_access",
  "receiveTimestamp": "2025-04-09T18:32:35.059811619Z"
}

Registros de declarações SAML assinadas e criptografadas

Nesta seção, descrevemos as entradas de registro dos Registros de auditoria do Cloud que o Security Token Service cria quando tenta verificar as declarações SAML assinadas ou descriptografar declarações criptografadas enviadas do IdP.

Para a federação de identidade de colaboradores, a entrada de registro pertinente é semelhante a esta:

"keyInfo": [
  {
    "use": "verify"
    "fingerprint": "3C:B2:47:F8:A5:9A:8A:52:BD:1C:BC:96:B5:45:C1:8D:A7:F1:73:2D"
  },
  {
    "use": "decrypt"
    "resourceName": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_NAME/providers/PROVIDER_NAME/keys/KEY_NAME"
  }
]

Esta saída inclui os seguintes valores:

  • fingerprint: a representação hexadecimal do hash SHA-256 do certificado X.509 usado para verificar a assinatura na credencial SAML. O certificado X.509 é extraído dos metadados XML SAML anexados ao provedor do pool de identidades da força de trabalho.
  • resourceName: o nome do recurso da chave do provedor de pool de identidade da força de trabalho que foi usada para descriptografar a declaração SAML criptografada. Esse campo só estará presente se a federação de identidade receber uma resposta SAML criptografada do IdP.

Registros para chamar APIs do Google Cloud com o token federado

Depois de trocar o token do IdP por um token federado, você pode usar o token federado para chamar as APIs do Google Cloud . Alguns dos métodos chamados podem gerar registros de auditoria.

O exemplo a seguir mostra uma entrada de registro de auditoria para uma solicitação para listar os buckets do Cloud Storage em um projeto usando um token federado.

{
  "logName": "projects/my-project/logs/cloudaudit.googleapis.com%2Fdata_access",
  "protoPayload": {
    "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
    "authenticationInfo": {
      "principalSubject": "principal://iam.googleapis.com/locations/global/workforcePools/oidc-pool/subject/kalani@altostrat.com"
    },
    "methodName": "storage.buckets.list",
    "serviceName": "storage.googleapis.com",
  },
  "resource": {
    "type": "gcs_bucket"
  }
}

Registros para login no console do Google Cloud (federado)

Depois que você configurar seus pools de identidade de colaboradores e os IdPs deles, os usuários poderão fazer login no Google Cloud usando o console (federado).

Registros para login realizado

Nesta seção, apresentamos um exemplo de entrada de registro dos Registros de auditoria do Cloud que é registrada como resultado de um processo de login bem-sucedido. Neste exemplo, o usuário user@example.com faz login usando um provedor locations/global/workforcePools/my-pool/providers/my-provider. Nesse caso, a seguinte entrada de registros de auditoria do Cloud é gerada:

{
  "logName": "organizations/my-organization-id/logs/cloudaudit.googleapis.com%2Fdata_access",
  "protoPayload": {
    "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
    "authenticationInfo": {
      "principalSubject": "user@example.com",
    },
    "serviceName": "sts.googleapis.com",
    "methodName": "google.identity.sts.SecurityTokenService.WebSignIn",
    "resourceName": "locations/global/workforcePools/my-pool/providers/my-provider",
    "request": {
      "@type": "type.googleapis.com/google.identity.sts.SecurityTokenService.WebSignInRequest",
      "provider": "//iam.googleapis.com/locations/global/workforcePools/my-pool/providers/my-provider",
      "continueUrl": "https://console.cloud.google",
      "host": "http://auth.cloud.google",
    },
    "metadata": {
       "mappedPrincipal": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
    }
  },
  "resource": {
    "type": "audited_resource",
    "labels": {
      "service": "sts.googleapis.com",
      "method": "google.identity.sts.SecurityTokenService.WebSignIn",
    }
  },
}

A entrada de registros de auditoria do Cloud para provedores SAML também pode conter informações sobre a chave de assinatura no campo de metadados.

{
  "metadata": {
    "mappedPrincipal": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
    "keyInfo": [
      {
        "use": "verify",
        "fingerprint": "AE:CK:LM:EF:LK:OG:EH:IJ:KN:AL:OM:AD:NO",
      }
    ],
  }
}

Registros de falha no login

Nesta seção, apresentamos um exemplo de entrada de registro dos Registros de auditoria do Cloud que é registrada como resultado de um processo de login com falha. Neste exemplo, o usuário user@example.com tenta fazer login usando um provedor locations/global/workforcePools/my-pool/providers/my-provider, mas tem o acesso negado porque uma condição de atributo não está sendo atendida. Nesse caso, a seguinte entrada de registros de auditoria do Cloud é gerada:

{
  "logName": "organizations/my-organization-id/logs/cloudaudit.googleapis.com%2Fdata_access",
  "protoPayload": {
    "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
    "authenticationInfo": {
      "principalSubject": "user@example.com",
    },
    "status": {
      "code": 3,
      "message": "The given credential is rejected by the attribute condition.",
    },
    "serviceName": "sts.googleapis.com",
    "methodName": "google.identity.sts.SecurityTokenService.WebSignIn",
    "resourceName": "locations/global/workforcePools/my-pool/subject/user@example.com",
    "request": {
      "@type": "type.googleapis.com/google.identity.sts.SecurityTokenService.WebSignInRequest",
      "provider": "//iam.googleapis.com/locations/global/workforcePools/my-pool/providers/my-provider",
      "host": "http://auth.cloud.google",
    },
    "metadata": {
      "mappedPrincipal": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
    }
  },
  "resource": {
    "type": "audited_resource",
    "labels": {
      "service": "sts.googleapis.com",
      "method": "google.identity.sts.SecurityTokenService.WebSignIn",
    }
  },
}

Registros de saída

Nesta seção, apresentamos um exemplo de entrada de registro dos Registros de auditoria do Cloud que é registrada como resultado de um evento de saída. Neste exemplo, o usuário user@example.com, que fez login usando um provedor locations/global/workforcePools/my-pool/providers/my-provider, inicia uma saída. Nesse caso, a seguinte entrada de registro dos Registros de auditoria do Cloud é gerada:

{
  "logName": "organizations/my-organization-id/logs/cloudaudit.googleapis.com%2Fdata_access",
  "protoPayload": {
    "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
    "authenticationInfo": {
      "principalSubject": "user@example.com",
    },
    "serviceName": "sts.googleapis.com",
    "methodName": "google.identity.sts.SecurityTokenService.WebSignOut",
    "resourceName": "locations/global/workforcePools/my-pool/providers/my-provider",
    "request": {
      "@type": "type.googleapis.com/google.identity.sts.SecurityTokenService.WebSignOutRequest",
      "provider": "//iam.googleapis.com/locations/global/workforcePools/my-pool/providers/my-provider",
      "host": "http://auth.cloud.google"
    },
    "metadata": {
      "mappedPrincipal": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
    }
  },
  "resource": {
    "type": "audited_resource",
    "labels": {
      "service": "sts.googleapis.com",
      "method": "google.identity.sts.SecurityTokenService.WebSignOut"
    }
  },
}

Registros de login com o fluxo do OAuth

Depois de configurar o pool de identidades e o provedor de pool de identidades da força de trabalho, é possível acessar os recursos do Google Cloud usando o fluxo do OAuth.

Depois que você ativa os registros de auditoria do Cloud para a atividade de registros de auditoria de acesso a dados, o IAM gera uma entrada de registro de auditoria sempre que um principal usa o fluxo do OAuth para fazer login. A entrada de registro inclui os seguintes campos:

  • protoPayload.authenticationInfo.principalSubject: o assunto do token do IdP.
    • Para IdPs OIDC, esse campo contém o valor da declaração sub ou assunto do token OIDC.
    • Para IdPs de SAML, este campo contém o valor do subatributo NameID do atributo Subject na declaração SAML.
  • protoPayload.metadata.mapped_principal: o assunto do token, usando a sintaxe do IAM para identificar o principal:

    principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/IDENTIFIER
    
  • protoPayload.resourceName: o provedor do pool de forças de trabalho a que o token está associado.

O exemplo a seguir mostra uma entrada de registro de auditoria para uma solicitação para trocar um token. Neste exemplo, o principal é federado usando um provedor OIDC:

{
  "logName": "organizations/123456789012/logs/cloudaudit.googleapis.com%2Fdata_access",
  "protoPayload": {
    "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
    "authenticationInfo": {
      "principalSubject": "b6112abb-5791-4507-adb5-7e8cc306eb2e"
    },
    "metadata": {
      "mapped_principal": "principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/IDENTIFIER"
    },
    "methodName": "google.identity.sts.v1.SecurityTokenService.ExchangeOauthToken",
    "resourceName": "locations/global/workforcePools/POOL_ID/providers/WORKFORCE_PROVIDER_ID",
    "serviceName": "sts.googleapis.com",
    "request": {
      "@type": "type.googleapis.com/google.identity.sts.v1.SecurityTokenService.ExchangeOauthTokenRequest",
      "grantType": "authorization_code",
    }
  },
  "resource": {
    "type": "audited_resource"
  }
}

A seguir