Resolver problemas com a federação de identidade de colaboradores

Nesta página, mostramos como resolver problemas comuns com a federação de identidade da força de trabalho.

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.

Importante: se você estiver solicitando o arquivo HAR dos usuários, peça para eles limparem todas as informações de identificação pessoal (PII) e os cookies do arquivo HAR antes do envio.

SAML

Para inspecionar a resposta do IdP SAML, siga estas etapas:

1. Localize o valor do parâmetro de solicitação SAMLResponse no arquivo HAR registrado no URL com o caminho /signin-callback.
2. 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.

1. Procure o parâmetro de solicitação id_token no arquivo HAR que é registrado em um URL com o caminho /signin-callback.
2. 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 siga estas etapas:

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.

Revisar registros

Para determinar se Google Cloud está se comunicando com seu 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.
• Inspecione os tokens gerados pelo seu IdP. Para saber como gerar um token do seu IdP, consulte a documentação dele.
• Analise 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 da força de trabalho.

É possível ativar o registro de auditoria detalhado ao criar o provedor do pool de identidades da força de trabalho. Para ativar o registro de auditoria detalhado, adicione a flag --detailed-audit-logging ao criar o provedor de pool de identidades da força de trabalho.

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 força de trabalho 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. Tente novamente mais tarde.

Esse erro ocorre quando você atinge o limite da cota para recursos do pool da força de trabalho. Entre em contato com o representante da sua conta do Google Cloud para pedir um aumento de cota.

Erros no login

Esta seção fornece sugestões para corrigir erros comuns que um usuário da federação de identidade da força de trabalho 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:

1. Descreva o provedor que foi usado para fazer login e verifique se o attributeCondition está correto. Para mais informações sobre operações compatíveis com condições, consulte a Definição de idioma.

2. 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.

3. 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:

1. 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 chamado userRole é mapeado para o atributo role, e o atributo role aparece no exemplo de erro acima.

2. Siga as orientações abaixo para atualizar o mapeamento de atributos:

   Observação: somente google.groups aceita uma lista.

   • 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 myRole fosse 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 userRole tiver 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:

1. Descreva o provedor e inspecione o attributeMapping. Identifique o mapeamento configurado para google.subject. Se o mapeamento não estiver correto, atualize o provedor do pool de identidade da força de trabalho.

2. 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.subject nos 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.

3. Tente fazer login novamente.

O tamanho dos atributos mapeados excede o limite

O seguinte erro ocorreu quando um usuário federado tentou 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 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 identidade da força de trabalho, 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 ocorreu quando um usuário federado tentou 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 emite

• GROUPS_COUNT_LIMIT:limite de contagem de Google Cloudpara grupos

Esse erro ocorreu quando o número de grupos emitidos pelo IdP excedeu o limite de Google 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. O IdP só precisa emitir grupos usados para federar usuários no 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:

1. Siga as etapas na seção Informe seus usuários sobre como fazer login para verificar se você está seguindo as etapas corretas.

2. Compare a configuração do provedor de pool de identidade da força de trabalho com a configuração do IdP.

Erros de login no OIDC

Esta seção fornece sugestões para corrigir erros específicos do OIDC que um usuário da Federação de identidade da força de trabalho 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:

1. Descreva o provedor e inspecione o issuerUri configurado. Para criar o URL do documento de descoberta, anexe /.well-known/openid-configuration ao URI do emissor. Por exemplo, se issuerUri for https://example.com, o URL do documento de descoberta será https://example.com/.well-known/openid-configuration.

2. Abra o URL do documento de descoberta em uma janela de navegação anônima.

   1. 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 o issuerUri no 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.

   2. Se o URL for aberto, verifique as seguintes condições:

      1. 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.
      2. Verifique o tempo de resposta do IdP. Consulte o administrador do IdP para reduzir a latência da resposta.
      3. O documento de descoberta aberto precisa estar no formato JSON.

      4. Procure um campo jwks_uri no JSON.

         1. Verifique se o valor do URL associado também é aberto.
         2. Verifique se o URL atende às condições descritas anteriormente neste guia.

   3. 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 da Federação de identidade da força de trabalho 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:

1. 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 campo X509Certificate presente no valor idpMetadataXml definido no pool de identidade da força de trabalho provedor. Compare o certificado com o que foi visto na resposta retornada pelo IdP. Os certificados precisam ser iguais.

2. Faça login no Admin Console do IdP e faça o download do XML de metadados mais recente.

3. Atualize o provedor de pool de identidade da força de trabalho com o XML de metadados do IdP transferido por download.

4. 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 aparece 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.

Observação: NameID é obrigatório mesmo que você decida mapear um atributo diferente para google.subject no mapeamento de atributos.

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 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:

1. Consulte a documentação do IdP sobre como configurar o público-alvo nas tags AudienceRestriction enviadas na resposta SAML. Normalmente, o público-alvo é configurado ao definir o campo Entity ID ou Audience na 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 valor SP Entity ID que precisa ser definido.

2. 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.