Provisionamento do SCIM para a federação de identidade de colaboradores

Se o provedor de identidade (IdP) for compatível com o System for Cross-domain Identity Management (SCIM), configure-o para provisionar e gerenciar usuários e grupos no Google Cloud.

Recursos

O suporte ao SCIM da federação de identidade de colaboradores oferece os seguintes recursos:

  • Sincronização de identidades:sincroniza usuários e grupos do seu IdP externo com o Google Cloud para manter uma visão geral das identidades de colaboradores.
  • Fonte principal para declarações:quando o SCIM está ativado para um provedor de força de trabalho,o Google Cloud usa os usuários e grupos sincronizados do SCIM como fonte de verdade para atributos de usuários e associações a grupos na avaliação de políticas do IAM.
  • Preenchimento automático de identidade:permite o preenchimento automático de usuários e grupos ao conceder acesso e compartilhar recursos (como notebooks e agentes) no Gemini Enterprise.

Considerações

Ao usar o suporte a SCIM da federação de identidade de colaboradores, as seguintes considerações se aplicam:

  • É necessário configurar um pool e um provedor de identidade de colaboradores antes de configurar um locatário do SCIM.
  • Cada pool de identidade da força de trabalho aceita apenas um locatário do SCIM, vinculado a um único provedor. Não é possível ativar o uso do SCIM (--scim-usage) em nenhum outro provedor no mesmo pool. Para configurar um novo locatário do SCIM no mesmo pool de identidade de colaboradores, primeiro exclua o locatário atual. Para excluir um locatário do SCIM, use um dos seguintes métodos:
    • Exclusão reversível (padrão): a exclusão de um locatário do SCIM inicia um período de exclusão reversível de 30 dias. Durante esse período, o locatário fica oculto e não pode ser usado. Além disso, não é possível criar um novo locatário do SCIM no mesmo pool de identidades da força de trabalho.
    • Exclusão definitiva:para excluir um locatário do SCIM de forma permanente e imediata, use a flag --hard-delete com o comando de exclusão. Essa ação é irreversível e permite criar um novo locatário do SCIM no mesmo pool de identidades da força de trabalho imediatamente, sem esperar o período de retenção de 30 dias. Como alternativa, crie um pool de identidades de colaboradores e um locatário do SCIM ou use um pool de identidades de colaboradores que não tenha sido configurado anteriormente com um locatário do SCIM.
  • Modos de uso do SCIM (--scim-usage):
    • enabled-for-groups (Gemini Enterprise): usa grupos sincronizados com SCIM para autorização do IAM e avaliação de políticas. Os atributos do usuário continuam sendo originados de tokens de login. Somente os mapeamentos google.subject e google.group são avaliados.
    • enabled-for-users-groups (Looker) (Prévia): usa dados de usuários e grupos sincronizados com o SCIM como a fonte de declarações para autorização do IAM e fluxos de trabalho de login do OAuth. Avalia google.subject, google.group e todas as declarações de usuário configuradas (como google.display_name, google.profile_photo, google.email, google.posix_username e attribute.KEY personalizadas).
  • Exclusão mútua:definir --scim-usage=enabled-for-users-groups (prévia) é mutuamente exclusivo com atributos extras (extra_attributes_oauth2_client) e atributos estendidos (extended_attributes_oauth2_client).
  • Ao usar o SCIM, você mapeia atributos no provedor do pool de identidade de colaboradores e no locatário do SCIM. O atributo google.subject precisa se referir de maneira exclusiva às mesmas identidades. Você especifica google.subject no provedor de pool de identidades de colaboradores usando a flag --attribute-mapping e no locatário do SCIM usando a flag --claim-mapping. O mapeamento de valores de identidade não exclusivos pode fazer com que o Google Cloud trate identidades de IdP diferentes como se fossem a mesma. Como resultado, o acesso concedido a um usuário ou grupo pode ser estendido a outros, mas revogar o acesso de um pode não remover de todos.
  • Se você ativar o uso do SCIM em um provedor sem um locatário do SCIM anexado, as tentativas de login vão falhar porque o Google Cloud não consegue encontrar um locatário do SCIM para esse provedor.
  • Aplicação da exclusividade:o Google Cloud valida e aplica a exclusividade nos atributos mapeados para google.subject (usuários) e google.group (grupos) em um locatário do SCIM. Se os atributos mapeados provisionados pelo seu IdP resultarem em valores duplicados para google.subject ou google.group durante a sincronização, o provisionamento vai falhar com um erro HTTP 409 Conflict. Se um atributo mapeado for avaliado como nulo ou vazio, o provisionamento vai falhar com um erro HTTP 400 Bad Request.
  • Limites de tamanho de atributo:o tamanho máximo para atributos de usuário mapeados serializados (excluindo google.group) é de 16 kB. Se os atributos mapeados excederem esse limite, as tentativas de login vão falhar.
  • Limite de tokens do SCIM:cada locatário do SCIM aceita um máximo de dois tokens do SCIM (por exemplo, para oferecer suporte à rotação de tokens sem tempo de inatividade). Se você tiver dois tokens, exclua um deles antes de criar um novo.
  • A API SCIM (iamscim.googleapis.com) está sujeita a cotas de taxa que são diferentes das cotas padrão da API de recursos do IAM. Por padrão, as solicitações de leitura e gravação são limitadas a 3.000 por locatário do SCIM por organização por minuto. Para mais informações, consulte Cotas e limites.

