CREATE SECURITY INTEGRATION (OAuth externo)

Cria uma nova integração de segurança do OAuth externo na conta ou substitui uma integração existente. Uma integração de segurança de OAuth externo permite que um cliente utilize um servidor de autorização de terceiros para obter os tokens de acesso necessários para interagir com o Snowflake.

Para obter mais informações sobre a criação de outros tipos de integrações de segurança (por exemplo, Snowflake OAuth), ver CREATE SECURITY INTEGRATION.

Consulte também:

ALTER SECURITY INTEGRATION (OAuth externo) , DROP INTEGRATION , SHOW INTEGRATIONS

Sintaxe

CREATE [ OR REPLACE ] SECURITY INTEGRATION [IF NOT EXISTS]
  <name>
  TYPE = EXTERNAL_OAUTH
  ENABLED = { TRUE | FALSE }
  EXTERNAL_OAUTH_TYPE = { OKTA | AZURE | PING_FEDERATE | CUSTOM }
  EXTERNAL_OAUTH_ISSUER = '<string_literal>'
  EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = '<string_literal>' | ('<string_literal>', '<string_literal>' [ , ... ] )
  EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = 'LOGIN_NAME | EMAIL_ADDRESS'
  [ EXTERNAL_OAUTH_JWS_KEYS_URL = '<string_literal>' ] -- For OKTA | PING_FEDERATE | CUSTOM
  [ EXTERNAL_OAUTH_JWS_KEYS_URL = '<string_literal>' | ('<string_literal>' [ , '<string_literal>' ... ] ) ] -- For Azure
  [ EXTERNAL_OAUTH_BLOCKED_ROLES_LIST = ( '{role_name}' [ , '{role_name}' , ... ] ) ]
  [ EXTERNAL_OAUTH_ALLOWED_ROLES_LIST = ( '{role_name}' [ , '{role_name}' , ... ] ) ]
  [ EXTERNAL_OAUTH_RSA_PUBLIC_KEY = <public_key1> ]
  [ EXTERNAL_OAUTH_RSA_PUBLIC_KEY_2 = <public_key2> ]
  [ EXTERNAL_OAUTH_AUDIENCE_LIST = ('<string_literal>') ]
  [ EXTERNAL_OAUTH_ANY_ROLE_MODE = DISABLE | ENABLE | ENABLE_FOR_PRIVILEGE ]
  [ EXTERNAL_OAUTH_SCOPE_DELIMITER = '<string_literal>' ] -- Only for EXTERNAL_OAUTH_TYPE = CUSTOM

Parâmetros obrigatórios

name

Cadeia de caracteres que especifica o identificador (ou seja, nome) para a integração; deve ser única em sua conta.

Além disso, o identificador deve começar com um caractere alfabético e não pode conter espaços ou caracteres especiais, a menos que toda a cadeia de caracteres do identificador esteja entre aspas duplas (por exemplo, "My object"). Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

Para obter mais detalhes, consulte Requisitos para identificadores.

TYPE = EXTERNAL_OAUTH

Distingue a integração OAuth externo de uma integração Snowflake OAuth.

ENABLED = TRUE | FALSE

Especifica se deve iniciar a operação da integração ou suspendê-la.

  • TRUE permite que a integração funcione com base nos parâmetros especificados na definição do canal.

  • FALSE suspende a integração para manutenção. Qualquer integração entre o Snowflake e um serviço de terceiro não funciona.

EXTERNAL_OAUTH_TYPE = OKTA | AZURE | PING_FEDERATE | CUSTOM

Especifica o servidor de autorização OAuth 2.0 a ser Okta, Microsoft Azure AD, Ping Identity PingFederate ou um servidor de autorização personalizado OAuth 2.0.

EXTERNAL_OAUTH_ISSUER = 'string_literal'

Especifica o URL para definir o servidor de autorização OAuth 2.0.

EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = 'string_literal' | ('string_literal', 'string_literal' [ , ... ] )

