Configuração do Snowflake OAuth para clientes personalizados¶

Fluxo de trabalho¶

As seguintes etapas de alto nível são necessárias para configurar o OAuth para clientes personalizados:

1. Registre seu cliente no Snowflake. Para registrar seu cliente, crie uma integração. Uma integração é um objeto Snowflake que fornece uma interface entre o Snowflake e serviços de terceiros, tais como um cliente que suporta OAuth.

   O processo de registro define uma ID de cliente e os segredos do cliente.

2. Configure chamadas para os pontos de extremidade Snowflake OAuth para solicitar códigos de autorização do servidor de autorização do Snowflake e para solicitar e atualizar tokens de acesso.

   Os parâmetros opcionais de “escopo” no solicitação de autorização inicial limitam a função permitida pelo token de acesso e podem, adicionalmente, ser usados para configurar o comportamento de atualização de token.

Criação de uma integração do Snowflake OAuth¶

Crie uma integração do Snowflake OAuth usando o comando CREATESECURITYINTEGRATION. Certifique-se de especificar OAUTH_CLIENT = CUSTOM ao criar a integração.

CREATE SECURITY INTEGRATION oauth_kp_int
  TYPE = OAUTH
  ENABLED = TRUE
  OAUTH_CLIENT = CUSTOM
  OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
  OAUTH_REDIRECT_URI = 'https://localhost.com'
  OAUTH_ISSUE_REFRESH_TOKENS = TRUE
  OAUTH_REFRESH_TOKEN_VALIDITY = 86400
  BLOCKED_ROLES_LIST = ('SYSADMIN')
  OAUTH_CLIENT_RSA_PUBLIC_KEY ='
  MIIBI
  ...
  ';

Chamada dos pontos de extremidade do OAuth¶

Pontos de extremidade do OAuth são as URLs que os clientes chamam para solicitar códigos de autorização e para solicitar e atualizar tokens de acesso. Estes pontos de extremidade referem-se a políticas específicas do OAuth 2.0 executadas quando o ponto de extremidade é chamado.

O Snowflake oferece os seguintes pontos de extremidade OAuth:

Autorização:

<snowflake_account_url>/oauth/authorize

Solicitações de token:

<snowflake_account_url>/oauth/token-request

Em que <snowflake_account_url> é uma URL válida da conta Snowflake. Por exemplo, você pode usar os pontos de extremidade https://myorg-account_xyz.snowflakecomputing.com/oauth/authorize e https://myorg-account_xyz.snowflakecomputing.com/oauth/token-request. Para obter uma lista de formatos compatíveis com a URL de conta Snowflake, consulte Conexão com uma URL.

Para ver uma lista de pontos de extremidade OAuth válidos para uma integração de segurança, execute DESCRIBE INTEGRATION e confira os valores nas propriedades OAUTH_ALLOWED_AUTHORIZATION_ENDPOINTS e OAUTH_ALLOWED_TOKEN_ENDPOINTS.

<snowflake_account_url>/oauth/authorize

<snowflake_account_url>/oauth/token-request

Content-type: application/x-www-form-urlencoded

{
  "access_token":  "ACCESS_TOKEN",
  "expires_in": 600,
  "refresh_token": "REFRESH_TOKEN",
  "token_type": "Bearer",
  "username": "user1",
}

{
  "data" : null,
  "message" : "This is an invalid client.",
  "code" : null,
  "success" : false,
  "error" : "invalid_client"
}

Proof Key for Code Exchange¶

O Snowflake suporta o Proof Key for Code Exchange (PKCE) para obter tokens de acesso usando o tipo de concessão authorization_code, conforme descrito em RFC 7636. O PKCE pode ser usado para diminuir a possibilidade de um ataque de interceptação de código de autorização e é adequado para clientes que podem não ser capazes de manter o segredo do cliente totalmente seguro.

Por padrão, o PKCE é opcional e só é aplicado se os parâmetros code_challenge e code_challenge_method estiverem ambos incluídos na URL do ponto de extremidade de autorização. Entretanto, o Snowflake recomenda fortemente que seu cliente exija PKCE para todas as autorizações para tornar o fluxo OAuth mais seguro.

O seguinte descreve como o PKCE para Snowflake funciona:

1. O cliente cria um segredo chamado verificador de código e realiza uma transformação nele para gerar o desafio do código. O cliente guarda o segredo.

   Importante

   Gere o verificador de código a partir dos caracteres ASCII permitidos de acordo com a Seção 4.1 do RFC 7636.

2. O cliente que direciona o usuário para a URL da autorização anexa os dois parâmetros de consulta seguintes:

   code_challenge

   Especifica o desafio de código gerado na Etapa 1.

   code_challenge_method

   Especifica as transformações usadas no verificador de código na Etapa 1 para gerar o desafio do código. Atualmente, o Snowflake suporta apenas SHA256, portanto, este valor deve ser definido como S256. O algoritmo de transformação para SHA256 é BASE64URL-ENCODE(SHA256(ASCII(code_verifier))).