Mapeamento de declarações

Ao configurar o SCIM, você define mapeamentos de declarações (--claim-mapping) no locatário do SCIM para mapear atributos de usuário e grupo do SCIM para atributos do Google.

Atributos Google Cloud compatíveis para mapeamento de declarações

A tabela a seguir lista os atributos Google Cloud que podem ser mapeados no seu locatário do SCIM (--claim-mapping) usando a Common Expression Language (CEL):

AtributoGoogle Cloud Requisito Descrição Expressões e limites aceitos
google.subject Obrigatório

Identificador exclusivo do usuário autenticado.

O atributo do IdP usado para preencher google.subject precisa ser idêntico no mapeamento do provedor (--attribute-mapping) e no locatário do SCIM (--claim-mapping). Se esses mapeamentos forem inconsistentes, os usuários poderão fazer login, mas não serão reconhecidos como membros de grupos provisionados pelo SCIM.

 Restrito às seguintes expressões básicas (ou com .lowerAscii()):
  • user.externalId
  • user.userName
  • user.emails[0].value

Comprimento máximo: 127 bytes.

Observação:esse mapeamento é imutável depois que o locatário do SCIM é criado. Para atualizá-lo, é necessário excluir permanentemente e recriar o locatário do SCIM.
google.group Obrigatório para grupos do SCIM Identificador exclusivo da associação ao grupo sincronizada usando o SCIM. Restrito às seguintes expressões básicas (ou com .lowerAscii()):
  • group.externalId
  • group.displayName

Observação:esse mapeamento é imutável depois que o locatário do SCIM é criado. Para atualizá-lo, é necessário excluir permanentemente e recriar o locatário do SCIM.
google.display_name Opcional Um atributo que define o nome do usuário conectado no console Google Cloud . Ele não pode ser usado em políticas de permissão do IAM. Mapeia para um atributo de string, como user.displayName ou user.name.formatted. Tamanho máximo: 100 bytes.
google.profile_photo Opcional Um URL da miniatura da foto do usuário que aparece como foto do perfil no console do Google Cloud . Ele não pode ser usado em políticas de permissão do IAM. Precisa ser avaliado como uma string de URL válida (como user.photos.filter(p, p.type == 'thumbnail')[0].value ou user.photos[0].value).
google.email Opcional Um atributo usado para mapear endereços de e-mail do IdP para produtos integrados usando a integração do cliente OAuth da federação de identidade de colaboradores. Ele não pode ser usado em políticas de permissão do IAM. Mapeia para um atributo de e-mail, como user.emails.filter(e, e.type == 'work')[0].value ou user.emails[0].value.
google.posix_username Opcional Uma string de nome de usuário exclusiva compatível com POSIX usada para SSH no navegador e Login do SO com a federação de identidade de colaboradores. Esse atributo não pode ser usado nas políticas de permissão do IAM. O tamanho máximo é de 32 caracteres.
attribute.KEY Opcional