Especifica declarações de token de acesso ou declarações que podem ser usadas para mapear o token de acesso para um registro de usuário Snowflake.

O tipo de dados da declaração deve ser uma cadeia de caracteres ou uma lista de cadeias de caracteres.

EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = 'LOGIN_NAME | EMAIL_ADDRESS'

Indica qual atributo de registro de usuário Snowflake deve ser usado para mapear o token de acesso a um registro de usuário Snowflake.

Parâmetros opcionais

EXTERNAL_OAUTH_JWS_KEYS_URL = 'string_literal'

Especifica o ponto de extremidade a partir dos quais deve-se baixar chaves ou certificados públicos para validar um token de acesso do OAuth externo.

Esta sintaxe se aplica às integrações de segurança em que EXTERNAL_OAUTH_TYPE = OKTA | PING_FEDERATE | CUSTOM

EXTERNAL_OAUTH_JWS_KEYS_URL = 'string_literal' | ('string_literal' [ , 'string_literal' ... ] )

Especifica o ponto de extremidade ou uma lista de pontos de extremidade a partir dos quais baixar chaves ou certificados públicos para validar um token de acesso External OAuth. O número máximo de URLs que pode ser especificado na lista é 3.

Esta sintaxe se aplica às integrações de segurança em que EXTERNAL_OAUTH_TYPE = AZURE

EXTERNAL_OAUTH_RSA_PUBLIC_KEY = public_key1

Especifica uma chave pública RSA com codificação de Base64, sem os cabeçalhos -----BEGIN PUBLIC KEY----- e -----END PUBLIC KEY-----.

EXTERNAL_OAUTH_RSA_PUBLIC_KEY_2 = public_key2

Especifica uma segunda chave pública RSA, sem os cabeçalhos -----BEGIN PUBLIC KEY----- e -----END PUBLIC KEY-----. Utilizado para rotação de chaves.

EXTERNAL_OAUTH_BLOCKED_ROLES_LIST = ( 'role_name' [ , 'role_name' , ... ] )

Especifica a lista de funções que um cliente não pode definir como uma função primária. Uma função nesta lista não pode ser usada ao criar uma sessão do Snowflake baseada no token de acesso do servidor de autorização do OAuth externo.

Por padrão, esta lista inclui as funções ACCOUNTADMIN e SECURITYADMIN. Para remover estas funções privilegiadas da lista, use o comando ALTER ACCOUNT para definir o parâmetro de conta EXTERNAL_OAUTH_ADD_PRIVILEGED_ROLES_TO_BLOCKED_LIST como FALSE.

EXTERNAL_OAUTH_ALLOWED_ROLES_LIST = ( 'role_name' [ , 'role_name' , ... ] )

Especifica a lista de funções que o cliente pode definir como a função primária.

Uma função nesta lista não ser usada ao criar uma sessão do Snowflake baseada no token de acesso do servidor de autorização do OAuth externo.

Cuidado

Este parâmetro oferece suporte às funções do sistema ACCOUNTADMIN e SECURITYADMIN.

Tenha cuidado ao criar uma sessão de Snowflake com estas funções altamente privilegiadas definidas como a função primária.

EXTERNAL_OAUTH_AUDIENCE_LIST = ('string_literal')

Especifica valores adicionais que podem ser usados para a validação do token de acesso ao público além de usar a conta Snowflake do cliente URL (ou seja, <identificador_conta>.snowflakecomputing.com). Para obter mais informações, consulte Identificadores de conta.

Para obter mais detalhes sobre esta propriedade ao usar o Power BI SSO, consulte as integração de segurança do Power BI SSO.

Atualmente, múltiplos URLs de audiência podem ser especificados para clientes personalizados do OAuth externo somente. Cada URL deve ser delimitado por aspas simples, com uma vírgula separando cada URL. Por exemplo:

external_oauth_audience_list = ('https://example.com/api/v2/', 'https://example.com')
EXTERNAL_OAUTH_ANY_ROLE_MODE = DISABLE | ENABLE | ENABLE_FOR_PRIVILEGE

