Gerenciamento de usuários e grupos com SCIM

Este tópico descreve:

  1. Integrações do SCIM com o Snowflake.

  2. Casos de uso do SCIM com o Snowflake.

  3. Uso de APIs SCIM do Snowflake para fazer solicitações a um provedor de identidade.

Visão geral do SCIM

SCIM é uma especificação aberta para ajudar a facilitar o gerenciamento automatizado de identidades e grupos de usuários (ou seja, funções) em aplicativos na nuvem usando APIs RESTful.

Estas APIs utilizam métodos comuns (por exemplo GET, POST) com atributos de pares chave-valor no formato JSON. O conjunto de atributos do usuário é único para o usuário. Da mesma forma, o conjunto de atributos do grupo é único para o grupo

Atualmente, o Snowflake suporta SCIM 2.0 para integrar o Snowflake com o Okta e o Microsoft Azure AD, que funcionam como provedores de identidade. O Snowflake também suporta provedores de identidade que não são nem Okta nem Microsoft Azure (ou seja, personalizados). Os usuários e grupos do provedor de identidade podem ser provisionados no Snowflake, que funciona como o provedor de serviços.

Importante

A função específica do SCIM no Snowflake deve ser de proprietário de quaisquer usuários e funções que são importados do provedor de identidade. Se a função do SCIM do Snowflake não possuir usuários ou funções importados, as atualizações no provedor de identidade não serão sincronizadas com o Snowflake. A função do SCIM do Snowflake é específica do provedor de identidade (IdP), desta forma:

  • Função SCIM do Okta: okta_provisioner

  • Função SCIMdo Azure AD: aad_provisioner

  • Função SCIM personalizada: generic_scim_provisioner

Para obter mais informações sobre como usar a função SCIM do Snowflake, consulte as seções de configuração do SCIM para Okta, Azure AD e a integração SCIM personalizada.

O provedor de identidade usa um cliente SCIM para fazer a solicitação de API RESTful ao servidor SCIM do Snowflake. Ao validar a solicitação de API, o Snowflake realiza ações para o usuário ou grupo.

O processo de autenticação utiliza um token Bearer OAuth, válido por seis meses. Os clientes devem manter o registro de seu token de autenticação e podem gerar um novo token sob demanda. Durante cada solicitação de API, o token é passado para o cabeçalho como um parâmetro Bearer de autorização.

Após a configuração inicial do SCIM do Snowflake, você pode usar a API SCIM do Snowflake para tratar dos seguintes casos de uso:

  1. Gerenciamento do ciclo de vida do usuário

  2. Mapeamento dos grupos do Active Directory para funções do Snowflake

Cuidado

Atualmente, a API SCIM do Snowflake permite aos administradores gerenciar usuários e grupos do provedor de identidade do cliente ao Snowflake.

Portanto, se utilizar a API SCIM do S para a administração do gerenciamento de acesso e identidade de usuários e grupos, não faça mudanças de usuário e grupo no Snowflake (porque essas mudanças não serão sincronizadas de volta ao provedor de identidade do cliente).

Casos de uso do SCIM

A API SCIM do Snowflake pode abordar os seguintes casos de uso.

Gerenciar usuários:

Os administradores podem provisionar e gerenciar seus usuários desde o provedor de identidade de sua organização até o Snowflake. O gerenciamento de usuários é um mapeamento individual do provedor de identidade até o Snowflake.

Gerenciar funções:

Os administradores podem provisionar e gerenciar seus grupos (ou seja, funções) desde o provedor de identidade de sua organização até o Snowflake. O gerenciamento de funções é um mapeamento individual do provedor de identidade até o Snowflake.

Auditoria:

Os administradores podem consultar a tabela rest_event_history para determinar se o provedor de identidade está enviando atualizações (ou seja, solicitações de API SCIM) ao Snowflake.

Gerenciamento de usuários com SCIM

O Snowflake suporta o gerenciamento do ciclo de vida do usuário com APIs SCIM. O gerenciamento do ciclo de vida do usuário é uma atividade administrativa que coincide com o caminho que o usuário percorre em toda a organização. Eventos comuns no ciclo de vida do usuário incluem estas atividades.

  1. Criação e ativação de um usuário.

  2. Atualização de atributos do usuário, tais como email ou password.

  3. Desativação de um usuário após o término.