Atributos personalizados do seu IdP que podem ser usados para definir sua estratégia de autorização em uma política de permissão do IAM. Substitua KEY pelo nome do atributo que você quer usar.

Por exemplo, é possível definir um atributo personalizado como costcenter = "1234" e se referir a ele usando principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workforcePools/WORKFORCE_POOL_ID/attribute.costcenter/1234. Conceder acesso a esse identificador principal dá acesso a todas as identidades configuradas no IdP com esse centro de custo.

 Até 50 regras de mapeamento de atributos personalizados. Tamanho máximo por regra: 256 caracteres.

Comportamento com base no uso do SCIM do provedor (--scim-usage)

A avaliação dos mapeamentos de declarações do SCIM depende do modo --scim-usage configurado no provedor de pool de identidade da força de trabalho:

  • enabled-for-groups (Gemini Enterprise): somente os mapeamentos google.subject e google.group são avaliados. Todos os outros mapeamentos de declarações de usuário em --claim-mapping são ignorados.
  • enabled-for-users-groups (Looker) (Pré-lançamento): avalia google.subject, google.group e todas as declarações de usuário configuradas (como google.display_name, google.profile_photo, google.email, google.posix_username e attribute.<var>KEY</var> personalizadas).

Exemplos de mapeamentos para consistência de assunto

Conforme descrito em Atributos compatíveis para mapeamento de declarações, o atributo do IdP usado para preencher google.subject precisa ser idêntico no mapeamento do provedor (--attribute-mapping) e no locatário do SCIM (--claim-mapping). A tabela a seguir mostra exemplos de referência:

Atributo do Google Mapeamento de provedor de pool de identidade de colaboradores Mapeamento de locatário do SCIM (SCIM)
google.subject assertion.oid (Entra ID) user.externalId
google.subject assertion.sub (Okta) user.externalId
google.subject assertion.preferred_username user.userName
google.subject assertion.preferred_username.lowerAscii() user.userName.lowerAscii()
google.subject assertion.email user.emails[0].value
google.subject assertion.email.lowerAscii() user.emails[0].value.lowerAscii()

Endpoints compatíveis e incompatíveis

O serviço SCIM do IAM (iamscim.googleapis.com) implementa o protocolo SCIM 2.0 (RFC 7644) e atende solicitações no baseUri do seu locatário SCIM:

https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID

Neste URI, SCIM_TENANT_UID é o identificador exclusivo do seu locatário do SCIM.

O serviço SCIM do IAM é compatível com os seguintes endpoints padrão do protocolo SCIM relativos ao locatário baseUri:

  • /Users: gerenciar recursos do usuário. Operações aceitas: Create, Get, Update, Delete, Patch e Put.

  • /Groups: gerenciar recursos de grupo. Operações aceitas: Create, Get, Update, Delete e Patch. O método PUT não é compatível com grupos.

  • /Schemas: recupera informações do esquema.

  • /ServiceProviderConfig: recupere a configuração do provedor de serviços.

Os seguintes endpoints do protocolo SCIM não são compatíveis:

  • /Me

  • /Bulk

  • /Search

  • /ResourceTypes

Limitações

As seções a seguir descrevem as limitações e os desvios da implementação do SCIM da federação de identidade da força de trabalho em relação às especificações do SCIM (RFC 7643 e 7644).

Limitações do recurso de protocolo

  • Suporte a filtros:ao listar usuários ou grupos usando os endpoints /Users ou /Groups, as expressões de filtro só aceitam o operador eq (igual a). É possível combinar vários filtros eq com and. Outros operadores de filtro do SCIM, como co (contém) ou sw (começa com), não são compatíveis.

  • Paginação:a API SCIM do IAM não oferece suporte à paginação padrão para listar usuários ou grupos.

    • startIndex: esse parâmetro é sempre 1. A API retorna até 100 resultados, seja qual for o valor fornecido para startIndex.

    • itemsPerPage: o número máximo de recursos retornados em uma única resposta é 100.

    • totalResults: a API não retorna a contagem total real de recursos correspondentes. O campo totalResults na resposta é sempre igual ao número de itens retornados nela, com um máximo de 100.

  • Get Group e list Groups sem filtro:as APIs GetGroup e ListGroups retornam uma lista de membros vazia. Para recuperar membros de um grupo específico, use a API ListGroups com um filtro de membros.

  • Resposta JSON não compatível com tokens inválidos:solicitações que contêm um token de API inválido retornam um código de status HTTP 401 de Google Cloud. A resposta não é um JSON válido, conforme exigido pela especificação SCIM.

