Para diagnosticar e resolver erros de autenticação e provisionamento na federação de identidade de colaboradores, inspecione as respostas do provedor de identidade (IdP) e os registros de auditoria do Cloud. Essas verificações ajudam a identificar incompatibilidades de configuração e restaurar o acesso do usuário.
Inspecionar a resposta do IdP
Nesta seção, mostramos como inspecionar a resposta do provedor de identidade (IdP) para resolver problemas listados neste documento.
Login com base no navegador
Para inspecionar a resposta retornada pelo IdP, gere um arquivo HAR usando a ferramenta da sua escolha. Por exemplo, use o Google Admin Toolbox HAR Analyzer, que fornece instruções para gerar um arquivo HAR e as ferramentas para fazer upload e analisar.
SAML
Para inspecionar a resposta do IdP SAML, siga estas etapas:
- Localize o valor do parâmetro de solicitação
SAMLResponseno arquivo HAR registrado no URL com o caminho/signin-callback. - Decodifique com uma ferramenta de sua escolha. Por exemplo, você pode usar o Google Admin Toolbox Encode/Decode.
OIDC
Para inspecionar a resposta do IdP OIDC, siga estas etapas: Essa abordagem não funciona com o fluxo de código.
- Procure o parâmetro de solicitação
id_tokenno arquivo HAR que é registrado em um URL com o caminho/signin-callback. - Decodifique-o usando uma ferramenta de depuração JWT de sua escolha.
CLI da gcloud
Para inspecionar a resposta do IdP ao usar a CLI gcloud,
copie o conteúdo do arquivo transmitido na flag
--credential-source-file ao executar o comando
gcloud iam workforce-pools create-cred-config e execute as
etapas abaixo:
SAML
Decodifique a resposta do IdP SAML usando a ferramenta que preferir. Por exemplo, use o Google Admin Toolbox Encode/Decode.
OIDC
Decodifique a resposta do IdP do OIDC usando a ferramenta de depuração JWT de sua escolha.
Revisão de registros
Para determinar se o Google Cloud está se comunicando com o IdP e analisar as informações da transação, inspecione os registros de auditoria do Cloud.
Para ver exemplos de registros, consulte Exemplos de registros de auditoria.
Erros de gerenciamento de provedor e pool de funcionários
Nesta seção, fornecemos sugestões para corrigir erros comuns que você pode encontrar ao gerenciar pools e provedores.
Erros gerais de mapeamento de atributos
Para resolver problemas de mapeamento de atributos do provedor de pool de identidades de colaboradores, faça o seguinte:
Inspecione os atributos, também conhecidos como declarações, na configuração do IdP. Verifique como os mapeamentos de atributos convertem atributos do IdP em atributos do Google Cloud e como as condições avaliam esses atributos para permitir ou negar o acesso no console do Google Cloud .
- Verifique se você tem o papel de Editor de pool de forças de trabalho do IAM (
roles/iam.workforcePoolEditor). - Para ativar o fluxo de login baseado em navegador para a federação de identidade de colaboradores, adicione
https://auth.cloud.google/signin-callback/locations/global/workforcePools/POOL_ID/providers/PROVIDER_IDà lista de URIs de redirecionamento permitidos do IdP. -
No console do Google Cloud , acesse Pools de identidade de colaboradores.
Acessar pools de identidade de colaboradores - Na lista de pools, clique no nome do pool que você quer verificar.
- Na página Detalhes do pool de colaboradores, clique no nome do IdP que você quer verificar.
- Na página Detalhes do provedor, clique em Depurar token do IdP.
- Na caixa de diálogo Fazer login, faça login no IdP como usuário de teste.
A página Validar os atributos do seu provedor mostra os atributos mapeados e o resultado da condição de atributo.
A seção Atributos mapeados do token do IdP mostra como os atributos do Google, como
google.subject, são preenchidos com base no token do IdP de acordo com sua configuração de mapeamento. Um ícone de erro vai aparecer se um mapeamento estiver incorreto.A seção Condição do atributo mostra o resultado booleano da sua condição. Se a condição for avaliada como
false, o login será bloqueado.Para ver o token de declaração completo, clique em Ver token completo. Isso mostra o objeto JSON bruto do seu IdP. Faça referência a uma propriedade de nível superior nos mapeamentos usando o formato
assertion.PROPERTY_NAME.Para corrigir erros, edite a configuração:
- Na página Validar os atributos do seu provedor, clique em Editar.
- Faça as alterações necessárias.
- Para iniciar um novo teste e ver os resultados atualizados, clique em Salvar e buscar o token novamente.
- Verifique se você tem o papel de Editor de pool de forças de trabalho do IAM (
Inspecione os tokens gerados pelo IdP. Para saber como gerar um token do IdP, consulte a documentação dele.
Revise o registro de auditoria detalhado da federação de identidade de colaboradores nos Registros de auditoria do Cloud.
O registro de auditoria detalhado registra erros de autenticação e autorização, além de declarações recebidas pela federação de identidade de colaboradores.
É possível ativar a geração de registros de auditoria detalhados ao criar o provedor de pool de identidades de colaboradores. Para ativar os registros de auditoria detalhados, adicione a flag --detailed-audit-logging
ao criar o provedor do pool de identidades de colaboradores.
Permissão negada
Esse erro ocorre quando o usuário que tenta configurar a federação de identidade de colaboradores não tem o papel Administrador de pool de colaboradores do IAM (roles/iam.workforcePoolAdmin).
INVALID_ARGUMENT: configuração de logon único da Web do OIDC ausente
O seguinte erro ocorre quando os campos web-sso-response-type e web-sso-assertion-claims-behavior não são definidos ao criar um provedor de pool de identidade
do OIDC:
ERROR: (gcloud.iam.workforce-pools.providers.create-oidc) INVALID_ARGUMENT: Missing OIDC web single sign-on config.
Para resolver esse erro, siga as etapas na seção Criar um provedor para definir os campos adequadamente ao criar o provedor de pool de identidade da força de trabalho do OIDC.
Limite de taxa excedido (HTTP 429)
Esse erro ocorre quando sua organização esgota a cota para troca de tokens do pool de colaboradores (sts.googleapis.com/workforce_requests).
Essa cota é aplicada a cada organização e o padrão é de
1.000 solicitações por
minuto. Como essa cota é compartilhada entre todos os pools de colaboradores, provedores,
usuários e cargas de trabalho automatizadas na sua organização, um único cliente de alta
frequência pode causar erros de HTTP 429 em toda a organização, inclusive para
administradores. Para mais informações, consulte Cotas e limites.
Antes de começar
Se você tiver feito login pela federação de identidade de colaboradores, os comandos da Google Cloud CLI e as novas sessões de login do console do Google Cloud poderão ser limitados. Para realizar essas etapas quando sua cota for excedida, use uma conta de administrador que não seja autenticada pela federação de identidade de colaboradores, como uma conta de superadministrador do Cloud Identity de acesso de emergência.
Etapa 1: confirmar se a cota foi esgotada
No console do Google Cloud , acesse IAM e administrador > Cotas, defina o seletor de recursos como sua organização (não um projeto) e selecione Solicitações de troca de token do pool de colaboradores.
Acessar as cotas do IAM e do administrador
Etapa 2: identificar a origem do tráfego
As trocas de token limitadas são rejeitadas antes da validação das credenciais, portanto, não aparecem nos Registros de auditoria do Cloud. Para identificar a origem do tráfego, use um dos seguintes métodos:
- Analise os registros de login do IdP: no provedor de identidade, como o registro do sistema do Okta ou os registros de login do Microsoft Entra ID, verifique se há um aplicativo, principal de serviço ou conta de usuário específico emitindo tokens a uma taxa incomumente alta.
- Revise as configurações de carga de trabalho: verifique os jobs automatizados, os pipelines de CI/CD, os agentes daemon e as cargas de trabalho do GKE configurados com um arquivo de configuração de credenciais de colaboradores.
Etapa 3: conter o tráfego
Escolha a opção que resolve o tráfego com o menor número de interrupções para sua equipe:
| Ação | Efeito nos usuários |
|---|---|
| Interrompa a carga de trabalho (reduza a implantação para zero, exclua o job ou revogue o cliente no IdP). | Nenhuma. Recomendado quando é possível identificar a carga de trabalho específica. |
| Desative o login programático no pool de colaboradores. | Bloqueia todas as trocas de token programáticas do pool, incluindo
gcloud e kubectl para os usuários humanos.
Google Cloud O login no console continua funcionando.Recomendado quando não é possível localizar a carga de trabalho imediatamente. |
| Desativar o pool ou provedor | Bloqueia a autenticação para todo o pool ou provedor de força de trabalho. |
Para desativar o login programático:
gcloud iam workforce-pools update WORKFORCE_POOL_ID \
--location=global \
--disable-programmatic-signin
Depois de interromper a carga de trabalho problemática, reative o login programático
executando o comando com a flag --no-disable-programmatic-signin.
Etapa 4: evitar recorrência
- Migre cargas de trabalho automatizadas para a federação de identidade da carga de trabalho.
- Tente novamente as solicitações limitadas com espera exponencial e instabilidade. Loops de repetição apertados aumentam a saturação e estendem a interrupção.
- Alerta em 80% da sua cota para que você receba um aviso antes da saturação.
- Se a demanda em estado estável exceder o limite regularmente, recomendamos que você solicite um aumento de cota pelo Cloud Customer Care antes de precisar dele.
Erros no login
Esta seção fornece sugestões para corrigir erros comuns que um usuário de federação de identidade de colaboradores pode encontrar ao fazer login.
Erros comuns de login
A credencial especificada é rejeitada pela condição do atributo
Esse erro ocorre quando a condição de atributo definida no provedor de pool de identidade da força de trabalho não é atendida.
Por exemplo, considere a seguinte condição de atributo:
SAML
'gcp-users' in assertion.attributes.groups
OIDC
'gcp-users' in assertion.groups
Nesse caso, você vai ver o erro se a lista de grupos enviados no atributo groups
pelo IdP não contiver gcp-users.
Para resolver esse erro, siga estas etapas:
Descreva o provedor que foi usado para fazer login e verifique se o
attributeConditionestá correto. Para mais informações sobre operações compatíveis com condições, consulte a Definição de idioma.Siga as etapas em inspecionar a resposta do IdP para ver os atributos retornados pelo IdP e confirmar se a condição do atributo está correta e precisa.
Faça login no Admin Console do IdP e verifique se os atributos do IdP referenciados na condição estão configurados corretamente. Se necessário, consulte a documentação do IdP.
O atributo mapeado deve ser do tipo STRING
Esse erro ocorre para um provedor de pool de identidade de força de trabalho SAML quando o atributo especificado na mensagem de erro precisa ser uma STRING de valor único, mas é mapeado para uma lista no mapeamento de atributos.
Por exemplo, considere um provedor de pool de identidade de força de trabalho SAML que
tenha o mapeamento de atributos, attribute.role=assertion.attributes.userRole. Em uma declaração
SAML, um Attribute pode ter várias tags AttributeValue, conforme mostrado
no exemplo a seguir. Assim, todos os atributos SAML são considerados listas, portanto,
assertion.attributes.userRole é uma lista.
<saml:Attribute Name="userRole">
<saml:AttributeValue>
security-admin
</saml:AttributeValue>
<saml:AttributeValue>
user
</saml:AttributeValue>
</saml:Attribute>
Neste exemplo, você pode ver o seguinte erro:
The mapped attribute 'attribute.role' must be of type STRING
Para resolver esse problema, siga estas etapas:
Descreva o provedor usado para fazer login e identifique o atributo do IdP definido no
attributeMapping. Compare o atributo com o atributo apresentado na mensagem de erro. No exemplo anterior, um atributo do IdP chamadouserRoleé mapeado para o atributorole, e o atributoroleaparece no exemplo de erro.Ao atualizar o mapeamento de atributos, considere o seguinte:
Se o atributo que causa o erro tiver um valor de lista, identifique um atributo alternativo, estável e com valor de string. Em seguida, atualize o mapeamento de atributos para usá-lo fazendo referência ao primeiro item. No exemplo anterior, se
myRolefosse identificado como o atributo IdP de valor único alternativo, o mapeamento de atributos seria o seguinte:attribute.role=assertion.attributes.myRole[0]
Como alternativa, se o atributo tiver valor único, atualize o mapeamento de atributo para usar o primeiro item da lista. No exemplo anterior, se
userRoletiver apenas um papel, use o seguinte mapeamento:attribute.role=assertion.attributes.userRole[0]
Para gerar um identificador estável de valor único da lista, consulte Definição de idioma e atualize o mapeamento de atributos.
Consulte a seção Inspecionar a resposta do IdP para ver a resposta retornada pelo IdP.
Não foi possível obter um valor para google.subject da credencial especificada
Esse erro ocorre quando não é possível mapear a declaração necessária google.subject
usando o
mapeamento de atributos
definido na configuração do provedor de pool de federação de identidade da força de trabalho.
Para resolver esse erro, siga estas etapas:
Descreva o provedor e inspecione o
attributeMapping. Identifique o mapeamento configurado paragoogle.subject. Se o mapeamento não estiver correto, atualize o provedor do pool de identidade da força de trabalho.Consulte a seção Inspecionar a resposta do IdP para ver a resposta retornada pelo IdP. Inspecione o valor do atributo da resposta do IdP que é mapeado para
google.subjectnos mapeamentos de atributos.Se o valor estiver vazio ou incorreto, faça login no Admin Console do IdP e inspecione os atributos configurados. Em relação aos atributos, verifique se o usuário afetado tem dados correspondentes no seu IdP. Atualize a configuração do IdP para corrigir os atributos ou as informações do usuário.
Tente fazer login novamente.
O tamanho dos atributos mapeados excede o limite
O seguinte erro ocorre quando um usuário federado tenta fazer login:
The size of the entire mapped attributes exceeds the 16 KB limit.
Para resolver esse problema, peça ao administrador do IdP para reduzir o número de atributos emitidos pelo IdP. Seu IdP só precisa emitir atributos necessários para federar usuários ao Google Cloud. Para saber mais sobre os limites de mapeamento de atributos, consulte mapeamentos de atributos.
Por exemplo, se o IdP emitir um grande número de google.groups que são atributos mapeados
no provedor de pool de identidades de colaboradores, uma tentativa de login poderá falhar.
Peça ao administrador para restringir o número de grupos emitidos pelo IdP.
A contagem de grupos excede o limite
O seguinte erro ocorre quando um usuário federado tenta fazer login:
The current count of GROUPS_COUNT mapped attribute google.groups exceeds the GROUPS_COUNT_LIMIT count limit. Either modify your attribute mapping or the incoming assertion to produce a mapped attribute that has fewer than GROUPS_COUNT_LIMIT groups.
Esse erro inclui os seguintes valores:
GROUPS_COUNT: a contagem de grupos que o IdP emiteGROUPS_COUNT_LIMIT: limite de contagem do Google Cloud para grupos
Esse erro ocorre quando o número de grupos emitidos pelo IdP excede o limite doGoogle Cloud. Os grupos são mapeados para Google Cloud usando o atributo google.groups.
Para resolver esse problema, peça ao administrador para reduzir o número de grupos emitidos pelo IdP. Seu IdP só precisa emitir grupos que são usados para federar usuários ao Google Cloud. Saiba mais sobre os limites relacionados a grupos em mapeamentos de atributos.
400. Isto é um erro
Esse erro ocorre quando a solicitação não é recebida como esperado ou é formada incorretamente.
Para resolver esse erro, siga estas etapas:
Siga as etapas na seção Informe seus usuários sobre como fazer login para verificar se você está seguindo as etapas corretas.
Compare a configuração do provedor de pool de identidade da força de trabalho com a configuração do IdP.
Erros de login de atributos extras
Nesta seção, damos sugestões para corrigir erros ao usar atributos extras.
Falha no login quando atributos extras são configurados
Se você tiver configurado atributos extras, qualquer problema de configuração, como um ID do cliente, uma chave secreta do cliente ou um URI do emissor incorretos, vai causar uma falha na tentativa de login.
Para resolver esse erro, siga estas etapas:
- Descreva o provedor e verifique se o ID do cliente e o URI do emissor estão corretos.
- Verifique se a chave secreta do cliente é válida e não expirou.
- No IdP, verifique se o aplicativo tem as permissões necessárias.
Os grupos da declaração SAML ou OIDC são ignorados
Quando atributos extras são configurados, a federação de identidade de colaboradores ignora as informações de grupo fornecidas diretamente nas declarações SAML ou OIDC. Em vez disso, ele usa apenas os grupos buscados usando o canal de retorno (por exemplo, usando a API Microsoft Graph).
Se os usuários não estiverem vendo os grupos esperados, verifique se eles foram recuperados corretamente usando o canal de retorno e se os filtros de atributos estão configurados corretamente.
Erros de login no OIDC
Esta seção fornece sugestões para corrigir erros específicos do OIDC que um usuário de federação de identidade de colaboradores pode encontrar ao fazer login.
Erro ao se conectar ao emissor da credencial
Esse erro ocorre quando um provedor de pool de identidade da força de trabalho OIDC não pode acessar o documento de descoberta do OIDC ou URI JWKS.
Para resolver esse erro, siga estas etapas:
Descreva o provedor e inspecione o
issuerUriconfigurado. Para criar o URL do documento de descoberta, anexe/.well-known/openid-configurationao URI do emissor. Por exemplo, seissuerUriforhttps://example.com, o URL do documento de descoberta seráhttps://example.com/.well-known/openid-configuration.Abra o URL do documento de descoberta em uma janela de navegação anônima.
Se o URL não abrir ou o navegador exibir um erro
404, consulte a documentação do IdP para identificar o URI do emissor correto. Se necessário, atualize oissuerUrino provedor de pool de identidade da força de trabalho.Se o IdP for executado no local, consulte a documentação dele para provisioná-lo para acesso na Internet.
Se o URL for aberto, verifique as seguintes condições:
- Verifique se o URL não redireciona muitas vezes antes de exibir o documento de descoberta. Se isso acontecer, consulte o administrador do IdP para corrigir o problema.
- Verifique o tempo de resposta do IdP. Consulte o administrador do IdP para reduzir a latência da resposta.
- O documento de descoberta aberto precisa estar no formato JSON.
Procure um campo
jwks_urino JSON.- Verifique se o valor do URL associado também é aberto.
- Verifique se o URL atende às condições descritas anteriormente neste guia.
Tente fazer login novamente.
Erros de login via SAML
Esta seção fornece sugestões para corrigir erros específicos do SAML que um usuário de federação de identidade de colaboradores pode encontrar ao fazer login.
Falha ao verificar a assinatura em SAMLResponse
Esse erro ocorre para um provedor de pool de identidade de força de trabalho SAML quando a assinatura na resposta do IdP não pode ser verificada usando qualquer um dos certificados X.509 fornecidos no XML de metadados do IdP que você configurou no provedor de pool de identidade da força de trabalho. Uma causa comum desse erro é que o certificado de verificação no IdP foi alternado, mas você não atualizou a configuração do provedor de pool de identidade da força de trabalho com o arquivo XML de metadados do IdP mais recente.
Para resolver esse erro, siga estas etapas:
Opcional: siga as etapas em inspecionar a resposta do IdP para ver a resposta retornada pelo IdP e localizar o campo
X509Certificate. Descreva o provedor que você usou para fazer login e inspecione o campoX509Certificatepresente no valoridpMetadataXmldefinido no provedor do pool de identidades de colaboradores. Compare o certificado com o que foi visto na resposta retornada pelo IdP. Os certificados precisam ser iguais.Faça login no Admin Console do IdP e faça o download do XML de metadados mais recente.
Atualize o provedor de pool de identidade da força de trabalho com o XML de metadados do IdP transferido por download.
Tente fazer login novamente.
O destinatário na declaração SAML não está definido como o URL do ACS correto
Esse erro ocorre para um provedor de pool de federação de identidade de força de trabalho SAML quando a resposta
do IdP contém um valor incorreto para o campo Recipient na
tag SubjectConfirmationData.
Para resolver esse erro, atualize Recipient URL / Redirect URL ou o
campo equivalente na configuração do IdP para usar o URL de redirecionamento descrito
em
Configurar URLs de redirecionamento no seu IdP e tente fazer login novamente.
Siga as etapas em inspecionar a resposta do IdP para ver a
resposta retornada pelo IdP e confirme se o campo Recipient está
correto.
Por exemplo, para o provedor de pool de identidade de força de trabalho locations/global/workforcePools/example-pool/providers/example-provider, o Recipient que contém o URL de redirecionamento apareceria na resposta SAML do IdP da seguinte maneira:
<SubjectConfirmationData Recipient="https://auth.cloud.google/signin-callback/locations/global/workforcePools/example-pool/providers/example-provider"
O destino SAMLResponse não corresponde ao URL de callback do RP
Esse erro ocorre para um provedor de pool de identidade de força de trabalho SAML quando a resposta
do IdP contém um valor incorreto para o campo Destination na
tag Response.
Para resolver esse erro, atualize Destination URL / Redirect URL ou o
campo equivalente na configuração do IdP para usar o URL de redirecionamento descrito
em
Configurar URLs de redirecionamento no seu IdP.
Siga as etapas em inspecionar a resposta do IdP para ver a
resposta retornada pelo IdP e confirme se o campo Destination está
correto.
Por exemplo, para um provedor de pool de identidade de força de trabalho
locations/global/workforcePools/example-pool/providers/example-provider, o
Destination que contém o URL de redirecionamento apareceria na resposta SAML do IdP da
seguinte maneira:
<Response Destination="https://auth.cloud.google/signin-callback/locations/global/workforcePools/example-pool/providers/example-provider"
Declaração inválida: NameID ausente ou vazio
Esse erro ocorre quando a resposta SAML recebida do IdP não contém o campo NameId ou tem um valor vazio.
Para resolver esse erro, consulte a documentação do IdP para configurá-lo para enviar
o NameID, que é o foco de uma declaração SAML, geralmente o usuário que
está sendo autenticado.
Siga as etapas em inspecionar a resposta do IdP para ver a
resposta retornada pelo IdP e o NameID definido.
Todos os <AudienceRestriction>s precisam conter o ID da entidade de RP SAML.
Esse erro ocorre quando as tags AudienceRestriction na resposta SAML do
IdP não definem uma tag Audience com um valor que represente o ID da entidade
do provedor de pool de identidade da força de trabalho.
Para resolver esse erro, siga estas etapas:
Consulte a documentação do IdP sobre como configurar o público-alvo nas tags
AudienceRestrictionenviadas na resposta SAML. Normalmente, o público-alvo é configurado ao definir o campoEntity IDouAudiencena configuração do IdP. Consulte a seção do SAML Criar um provedor de pool de identidades de força de trabalho para ver o valorSP Entity IDque precisa ser definido.Após atualizar a configuração do IdP, tente fazer login novamente.
Siga as etapas em inspecionar a resposta do IdP para ver a
resposta retornada pelo IdP e os AudienceRestrictions definidos.
Erros de login do SCIM
Nesta seção, descrevemos como resolver erros específicos do SCIM que um usuário da federação de identidade de colaboradores pode encontrar ao fazer login.
Não foi possível encontrar o locatário do SCIM
Esse erro ocorre quando um usuário tenta fazer login usando um provedor de pool de identidades de colaboradores configurado para usar o SCIM, mas nenhum locatário do SCIM está configurado para esse provedor.
Quando isso acontece, os usuários recebem o seguinte erro ao tentar fazer login:
There was an issue signing in with your identity provider.
Para resolver esse erro, faça o seguinte no seu provedor de identidade:
- Configure um locatário do SCIM e um token no Google Cloud (Microsoft Entra ID | Okta).
- Vincule o provedor a um locatário do SCIM (Microsoft Entra ID | Okta).
O login falha quando o uso do SCIM está ativado para usuários e grupos
Quando --scim-usage é definido como enabled-for-users-groups, as tentativas de login na Web e do OAuth podem falhar com as seguintes mensagens de erro:
Usuário do SCIM não encontrado ou inativo:
- Erro:
The workforce identity pool provider is configured to use identity information that is provided using SCIM, but a SCIM User could not be associated with the google.subject from the given credential.ou... the SCIM User associated with the google.subject from the given credential is not active. - Causa: o usuário não foi sincronizado com o Google Cloud usando o SCIM, o
google.subjectmapeado no provedor não corresponde ao mapeamento de usuários do SCIM ou o usuário está marcado comoactive: falseno IdP. - Resolução: no IdP, verifique se o usuário foi provisionado usando o SCIM, se o status dele está ativo e se o mapeamento de atributos do provedor e o mapeamento de declarações do locatário do SCIM para
google.subjectse referem à mesma identidade.
- Erro:
Erro de avaliação de CEL ou de mapeamento de declarações:
- Erro:
Failed to map attributes from the given credential with SCIM Tenant config. - Causa: uma expressão CEL em
--claim-mappingé inválida ou falhou durante a avaliação. - Resolução: revise as expressões
--claim-mappingdo locatário do SCIM para garantir uma sintaxe CEL válida e nomes de atributos compatíveis.
- Erro:
Os limites de tamanho dos atributos mapeados foram excedidos:
- Erro:
The size of SCIM mapped attribute google.display_name exceeds the 100 bytes limit.ouThe size of entire SCIM mapped attributes exceeds the 16 kB limit. - Causa: um atributo mapeado individual excedeu o limite de tamanho (por exemplo, 100 bytes para
google.display_name, 32 bytes paragoogle.posix_username, 127 bytes paragoogle.subject) ou o total de declarações mapeadas serializadas excedeu 16 kB. - Resolução: ajuste os mapeamentos de declarações do locatário do SCIM ou atualize os valores de atributos do IdP para permanecer dentro dos limites permitidos.
- Erro:
Erros de provisionamento e sincronização do SCIM
Nesta seção, descrevemos como resolver problemas com o provisionamento e a sincronização do SCIM na federação de identidade de colaboradores.
Falha na autenticação do token do SCIM (HTTP 401 ou 403)
Esse erro ocorre quando os registros do provedor de identidade (IdP) relatam falhas de autenticação (HTTP 401 Unauthorized ou HTTP 403 Forbidden). As causas comuns incluem:
- O token do SCIM está ausente, é inválido ou expirou.
- O token do SCIM contém espaços extras.
- A solicitação não tem o cabeçalho
Authorization: Bearer <TOKEN>. - O token SCIM não tem permissões suficientes.
Para resolver esse problema, faça o seguinte:
- Na configuração de provisionamento do IdP, verifique se o token do SCIM corresponde ao token secreto gerado no Google Cloud sem espaços em branco extras.
Se o token for perdido ou inválido, gere um novo token do SCIM:
gcloud iam workforce-pools providers scim-tenants tokens create SCIM_TOKEN_ID \ --workforce-pool="WORKFORCE_POOL_ID" \ --provider="PROVIDER_ID" \ --scim-tenant="SCIM_TENANT_ID" \ --location="global"Substitua:
SCIM_TOKEN_ID: um ID para o novo token SCIM.WORKFORCE_POOL_ID: o ID do pool de identidade de colaboradores.PROVIDER_ID: o ID do provedor do pool de colaboradores.SCIM_TENANT_ID: o ID do locatário do SCIM.
Atualize o token secreto na configuração do IdP.
Limite de taxa excedido (HTTP 429: muitas solicitações)
Esse erro ocorre quando as taxas de solicitação do IdP excedem a cota do locatário do SCIM. Por padrão, as solicitações de gravação e leitura são limitadas a 3.000 solicitações por locatário do SCIM por organização por minuto, o que equivale a 50 consultas por segundo (QPS). Para mais informações, consulte Cotas e limites.
Para resolver esse problema, faça o seguinte:
- Verifique se a taxa de solicitação de sincronização do IdP está dentro dos limites de cota.
- No console do Google Cloud , acesse IAM e administrador > Cotas e filtre
por
iamscim.googleapis.compara monitorar o uso de cotas. - Se você precisar de uma capacidade de processamento maior, solicite um aumento de cota no console do Google Cloud .
Falha na criação do locatário do SCIM
Esse erro ocorre quando o comando gcloud iam workforce-pools providers scim-tenants create falha.
As causas mais comuns incluem:
- Já existe um locatário do SCIM no pool de força de trabalho. Cada pool de colaboradores aceita apenas um locatário do SCIM.
- Um locatário do SCIM excluído recentemente ainda está no período de exclusão reversível de 30 dias.
- Você não tem o papel de Administrador de pool de força de trabalho do IAM (
roles/iam.workforcePoolAdmin). - A flag
--claim-mappingcontém expressões da Common Expression Language (CEL) não compatíveis.
Para resolver esse problema, faça o seguinte:
- Verifique se você tem o papel de Administrador de pool de força de trabalho do IAM (
roles/iam.workforcePoolAdmin). Liste os locatários do SCIM para verificar se um locatário já existe:
gcloud iam workforce-pools providers scim-tenants list \ --workforce-pool="WORKFORCE_POOL_ID" \ --provider="PROVIDER_ID" \ --location="global"Substitua:
WORKFORCE_POOL_ID: o ID do pool de identidade de colaboradores.PROVIDER_ID: o ID do provedor do pool de colaboradores.
Se um locatário excluído anteriormente for excluído de maneira reversível, exclua-o permanentemente usando a flag
--hard-delete:gcloud iam workforce-pools providers scim-tenants delete SCIM_TENANT_ID \ --workforce-pool="WORKFORCE_POOL_ID" \ --provider="PROVIDER_ID" \ --location="global" \ --hard-deleteSubstitua
SCIM_TENANT_IDpelo ID do locatário do SCIM.Verifique se
--claim-mappingusa apenas expressões CEL compatíveis. Para mais informações, consulte Mapeamento de declarações.
Falha na criação do token SCIM
Esse erro ocorre quando o comando gcloud iam workforce-pools providers scim-tenants tokens create falha.
As causas mais comuns incluem:
- O locatário do SCIM já tem o máximo de dois tokens do SCIM.
- Você não tem o papel de Administrador de pool de força de trabalho do IAM (
roles/iam.workforcePoolAdmin).
Para resolver esse problema, faça o seguinte:
- Verifique se você tem o papel de Administrador de pool de força de trabalho do IAM (
roles/iam.workforcePoolAdmin). Liste os tokens SCIM atuais para verificar se o limite de dois tokens foi atingido:
gcloud iam workforce-pools providers scim-tenants tokens list \ --workforce-pool="WORKFORCE_POOL_ID" \ --provider="PROVIDER_ID" \ --scim-tenant="SCIM_TENANT_ID" \ --location="global"Substitua:
WORKFORCE_POOL_ID: o ID do pool de identidade de colaboradores.PROVIDER_ID: o ID do provedor do pool de colaboradores.SCIM_TENANT_ID: o ID do locatário do SCIM.
Se o locatário do SCIM já tiver dois tokens, exclua um token não utilizado ou inválido:
gcloud iam workforce-pools providers scim-tenants tokens delete SCIM_TOKEN_ID \ --workforce-pool="WORKFORCE_POOL_ID" \ --provider="PROVIDER_ID" \ --scim-tenant="SCIM_TENANT_ID" \ --location="global"Substitua
SCIM_TOKEN_IDpelo ID do token SCIM a ser excluído.Depois de excluir o token, tente criar o novo token do SCIM novamente.
Conflito de mapeamento de atributos duplicados (conflito HTTP 409)
Esse erro ocorre quando os registros do provedor de identidade (IdP) relatam um
HTTP 409 Conflict durante a sincronização porque o IdP envia valores duplicados
para google.subject ou google.group ou valores não exclusivos de userName ou
displayName.
Para resolver esse problema, faça o seguinte:
- No console de administração do IdP, verifique se os atributos mapeados para
google.subjectegoogle.groupproduzem valores que não se sobrepõem. - Verifique se cada usuário tem um
userNameexclusivo e se cada grupo tem umdisplayNameexclusivo.
Falha nas solicitações PATCH do Microsoft Entra ID
Esse erro ocorre quando as atualizações de usuário ou as solicitações PATCH do Microsoft Entra ID
falham porque o URL do locatário não tem o
parâmetro de consulta ?aadOptscim062020, que é obrigatório para solicitações PATCH em conformidade com a RFC.
Para resolver esse problema, faça o seguinte:
- No Microsoft Entra ID, acesse seu aplicativo empresarial e selecione Provisionamento > Gerenciar provisionamento > Credenciais de administrador.
No campo URL do locatário, adicione
?aadOptscim062020ao URI de base:https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID?aadOptscim062020Substitua
SCIM_TENANT_UIDpelo ID exclusivo do seu locatário do SCIM.Clique em Testar conexão e salve a configuração.
O acesso ou compartilhamento com base em usuários ou grupos não está funcionando
Esse problema ocorre quando os usuários sincronizados não conseguem acessar os recursos do Google Cloud ou quando o compartilhamento de notebooks no Gemini Notebook para empresas ou de agentes no app Gemini Enterprise falha.
As causas mais comuns incluem:
- Falhas ou atrasos silenciosos de sincronização do IdP.
- Mapeamentos de declarações inconsistentes entre o provedor (
--attribute-mapping) e o locatário do SCIM (--claim-mapping). - Mudanças no IdP em atributos mapeados para
google.subjectougoogle.group. O Google Cloud espera que os valores mapeados para esses atributos sejam imutáveis. - O uso do SCIM (
--scim-usage=enabled-for-users-groupsou--scim-usage=enabled-for-groups) não está ativado no provedor do pool de força de trabalho que é proprietário do locatário do SCIM.
Para resolver esse problema, faça o seguinte:
Verifique a sincronização e a associação: confirme se os usuários, grupos e associações de grupos foram sincronizados com o Google Cloud:
Verifique a sincronização de usuários:
curl -G -H "Authorization: Bearer SCIM_TOKEN" \ "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Users" \ --data-urlencode 'filter=userName eq "USER_NAME"'Verifique a sincronização de grupos:
curl -G -H "Authorization: Bearer SCIM_TOKEN" \ "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Groups" \ --data-urlencode 'filter=displayName eq "GROUP_NAME"'Verificar a associação ao grupo: confirme se um usuário é membro de um grupo:
curl -G -H "Authorization: Bearer SCIM_TOKEN" \ "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Groups" \ --data-urlencode 'filter=id eq "GROUP_ID" and members eq "USER_ID"'Se o usuário for um membro do grupo, a resposta retornará
totalResults: 1. Se o usuário não for um membro, a resposta vai retornartotalResults: 0.
Substitua:
SCIM_TOKEN: seu token secreto do SCIM.SCIM_TENANT_UID: o ID exclusivo do locatário do SCIM.USER_NAME: o nome de usuário do usuário sincronizado.GROUP_NAME: o nome de exibição do grupo sincronizado.GROUP_ID: o ID do SCIM do grupo sincronizado, retornado no campoidda resposta da consulta do grupo.USER_ID: o ID do SCIM do usuário sincronizado, retornado no campoidda resposta da consulta do usuário.
Verifique os mapeamentos de declarações: verifique se o atributo mapeado para
google.subjectno provedor (por exemplo,google.subject=assertion.email.lowerAscii()) corresponde ao mapeamento de identidade no locatário do SCIM (por exemplo,google.subject=user.emails[0].value.lowerAscii()). Como os mapeamentos de declarações são imutáveis, se eles forem inconsistentes, você precisará fazer a exclusão irreversível do locatário do SCIM e recriá-lo com o mapeamento correto.Garanta a imutabilidade do identificador: verifique se os atributos do IdP mapeados para
google.subjectegoogle.groupnão mudaram. O Google Cloud trata os valores mapeados para esses atributos como identificadores imutáveis. Se um valor de atributo tiver sido alterado no IdP, reverta a alteração no IdP ou exclua permanentemente o usuário ou grupo afetado do IdP e recrie-o com o novo valor para que o identificador corresponda ao que o Google Cloud espera.Verifique o uso do SCIM no provedor: verifique o campo
scimUsageno provedor do pool de colaboradores que é proprietário do locatário do SCIM:gcloud iam workforce-pools providers describe PROVIDER_ID \ --workforce-pool="WORKFORCE_POOL_ID" \ --location="global"Substitua:
PROVIDER_ID: o ID do provedor do pool de colaboradores.WORKFORCE_POOL_ID: o ID do pool de identidade de colaboradores.
Na saída, confirme se
scimUsageestá definido comoENABLED_FOR_USERS_GROUPS(recomendado) ouENABLED_FOR_GROUPS. SescimUsagefor omitido ou definido comoSCIM_USAGE_UNSPECIFIED, as declarações de usuário e grupo sincronizadas com o SCIM não serão avaliadas para verificações de acesso do IAM.Ativar o uso do SCIM no provedor: se o uso do SCIM não estiver ativado, execute o comando de atualização para seu tipo de provedor. Recomendamos usar
enabled-for-users-groups. Para mais informações sobre os modos de uso do SCIM, consulte Considerações sobre o provisionamento do SCIM.OIDC
gcloud iam workforce-pools providers update-oidc PROVIDER_ID \ --workforce-pool="WORKFORCE_POOL_ID" \ --location="global" \ --scim-usage="enabled-for-users-groups"SAML
gcloud iam workforce-pools providers update-saml PROVIDER_ID \ --workforce-pool="WORKFORCE_POOL_ID" \ --location="global" \ --scim-usage="enabled-for-users-groups"
As mudanças feitas no IdP estão atrasadas ou não estão sendo refletidas
Esse problema ocorre quando as atualizações do IdP para usuários, associações a grupos ou exclusões não aparecem imediatamente no Google Cloud.
Como o SCIM é baseado em push, as atualizações dependem da programação de sincronização do IdP. Por exemplo, o Microsoft Entra ID é sincronizado aproximadamente a cada 40 minutos.
Para resolver esse problema, faça o seguinte:
- Aguarde o próximo ciclo de sincronização programado do IdP.
- Para implementar mudanças imediatamente, acione uma sincronização on demand no console de administração do IdP.
O provisionamento de usuários falha devido ao formato do e-mail
Esse erro ocorre quando usuários específicos não são sincronizados com o Google Cloud, e
os registros do provedor de identidade (IdP) informam um HTTP 400 Bad Request com um
erro de SCIM invalidValue.
Google Cloud O SCIM exige exatamente um e-mail de trabalho por usuário. O provisionamento
falhará se o IdP enviar vários e-mails ou se o e-mail não for do tipo work.
Para resolver esse problema, configure o mapeamento de atributos do IdP para enviar apenas o e-mail de trabalho principal.
Falha nas atualizações de grupo (HTTP PUT não é compatível)
Esse erro ocorre quando as atualizações de grupo falham porque o cliente usa HTTP PUT,
que não é compatível. A API SCIM do Google Cloud aceita apenas o método HTTP PATCH para atualizações de grupos.
Para resolver esse problema, configure o IdP ou o cliente personalizado para usar o HTTP PATCH
para atualizações de grupo.
A atualização do provedor falha com configurações mutuamente exclusivas
Esse erro ocorre quando a criação ou atualização do provedor falha com uma das seguintes mensagens:
Select one of scim_usage - ENABLED_FOR_USERS_GROUPS or extra_attributes_oauth2_client, but not both.Select one of scim_usage or extended_attributes_oauth2_client, but not both.
A configuração de --scim-usage=enabled-for-users-groups é mutuamente exclusiva com atributos extras (extra_attributes_oauth2_client) e atributos estendidos (extended_attributes_oauth2_client).
Para resolver esse problema, remova a configuração conflitante de atributos extras ou estendidos do provedor ou mude a configuração --scim-usage.
Erros de troca de token da API Cloud OAuth
Quando uma solicitação de troca de token falha, a API Cloud OAuth retorna um status HTTP
400 Bad Request ou 401 Unauthorized com uma resposta JSON de erro do OAuth 2.0 (RFC 6749). O campo error indica um dos seguintes códigos de erro:
| Código do erro | Descrição | Ações |
|---|---|---|
invalid_request |
A solicitação não tem um parâmetro obrigatório, inclui um valor de parâmetro inválido, inclui um parâmetro mais de uma vez ou está malformada. |
Verifique se todos os parâmetros codificados por URL necessários (grant_type,
code ou refresh_token, redirect_uri)
foram fornecidos.
|
invalid_client |
Falha na autenticação do cliente. |
Verifique se o client_id e o client_secret do OAuth registrados correspondem, se o cliente OAuth está ativado para o pool de identidades de colaboradores e se o cabeçalho Authorization: Basic está codificado em Base64 corretamente.
|
invalid_grant |
O código de autorização ou o token de atualização fornecido é inválido, expirou, foi revogado, não corresponde ao URI de redirecionamento usado na solicitação de autorização ou foi emitido para outro cliente. | Verifique se o código ou token não expirou ou foi trocado anteriormente. |
unauthorized_client |
O cliente OAuth autenticado não tem autorização para usar o
grant_type solicitado.
|
Verifique se o registro do cliente OAuth permite concessões de código de autorização ou token de atualização. |
unsupported_grant_type |
O tipo de permissão de acesso não é aceito pelo servidor de autorização. |
Defina grant_type como authorization_code ou
refresh_token.
|
invalid_scope |
O escopo solicitado é inválido, desconhecido, incorreto ou excede os escopos concedidos pelo proprietário do recurso. | Verifique se os escopos solicitados correspondem aos configurados no cliente OAuth e se são válidos para o aplicativo. |
resource_exhausted |
A solicitação excedeu a cota de troca de tokens da API Cloud OAuth. | Verifique o uso da API no console do Google Cloud ou solicite um aumento de cota. |
Erros de informações do usuário e grupos do Cloud OAuth
Quando uma solicitação para o endpoint /userinfo ou /groups falha, a API Cloud OAuth retorna um status HTTP 400 Bad Request, 401 Unauthorized ou 403 Forbidden com uma resposta de erro de token do portador do OAuth 2.0 (RFC 6750 / OpenID Connect Core).
O campo error indica um dos seguintes códigos de erro:
| Código do erro | Status HTTP | Descrição | Ações |
|---|---|---|---|
invalid_request |
400 Bad Request / 401 Unauthorized |
A solicitação não tem o cabeçalho Authorization obrigatório ou o cabeçalho está
malformado (por exemplo, não começa com Bearer).
|
Verifique se o cabeçalho Authorization: Bearer ACCESS_TOKEN está
formatado corretamente.
|
invalid_token |
401 Unauthorized |
O token de acesso fornecido é inválido, expirou ou foi revogado. |
Atualize o token de acesso usando a concessão refresh_token ou repita o
fluxo do código de autorização.
|
insufficient_scope |
403 Forbidden |
O token de acesso não tem o escopo openid necessário ou o locatário do token
não corresponde à organização especificada no URL do endpoint com escopo da organização.
|
Verifique se o token foi solicitado com o escopo openid obrigatório e se você está chamando o endpoint correto.
|