No Snowflake, a automação do ciclo de vida do usuário usando SCIM requer a passagem de atributos do usuário no corpo da solicitação de API. Uma solicitação bem-sucedida da API do provedor de identidade afeta o usuário no Snowflake quase imediatamente.

Atributos do usuário

Os atributos do usuário são os pares chave-valor que estão associados ao usuário. Estes pares são as informações sobre o usuário, tais como seu nome de exibição e seu endereço de e-mail. Os provedores de identidade às vezes definem chaves de atributos de forma diferente, tais como surname, familyName ou lastName, onde todos indicam o sobrenome do usuário. O Snowflake não suporta atributos do usuário com múltiplos valores.

A API SCIM do Snowflake passa os atributos do usuário no formato JSON, que são mostrados nos exemplos correspondentes de API do usuário.

O Snowflake suporta os seguintes atributos SCIM para o gerenciamento do ciclo de vida do usuário. Os atributos podem ser gravados, a menos que seja observado o contrário.

Importante

Na tabela, os atributos userName e loginName do Snowflake são mapeados para o atributo SCIM userName. O Snowflake suporta diferentes valores para o atributo userName e loginName do Snowflake. Esta separação de valores de atributo permite que os clientes tenham um controle mais granular sobre qual valor de atributo pode ser usado para acessar o Snowflake.

Para obter mais informações, consulte os exemplos de API do usuário para POST e PATCH.

Atributo de usuário do SCIM

Atributo de usuário do Snowflake

Tipo

Descrição

id

id

cadeia de caracteres

O identificador imutável e único (isto é, GUID) do usuário no Snowflake.

O Snowflake não expõe este valor na saída DESCRIBE USER ou SHOW USERS.

Para certos caminhos de solicitação que contêm este atributo (por exemplo, PATCH), o id pode ser encontrado chamando a função de tabela REST_EVENT_HISTORY.

Verifique os logs do IdP para garantir que os valores correspondem.

userName

userName, loginName

cadeia de caracteres

O identificador para login no Snowflake. Para detalhes sobre estes atributos do Snowflake, consulte CREATE USER.

name.givenName

firstName

cadeia de caracteres

O nome do usuário.

name.familyName

familyName

cadeia de caracteres

O sobrenome do usuário.

emails

email

cadeia de caracteres

O endereço de e-mail do usuário. O valor suporta um único endereço de e-mail.

displayName

displayName

cadeia de caracteres

O nome que a interface do usuário exibe para o usuário.

externalID

N/A

cadeia de caracteres

O identificador único estabelecido pelo cliente provisionador (por exemplo, Azure, Okta).

password

password

cadeia de caracteres

A senha para o usuário. Este valor não é retornado na resposta JSON.

Nota: Se a propriedade SYNC_PASSWORD da integração de segurança SCIM for definida como FALSE e a solicitação de API SCIM especificar o atributo password, o Snowflake ignora o valor para o atributo password. Todos os outros atributos na solicitação de API são processados de acordo.

active

disabled

booleano

Desabilita o usuário quando definido como false.

groups

N/A

cadeia de caracteres

Uma lista de grupos aos quais o usuário pertence. O nome de exibição do grupo é necessário.

Os grupos do usuário são somente leitura e sua associação deve ser atualizada com a API de grupos do SCIM.

meta.created

createdON

cadeia de caracteres

A hora em que o usuário é adicionado ao Snowflake.

meta.lastModified

lastModified

cadeia de caracteres

A hora em que o usuário foi modificado pela última vez no Snowflake.

meta.resourceType

N/A

cadeia de caracteres

Os usuários devem ter um valor de usuário.

schemas

N/A

cadeia de caracteres

Uma matriz de cadeias de caracteres separadas por vírgula para indicar os URIs do namespace. Os valores com suporte incluem:

  • urn:ietf:params:scim:schemas:core:2.0:User

  • urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

  • urn:ietf:params:scim:schemas:extension:2.0:User