Limitações de comportamento do SCIM

  • Identificadores imutáveis:os valores de atributos do SCIM mapeados para google.subject ou google.group são tratados como identificadores imutáveis em Google Cloud. Se precisar mudar esses valores, exclua permanentemente o usuário ou grupo do IdP e recrie com o novo valor.

  • Identificadores exclusivos e não vazios: Google Cloud impõe a exclusividade em valores mapeados para google.subject e google.group em um locatário do SCIM. A sincronização de atributos mapeados que resultam em valores duplicados para google.subject ou google.group falha com um erro HTTP 409 Conflict. Os atributos mapeados que são avaliados como nulos ou vazios falham com um erro HTTP 400 Bad Request.

  • Requisito de e-mail único:para que a sincronização do SCIM seja bem-sucedida, cada usuário precisa ter exatamente um endereço de e-mail do tipo work. O provisionamento ou as atualizações vão falhar se o IdP enviar vários e-mails ou se o e-mail fornecido não for do tipo work.

  • Transformações sem diferenciação de maiúsculas e minúsculas:transformações limitadas da Common Expression Language (CEL) são compatíveis com mapeamentos de declarações do SCIM. Somente .lowerAscii() é compatível com comparações sem diferenciação de maiúsculas e minúsculas para user.userName e user.emails[0].value.

Limitações de atributos

As seções a seguir descrevem o suporte a atributos para usuários, grupos e a extensão do esquema de usuário empresarial.

Atributos do usuário

A tabela a seguir lista os atributos do usuário e a disponibilidade deles nas declarações da federação de identidade de colaboradores:

Atributo Subatributos Compatível com o provisionamento do SCIM Limitações Compatível com --claim-mapping
userName N/A Sim N/A Sim
name formatted, familyName, givenName, middleName, honorificPrefix, honorificSuffix Sim N/A Sim
displayName N/A Sim N/A Sim
nickName N/A Sim N/A Sim
profileUrl N/A Sim N/A Sim
title N/A Sim N/A Sim
userType N/A Sim N/A Sim
preferredLanguage N/A Sim N/A Sim
locale N/A Sim N/A Sim
timezone N/A Sim N/A Sim
active N/A Sim N/A Sim
password N/A Não N/A Não
emails display, type, value, primary Sim Somente o tipo de e-mail work é aceito. Sim
phoneNumbers display, type, value, primary Sim N/A Sim
ims display, type, value Sim N/A Sim
photos display, type, value Sim N/A Sim
addresses formatted, streetAddress, locality, region, postalCode, country Sim N/A Sim
groups N/A Não N/A Não
entitlements display, type, value Sim N/A Sim
roles type, value Sim display não é compatível. Sim
x509Certificates type, value Sim display não é compatível. Não

Atributos do grupo

A tabela a seguir lista os atributos do grupo e a disponibilidade deles nas declarações da federação de identidade de colaboradores:

Atributo Subatributos aceitos Compatível com --claim-mapping
displayName N/A Sim
externalId N/A Sim
members value, type, $ref, display Não

Atributos de extensão do esquema de usuário empresarial

A tabela a seguir detalha o suporte para a extensão do esquema de usuário empresarial:

Atributo Subatributos aceitos Compatível com --claim-mapping
employeeNumber N/A Sim
costCenter N/A Sim
organization N/A Sim
division N/A Sim
department N/A Sim
manager value, $ref, displayName Sim (o $ref é compatível apenas com o provisionamento do SCIM, não com o --claim-mapping)

A seguir