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

Se o provedor de identidade (IdP) for compatível com o Sistema de gerenciamento de identidade entre domínios (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 identidade: sincroniza usuários e grupos do IdP externo com o Google Cloud para manter uma visão holística das identidades de colaboradores.
  • Fonte principal de 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 a fonte de verdade para atributos de usuário e associações de grupo para avaliação de políticas do IAM.
  • Preenchimento automático de identidade: ativa 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 ao SCIM da federação de identidade de colaboradores, as seguintes considerações se aplicam:

  • É necessário configurar um pool de identidade de colaboradores e um provedor antes de configurar um locatário do SCIM.
  • Cada pool de identidade de colaboradores 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 é preciso excluir o 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, e não é possível criar um novo locatário do SCIM no mesmo pool de identidade de colaboradores.
    • Exclusão irreversível: para fazer a exclusão irreversível de forma permanente e imediata de um locatário do SCIM, 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 de colaboradores imediatamente, sem esperar pelo período de retenção de 30 dias. Como alternativa, é possível criar um novo pool de identidade de colaboradores e um novo locatário do SCIM ou usar um pool de identidade 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 o 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 (Gemini Enterprise e Looker): usa dados de usuários e grupos sincronizados com o SCIM como fonte de declarações para autorização do IAM em fluxos de trabalho de login na Web e 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.<var>KEY</var> personalizado).
  • Exclusividade mútua: a configuração --scim-usage=enabled-for-users-groups é mutuamente exclusiva com os atributos extras (extra_attributes_oauth2_client) e os atributos estendidos (extended_attributes_oauth2_client).
  • Ao usar o SCIM, você mapeia atributos no provedor do pool de identidades de colaboradores e no locatário do SCIM. O atributo google.subject precisa se referir exclusivamente às mesmas identidades. Especifique google.subject no provedor do pool de identidade de colaboradores usando a flag --attribute-mapping e no locatário do SCIM usando a flag --claim-mapping. Mapear valores de identidade não exclusivos pode fazer com que o Google Cloud trate identidades de IdP diferentes como a mesma identidade. Como resultado, o acesso concedido a uma identidade de usuário ou grupo pode se estender a outras, mas revogar o acesso de uma pode não removê-lo de todas.
  • 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 vai conseguir encontrar um locatário do SCIM para esse provedor.
  • Aplicação de exclusividade: Google Cloud valida e aplica a exclusividade em atributos mapeados para google.subject (usuários) e google.group (grupos) em um locatário do SCIM. Se os atributos mapeados provisionados pelo 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 atributos: o tamanho máximo para atributos de usuário mapeados serializados (exceto 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 no máximo dois tokens do SCIM (por exemplo, para aceitar a rotação de tokens sem 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 diferem das cotas padrão da API de recursos do IAM. 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. 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 os atributos de usuário e grupo do SCIM para os atributos do Google.

Atributos do Google Cloud compatíveis com o mapeamento de declarações

A tabela a seguir lista os atributos do Google Cloud que podem ser mapeados no 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 que está sendo 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 de base (ou com .lowerAscii()):
  • user.externalId
  • user.userName
  • user.emails[0].value

Tamanho máximo: 127 bytes.

Observação: esse mapeamento é imutável após a criação do locatário do SCIM. Para atualizá-lo, é necessário fazer a exclusão irreversível 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 de base (ou com .lowerAscii()):
  • group.externalId
  • group.displayName

Observação: esse mapeamento é imutável após a criação do locatário do SCIM. Para atualizá-lo, é necessário fazer a exclusão irreversível e recriar o locatário do SCIM.

google.display_name Opcional Um atributo que define o nome do usuário conectado no console do Google Cloud . Ele não pode ser usado em políticas de permissão do IAM. É mapeado para um atributo de string (como user.displayName ou user.name.formatted). Tamanho máximo: 100 bytes.
google.profile_photo Opcional Um URL da foto em miniatura do usuário que fica visível como a foto do perfil no console do Google Cloud . Ele não pode ser usado em políticas de permissão do IAM. Precisa ser avaliada 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 de 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 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 fazer referência 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 identidades de colaboradores:

  • 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 (Gemini Enterprise e Looker): 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> personalizado). O Google Cloud usa declarações do SCIM nos seguintes fluxos de trabalho de login:
    • Login na Web: quando os usuários fazem login no Gemini Enterprise, o Google Cloud usa as declarações de usuário e grupo sincronizadas pelo SCIM. Quando os usuários fazem login em outros produtos, como o Google Cloud console, Google Cloud usa os atributos mapeados do token do IdP pela sinalização --attribute-mapping do provedor.
    • Login do OAuth: quando os usuários fazem login nos aplicativos Gemini Enterprise e Looker que usam o fluxo OAuth da federação de identidade de colaboradores, o Google Cloud usa as declarações de usuário e grupo sincronizadas com o SCIM. Quando os usuários fazem login em outros aplicativos, o Google Cloud usa os atributos mapeados do token do IdP pela flag --attribute-mapping do provedor.

Exemplos de mapeamentos para consistência de assunto

Conforme descrito em Atributos compatíveis com o 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 do provedor do 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 a solicitações no baseUri do locatário do SCIM:

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

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

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

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

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

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

  • /ServiceProviderConfig: recuperar 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 de colaboradores 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 é compatível com a paginação padrão para listar usuários ou grupos.

    • startIndex: este parâmetro é sempre 1. A API retorna até 100 resultados, independentemente do 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 nessa resposta, com um máximo de 100.

  • Receber grupo e listar grupos sem filtro: as APIs GetGroup e ListGroups retornam uma lista de participantes vazia. Para recuperar os participantes de um grupo específico, use a API ListGroups com um filtro de participantes.

  • Resposta JSON não compatível com tokens inválidos: as 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 do SCIM.

Limitações de comportamento do SCIM

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

  • Identificadores exclusivos e não vazios: Google Cloud impõe a exclusividade nos 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 que não diferenciam maiúsculas de minúsculas: as 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 que não diferenciam maiúsculas de 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 corporativo.

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 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 de 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 corporativo

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

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 ($ref é compatível apenas com o provisionamento SCIM, não com --claim-mapping)

A seguir