Atributos personalizados

O Snowflake suporta a definição de atributos personalizados que não são definidos pelo RFC 7643, tais como defaultRole, defaultWarehouse e defaultSecondaryRoles.

Atualmente, o Snowflake suporta o uso de dois namespaces para definir atributos personalizados para as seguintes solicitações de API POST, PUT e PATCH:

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Este namespace foi parte da implementação SCIM original no Snowflake e pode ser usado para definir atributos personalizados apenas para as integrações SCIM do Okta.

Este namespace não tem suporte para definir atributos personalizados para integrações SCIM do Microsoft Azure ou integrações SCIM personalizadas.

urn:ietf:params:scim:schemas:extension:2.0:User

Este namespace mais novo pode ser usado para definir atributos personalizados para todas as integrações SCIM e precisa ser usado para atributos personalizados com uma integração SCIM personalizada ou uma integração SCIM do Microsoft Azure.

APIs de usuário

O Snowflake suporta as seguintes APIs para facilitar o gerenciamento do ciclo de vida do usuário. Você pode obter informações do usuário com filtros e também criar, atualizar, desativar e excluir usuários.

Objetivo

Método e API

Notas

Verifique se existe um usuário.

GET scim/v2/Users?filter=userName eq "{{user_name}}"

Retorna os detalhes de uma conta de usuário com o userName dado e com um código de status HTTP de 200 se bem-sucedido.

Obtenha detalhes para um usuário específico.

GET scim/v2/Users/{{user_id}}

Retorna os detalhes de uma conta de usuário com o user_id dado e com um código de status HTTP de 200 se bem-sucedido.

Obtenha detalhes para um usuário específico.

GET scim/v2/Users?startIndex=0&count=1

Retorna um usuário de amostra para permitir que o cliente SCIM leia o esquema e com um código de status HTTP de 200 se bem-sucedido.

Crie um usuário.

POST scim/v2/Users

Cria um usuário no Snowflake e retorna um código de status HTTP 201 se bem-sucedido.

Se o usuário já existir ou outro conflito surgir, o Snowflake retorna um código de status HTTP 409.

Atualize o usuário com atributos parciais.

PATCH scim/v2/Users/{id}

Desativa o usuário correspondente se a chave active estiver definida como false.

Para ativar um usuário atualmente desativado, defina active como true.

PATCH requer uma chave de operações (ou seja, op) com uma matriz que declare a substituição de um valor de atributo.

Retorna um código de status HTTP de 200 se bem-sucedido ou 204 (isto é, sem conteúdo) se não for bem-sucedido.

Atualize um usuário.

PUT scim/v2/Users/{id}

Verifica se um usuário com o id dado existe. Esta operação falha se atributos imutáveis forem solicitados a mudar.

Caso contrário, ele substituirá os atributos de leitura-gravação ou somente gravação com base na solicitação.

Retorna um código de status HTTP de 400 se os valores de atributos imutáveis no corpo da solicitação não corresponderem aos valores no Snowflake.

Exclua um usuário.

DELETE scim/v2/Users/{id}

Para obter mais informações sobre solicitações de API SCIM, consulte Como fazer uma solicitação de API SCIM.

POST scim/v2/Users

Crie um usuário com userName e loginName mapeados para o mesmo valor.

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:2.0:User"
        ],
    "userName": "test_user_1",
    "password": "test",
    "name": {
        "givenName": "test",
        "familyName": "user"
        },
    "emails": [{
        "value": "test.user@snowflake.com"
        }
    ],
    "displayName": "test user",
    "active": true
}
Copy

Crie um usuário com userName e loginName mapeados para valores diferentes.

Se o Okta for seu provedor de identidade, siga este procedimento.

{
    "active": true,
    "displayName": "test user",
    "emails": [
        {
            "value": "test.user@snowflake.com"
        }
    ],
    "name": {
        "familyName": "test_last_name",
        "givenName": "test_first_name"
    },
    "password": "test_password",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "snowflakeUserName": "USER5"
    },
    "userName": "USER5"
}
Copy
PATCH scim/v2/Users/{id}