Especifica se o cliente ou usuário de OAuth pode usar uma função que não esteja definida no token de acesso do OAuth. Observe que, com uma integração do Power BI com o Snowflake, o usuário do PowerBI não pode mudar de função mesmo quando este parâmetro está habilitado.

  • DISABLE não permite que o cliente OAuth ou usuário troque de função (ou seja, use role <função>;). Padrão.

  • ENABLE permite que o cliente OAuth ou usuário troque de função.

  • ENABLE_FOR_PRIVILEGE permite que o cliente OAuth ou usuário troque de função somente para um cliente ou usuário com o privilégio USE_ANY_ROLE. Este privilégio pode ser concedido e revogado para uma ou mais funções disponíveis para o usuário. Por exemplo:

Observe que o valor pode ser opcionalmente delimitado por aspas simples (por exemplo, DISABLE ou 'DISABLE').

grant USE_ANY_ROLE on integration external_oauth_1 to role1;
revoke USE_ANY_ROLE on integration external_oauth_1 from role1;
EXTERNAL_OAUTH_SCOPE_DELIMITER = 'string_literal'

Especifica o delimitador de escopo no token de autorização.

O delimitador pode ser qualquer caractere individual, como vírgula (',') ou espaço (' ').

Esta propriedade de integração de segurança é opcional e pode ser usada para anular o delimitador de vírgula padrão. Note que esta propriedade só é suportada para integrações personalizadas do OAuth externo, onde:

EXTERNAL_OAUTH_TYPE = CUSTOM

Contate o suporte Snowflake para ativar essa propriedade em sua conta Snowflake.

Requisitos de controle de acesso

Uma função usada para executar este comando SQL deve ter os seguintes privilégios no mínimo:

Privilégio

Objeto

Notas

CREATE INTEGRATION

Conta

Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Controle de acesso no Snowflake.

Notas de uso

  • Em relação aos metadados:

    Atenção

    Os clientes devem garantir que nenhum dado pessoal (exceto para um objeto do usuário), dados sensíveis, dados controlados por exportação ou outros dados regulamentados sejam inseridos como metadados ao usar o serviço Snowflake. Para obter mais informações, consulte Campos de metadados no Snowflake.

  • Instruções CREATE OR REPLACE <object> são atômicas. Ou seja, quando o objeto é substituído, a exclusão do objeto antigo e a criação do novo objeto são processadas em uma única transação.

Exemplos

Exemplo do Microsoft Azure AD

O exemplo seguinte cria uma integração de segurança de OAuth externo para um servidor de autorização Microsoft Azure AD OAuth 2.0.

create security integration external_oauth_azure_1
    type = external_oauth
    enabled = true
    external_oauth_type = azure
    external_oauth_issuer = '<AZURE_AD_ISSUER>'
    external_oauth_jws_keys_url = '<AZURE_AD_JWS_KEY_ENDPOINT>'
    external_oauth_token_user_mapping_claim = 'upn'
    external_oauth_snowflake_user_mapping_attribute = 'login_name';

Ver as configurações de integração usando DESCRIBE INTEGRATION:

DESC SECURITY INTEGRATION external_oauth_azure_1;

Exemplo Okta

O exemplo seguinte cria uma integração de segurança de OAuth externo para um servidor de autorização Okta OAuth 2.0.

create security integration external_oauth_okta_1
    type = external_oauth
    enabled = true
    external_oauth_type = okta
    external_oauth_issuer = '<OKTA_ISSUER>'
    external_oauth_jws_keys_url = '<OKTA_JWS_KEY_ENDPOINT>'
    external_oauth_token_user_mapping_claim = 'sub'
    external_oauth_snowflake_user_mapping_attribute = 'login_name';

Ver as configurações de integração usando DESCRIBE INTEGRATION:

DESC SECURITY INTEGRATION external_oauth_okta_1;