3. Depois que o usuário consente nos escopos solicitados ou o Snowflake determina que o consentimento está presente para esse usuário, o código de autorização é emitido.

4. O cliente recebe o código de autorização do servidor de autorização do Snowflake, que ele então submete junto com o code_verifier na solicitação ao ponto de extremidade de token.

5. Snowflake transforma o valor code_verifier e verifica se o valor transformado corresponde ao valor code_challenge usado na geração de autorizações. Se esses valores corresponderem, então o servidor de autorização emite os tokens de acesso e de atualização.

Uso de autenticação de pares de chaves¶

O Snowflake suporta o uso da autenticação de par de chaves em vez da típica autenticação por nome de usuário/senha ao chamar o ponto de extremidade de token OAuth. Este método de autenticação requer um par de chaves RSA de 2048 bits (mínimo). Gere o par de chaves pública-privada PEM (Privacy Enhanced Mail) usando OpenSSL. A chave pública é atribuída ao usuário do Snowflake que usa o cliente Snowflake.

Para configurar o par de chaves pública/privada:

1. A partir da linha de comando em uma janela terminal, gere uma chave privada criptografada:

   $ openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 des3 -inform PEM -out rsa_key.p8
   

   Copy

   O OpenSSL solicita uma senha usada para criptografar o arquivo de chave privada. O Snowflake recomenda o uso de uma senha forte para proteger a chave privada. Registre esta senha. Você deve inseri-la ao conectar-se ao Snowflake. Note que a senha é usada apenas para proteger a chave privada e nunca é enviada ao Snowflake.

   Exemplo de chave privada PEM

   -----BEGIN ENCRYPTED PRIVATE KEY-----
   MIIE6TAbBgkqhkiG9w0BBQMwDgQILYPyCppzOwECAggABIIEyLiGSpeeGSe3xHP1
   wHLjfCYycUPennlX2bd8yX8xOxGSGfvB+99+PmSlex0FmY9ov1J8H1H9Y3lMWXbL
   ...
   -----END ENCRYPTED PRIVATE KEY-----
   

   Copy

2. A partir da linha de comando, gere a chave pública, referenciando a chave privada:

   $ openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
   

   Copy

   Exemplo de chave pública PEM

   -----BEGIN PUBLIC KEY-----
   MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy+Fw2qv4Roud3l6tjPH4
   zxybHjmZ5rhtCz9jppCV8UTWvEXxa88IGRIHbJ/PwKW/mR8LXdfI7l/9vCMXX4mk
   ...
   -----END PUBLIC KEY-----
   

   Copy

3. Copie os arquivos de chaves públicas e privadas em um diretório local para armazenamento. Registre o caminho para os arquivos.

   Observe que a chave privada é armazenada usando o formato PKCS8 (Public Key Cryptography Standards) e é criptografada usando a senha especificada no passo anterior; entretanto, o arquivo ainda deve ser protegido contra acesso não autorizado usando o mecanismo de permissão de arquivo fornecido por seu sistema operacional. É sua responsabilidade proteger o arquivo quando ele não estiver sendo usado.

4. Atribua a chave pública ao objeto de integração usando ALTERSECURITYINTEGRATION. Por exemplo:

   ALTER SECURITY INTEGRATION myint SET OAUTH_CLIENT_RSA_PUBLIC_KEY='MIIBIjANBgkqh...';
   

   Copy

   Nota

   • Somente os administradores de conta podem executar o comando ALTER SECURITY INTEGRATION.

   • Exclua o cabeçalho e rodapé da chave pública no comando.

   Verifique a impressão digital da chave pública usando DESCRIBE INTEGRATION:

   DESC SECURITY INTEGRATION myint;
   
   +----------------------------------+---------------+----------------------------------------------------------------------+------------------+
   | property                         | property_type | property_value                                                       | property_default |
   |----------------------------------+---------------+----------------------------------------------------------------------+------------------|
   ...
   | OAUTH_CLIENT_RSA_PUBLIC_KEY_FP   | String        | SHA256:MRItnbO/123abc/abcdefghijklmn12345678901234=                  |                  |
   | OAUTH_CLIENT_RSA_PUBLIC_KEY_2_FP | String        |                                                                      |                  |
   ...
   +----------------------------------+---------------+----------------------------------------------------------------------+------------------+
   

   Copy

   Nota

   A propriedade OAUTH_CLIENT_RSA_PUBLIC_KEY_2_FP está descrita em Rodízio de chaves (neste tópico).

5. Modifique e execute o código de exemplo abaixo. O código usa a chave privada para codificar um JWT e depois passa esse token para o servidor de autorização do Snowflake:

   • Atualize os parâmetros de segurança:

     • <private_key>: abra o arquivo rsa_key.p8 em um editor de texto e copie as linhas entre o cabeçalho BEGIN e o rodapé END.

   • Atualize os parâmetros da sessão:

     • <account_identifier>: Especifica o nome completo de sua conta (fornecido pelo Snowflake).

   • Atualize os campos JSON Web Token (JWT):

     post body

     Um objeto JSON com os seguintes campos padrão (“declarações”):

     Atributo	Tipo de dados	Obrigatório	Descrição
     iss	Cadeia de caracteres	Sim	Especifica a entidade de segurança que emitiu o JWT no formato client_id.public_key_fp onde client_id é a ID de cliente da integração do cliente OAuth e public_key_fp é a impressão digital da chave pública que é usada durante a verificação.
     sub	Cadeia de caracteres	Sim	Assunto do JWT no formato account_identifier.client_id onde account_identifier é o nome completo de sua conta Snowflake e client_id é a ID de cliente da integração do cliente OAuth. Dependendo da plataforma de nuvem (AWS ou Azure) e da região onde sua conta está hospedada, o nome completo da conta pode exigir segmentos adicionais. Para obter mais informações, consulte a descrição da variável account em Ponto de extremidade de token.
     iat	Carimbo de data/hora	Não	Hora em que o token foi emitido.
     exp	Carimbo de data/hora	Sim	Hora em que o token deve expirar. Este período deve ser relativamente curto (por exemplo, alguns minutos).

   Código de exemplo

   Observe que o valor private_key inclui o cabeçalho -----BEGIN e o rodapé -----END.

   import datetime
   import json
   import urllib
   
   import jwt
   import requests
   
   private_key = """
   <private_key>
   """
   
   public_key_fp = "SHA256:MR..."
   
   
   def _make_request(payload, encoded_jwt_token):
       token_url = "https://<account_identifier>.snowflakecomputing.com/oauth/token-request"
       headers = {
               u'Authorization': "Bearer %s" % (encoded_jwt_token),
               u'content-type': u'application/x-www-form-urlencoded'
       }
       r = requests.post(
               token_url,
               headers=headers,
               data=urllib.urlencode(payload))
       return r.json()
   
   
   def make_request_for_access_token(oauth_az_code, encoded_jwt_token):
       """ Given an Authorization Code, make a request for an Access Token
       and a Refresh Token."""
       payload = {
           'grant_type': 'authorization_code',
           'code': oauth_az_code
       }
       return _make_request(payload, encoded_jwt_token)
   
   
   def make_request_for_refresh_token(refresh_token, encoded_jwt_token):
       """ Given a Refresh Token, make a request for another Access Token."""
       payload = {
           'grant_type': 'refresh_token',
           'refresh_token': refresh_token
       }
       return _make_request(payload, encoded_jwt_token)
   
   
   def main():
       account_identifier = "<account_identifier>"
       client_id = "1234"  # found by running DESC SECURITY INTEGRATION
       issuer = "{}.{}".format(client_id, public_key_fp)
       subject = "{}.{}".format(account_identifier, client_id)
       payload = {
           'iss': issuer,
           'sub': subject,
           'iat': datetime.datetime.utcnow(),
           'exp': datetime.datetime.utcnow() + datetime.timedelta(seconds=30)
       }
       encoded_jwt_token = jwt.encode(
               payload,
               private_key,
               algorithm='RS256')
   
       data = make_request_for_access_token(oauth_az_code, encoded_jwt_token)
       refresh_token = data['refresh_token']
       data = make_request_for_refresh_token(refresh_token, encoded_jwt_token)
       access_token = data['access_token']
   
   
   if __name__ == '__main__':
       main()
   

   Copy

   Após a criação do token, envie-o em solicitações ao ponto de extremidade de token. As solicitações exigem o formato de autorização Bearer como o cabeçalho da autorização, em vez do formato básico de autorização normalmente usado para ID de cliente e segredo do cliente, como se segue:

   "Authorization: Bearer JWT_TOKEN"
   

   Copy

Códigos de erro¶

Consulte em Códigos de erro uma lista de códigos de erro associados ao OAuth, bem como erros que são retornados no blob JSON, durante o fluxo de autorização, solicitação ou troca de tokens ou ao criar uma sessão do Snowflake após completar o fluxo OAuth.

Pré-autorização do consentimento do usuário para uma função¶

Os administradores de segurança (ou seja, usuários com a função SECURITYADMIN) ou superior podem autorizar previamente o consentimento para que um cliente inicie uma sessão para um usuário usando uma função e integração especificadas. Este consentimento é concedido usando ALTER USER com as palavras-chave ADD DELEGATED AUTHORIZATION. Sem esta autorização delegada, o usuário precisa autorizar o consentimento para a função após a autenticação. Esta autorização delegada também pode ser revogada.

Para obter mais informações, consulte Gerenciamento do consentimento do usuário para OAuth.