Atualize um usuário com userName e loginName mapeados para o mesmo valor.

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "replace",
        "value": {
            "active": false
        }
    }]
}
Copy

Atualize um usuário com userName e loginName mapeados para valores diferentes.

Se o Okta for seu provedor de identidade, siga este procedimento.

{
    "Operations": [
        {
            "op": "Replace",
            "path": "userName",
            "value": "test_updated_name"
        },
        {
            "op": "Replace",
            "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.snowflakeUserName",
            "value": "USER5"
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}
Copy
PUT scim/v2/Users/{id}

Atualize um usuário, incluindo a configuração dos campos "defaultRole", "defaultSecondaryRoles" e "defaultWarehouse".

Para especificar as propriedades "defaultRole", "defaultSecondaryRoles" e "defaultWarehouse", o Snowflake requer o uso de um dos esquemas extension. Observe que o único valor possível para defaultSecondaryRoles é "ALL".

Nota

Embora o Snowflake a suporte, tenha cuidado ao usar a operação PUT porque é mais cara do que uma operação PATCH. Use a operação PATCH em seu lugar.

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
        ],
    "userName": "test_user_1",
    "password": "test",
    "name": {
        "givenName": "test",
        "familyName": "user"
        },
    "emails": [{
        "primary": true,
        "value": "test.user@snowflake.com",
        "type": "work"
        }
    ],
    "displayName": "test user",
    "active": true,
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "defaultRole" : "test_role",
        "defaultSecondaryRoles" : "ALL",
        "defaultWarehouse" : "test_warehouse"
    }
}
Copy

Gerenciamento de funções com SCIM

O Snowflake suporta o uso do SCIM para importar funções do Okta, Azure AD e aplicativos personalizados. Há um mapeamento direto e individual com estas funções para funções do Snowflake.

Funções, que geralmente são sinônimos de grupos, são uma coleção lógica de privilégios de acesso. No modelo Snowflake, o acesso a objetos protegíveis é permitido através de privilégios atribuídos a funções, que por sua vez são atribuídas a outras funções ou usuários.

As permissões de acesso e os direitos que são concedidos à função são automaticamente herdados por cada membro (por exemplo, usuário) da função. Para obter mais informações, consulte Visão geral do controle de acesso.

À medida que os usuários prosseguem em sua trajetória profissional em sua organização, seus requisitos de acesso ao Snowflake podem mudar. Por exemplo, um usuário pode mudar de colaborador individual para gerente com subordinados diretos. Quando sua função mudar, seu acesso no Snowflake também pode precisar permitir conjuntos de dados disponíveis apenas para os gerentes.

À medida que a função de membro do usuário muda em sua organização, o acesso ao Snowflake pode mudar automaticamente uma vez que suas funções na organização são mapeadas para a função correspondente do Snowflake.

Atributos de função

A API SCIM do Snowflake passa os atributos da função no formato JSON, que são mostrados nos exemplos correspondentes de API.

O Snowflake suporta os seguintes atributos SCIM para o gerenciamento do ciclo de vida da função. Os atributos podem ser gravados, a menos que seja observado o contrário.

Atributo de grupo do SCIM

Atributo de grupo do Snowflake

Tipo

Descrição

id

id

Cadeia de caracteres

O identificador imutável e único (isto é, GUID) da função no Snowflake.

O Snowflake não expõe este valor. Ele pode ser encontrada chamando a função de tabela do Information Schema REST_EVENT_HISTORY.

Verifique os logs do IdP para garantir que os valores correspondem.

displayName

name

Cadeia de caracteres

O nome que a interface do usuário exibe para a função.

members.value

N/A

Cadeia de caracteres

O valor userID do usuário que é um membro da função.

schemas

N/A

Cadeia de caracteres

Uma matriz de cadeias de caracteres para indicar os URIs do namespace.

Por exemplo, urn:ietf:params:scim:schemas:core:2.0:Group.

APIs de função

Você pode obter informações de função com filtros e também criar uma função, atualizar a associação do membro e excluir uma função. O Snowflake suporta as seguintes APIs para facilitar o gerenciamento de funções.

Objetivo

Método e API

Notas

Obtenha um grupo por nome de exibição.

GET scim/v2/Groups?filter=displayName="scim_test_group"

Retorna os detalhes do grupo com o displayName dado e com um código de status HTTP de 200 se bem-sucedido.

Obtenha um grupo por seu groupId.

GET scim/v2/Groups/{group_id}

Retorna os detalhes do grupo com o groupId dado e um código de status HTTP de 200 se bem-sucedido.

Obtenha um grupo de amostra.

GET scim/v2/Groups?startIndex=0&count=1

Retorna um grupo de amostra para permitir que o cliente SCIM leia o esquema e com um código de status HTTP de 200 se bem-sucedido.

Crie um novo grupo.

POST scim/v2/Groups

Cria um novo grupo com um código de status HTTP de 201 se bem-sucedido.

Atualize um grupo.

PATCH scim/v2/Groups/{id}

Atualiza o atributo do nome de exibição do grupo ou a associação ao grupo.

PATCH requer uma chave de operações (ou seja, op) com uma matriz indicando se deve adicionar ou substituir.

Retorna um código de status HTTP de 200 se bem-sucedido ou 204 (isto é, sem conteúdo) se não for bem-sucedido.

Exclua um grupo.

DELETE scim/v2/Groups/{id}

Para obter mais informações sobre solicitações de API SCIM, consulte Como fazer uma solicitação de API SCIM.

POST scim/v2/Groups
{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "displayName":"scim_test_group2"
}
Copy
PATCH scim/v2/Groups/{id}
{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "replace",
        "value": {
            "displayName": "updated_name"
            }
        },
        {
            "op" : "remove",
            "path": "members[value eq \"user_id_1\"]"
        },
        {
          "op": "add",
          "value": [{
            "value": "user_id_2"
            }]
        }
    ]
}
Copy

Auditoria com SCIM

É possível consultar o Snowflake para determinar quais solicitações de API SCIM foram feitas em um determinado intervalo de tempo.

Por exemplo, estas informações podem ajudar a determinar se a população ativa de usuários da organização que deve ser provisionada no Snowflake corresponde aos usuários provisionados no Snowflake.

O SQL abaixo é um exemplo representativo que chama a função de tabela do Information Schema REST_EVENT_HISTORY para determinar quais solicitações de API REST SCIM foram feitas nos últimos cinco minutos, até 200 solicitações.

use role accountadmin;
use database demo_db;
use schema information_schema;
select *
    from table(rest_event_history(
        'scim',
        dateadd('minutes',-5,current_timestamp()),
        current_timestamp(),
        200))
    order by event_timestamp;
Copy

Para obter mais informações sobre como modificar esta consulta, consulte as funções DATEADD e CURRENT_TIMESTAMP.

Integrações SCIM com suporte

O Snowflake pode se integrar com os seguintes provedores de identidade para provisionar, gerenciar e sincronizar usuários e grupos.

  1. Okta

  2. Microsoft Azure Active Directory

  3. Personalizado

    Nota

    As integrações SCIM personalizadas permitem aos provedores de identidade que não têm uma integração dedicada provisionar, gerenciar e sincronizar usuários e grupos no Snowflake.

    Atualmente, a integração SCIM personalizada deve ser usada para provedores de identidade que não são nem Okta nem Microsoft Azure AD.

Os clientes que utilizam o Okta como seu provedor de identidade devem seguir as instruções em Integração SCIM Okta com o Snowflake.

Os clientes que utilizam o Microsoft Azure Active Directory como seu provedor de identidade devem seguir as instruções em Integração Azure SCIM com o Snowflake.

Os clientes que não estão utilizando o Okta ou o Microsoft Azure Active Directory como seu provedor de identidade devem criar seu próprio cliente SCIM e então seguir as instruções em Integração SCIM personalizada com o Snowflake.

Uso da replicação com SCIM

O Snowflake oferece suporte à replicação e failover/failback com a integração de segurança SCIM da conta de origem para a conta de destino.

Para obter mais detalhes, consulte Replicação de integrações de segurança e políticas de redes em múltiplas contas.

Próximos tópicos: