사용자 지정 클라이언트용 Snowflake OAuth 구성하기¶

워크플로¶

사용자 지정 클라이언트를 위해 OAuth를 구성하려면 다음 개요 수준 단계가 필요합니다.

1. Snowflake에 클라이언트를 등록합니다. 클라이언트를 등록하려면 통합을 생성합니다. 통합은 OAuth를 지원하는 클라이언트와 같이 Snowflake와 서드 파티 서비스 간의 인터페이스를 제공하는 Snowflake 오브젝트입니다.

   등록 프로세스는 클라이언트 ID 및 클라이언트 시크릿을 정의합니다.

2. Snowflake OAuth 엔드포인트에 대한 호출을 구성하여 Snowflake 인증 서버에서 인증 코드를 요청하고 액세스 토큰을 요청 및 새로 고칩니다.

   초기 인증 요청의 선택적 《범위》 매개 변수는 액세스 토큰에서 허용되는 역할을 제한하고 새로 고침 토큰의 동작을 구성하기 위한 용도로 추가로 사용할 수 있습니다.

Snowflake OAuth 통합 만들기¶

CREATE SECURITY INTEGRATION 명령을 사용하여 Snowflake OAuth 통합을 생성합니다. 통합을 생성할 때 OAUTH_CLIENT = CUSTOM 을 지정해야 합니다.

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
  ...
  ';

OAuth 엔드포인트 호출하기¶

OAuth 엔드포인트는 클라이언트가 인증 코드를 요청하고 액세스 토큰을 요청 및 새로 고치기 위해 호출하는 URLs입니다. 이러한 엔드포인트는 엔드포인트가 호출될 때 실행되는 특정 OAuth 2.0 정책을 참조합니다.

Snowflake는 다음 OAuth 엔드포인트를 제공합니다.

인증

<snowflake_계정_url>/oauth/authorize

토큰 요청

<snowflake_계정_url>/oauth/token-request

여기서 < snowflake_account_url> 은 유효한 Snowflake 계정 URL입니다. 예를 들어 https://myorg-account_xyz.snowflakecomputing.com/oauth/authorize 및 https://myorg-account_xyz.snowflakecomputing.com/oauth/token-request 엔드포인트를 사용할 수 있습니다. Snowflake 계정 URL에 대해 지원되는 형식의 목록은 URL을 사용하여 연결하기 섹션을 참조하십시오.

보안 통합에 유효한 OAuth 엔드포인트의 목록을 보려면 DESCRIBE INTEGRATION 을 실행한 다음, OAUTH_ALLOWED_AUTHORIZATION_ENDPOINTS 및 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"
}

PKCE(Proof Key for Code Exchange)¶

Snowflake는 RFC 7636 의 설명과 같이 authorization_code 권한 타입을 사용하여 액세스 토큰을 획득하기 위한 PKCE(Proof Key for Code Exchange)를 지원합니다. PKCE를 사용하면 인증 코드 가로채기 공격의 가능성을 줄일 수 있으며, 클라이언트 시크릿의 보안을 완벽하게 보호할 수 없는 클라이언트에 적합합니다.

기본적으로, PKCE는 선택 사항이며 code_challenge 및 code_challenge_method 매개 변수가 둘 다 인증 엔드포인트 URL에 포함된 경우에만 적용됩니다. 하지만 Snowflake는 클라이언트의 모든 인증에서 PKCE를 요청하여 OAuth 흐름의 보안을 강화하는 것을 강력히 권장합니다.

다음을 Snowflake용 PKCE의 작동 방법을 설명합니다.

1. 클라이언트가 코드 검증 도구 라는 시크릿을 생성하고 변환을 수행하여 코드 챌린지 를 생성합니다. 클라이언트는 해당 시크릿을 유지합니다.

   중요

   RFC 7636의 섹션 4.1 에 따라 허용되는 ASCII 문자에서 코드 검증 도구 를 생성합니다.

2. 사용자를 인증 URL로 연결하는 클라이언트가 다음의 쿼리 매개 변수 2개를 추가합니다.

   code_challenge

   1단계에서 생성된 코드 챌린지를 지정합니다.

   code_challenge_method

   1단계의 코드 검증 도구에서 사용되는 변환을 지정하여 코드 챌린지를 생성합니다. 현재, Snowflake는 SHA256만 지원하므로, 이 값은 반드시 S256 으로 설정되어야 합니다. SHA256용 변환 알고리즘은 BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) 입니다.

3. 사용자가 요청된 범위에 동의한 후 또는 Snowflake가 해당 사용자에 대한 동의가 있는 것으로 판단한 후 인증 코드가 발급됩니다.

4. 클라이언트는 Snowflake 인증 서버로부터 인증 코드를 수신한 후 요청의 code_verifier 와 함께 토큰 엔드포인트에 제출합니다.

5. Snowflake는 code_verifier 값을 변환하고 변환된 값이 인증을 생성할 때 사용된 code_challenge 값과 일치하는지 확인합니다. 이러한 값이 일치하면 인증 서버는 액세스 토큰 및 새로 고침 토큰을 발급합니다.

키 페어 인증 사용하기¶

Snowflake는 OAuth 토큰 엔드포인트를 호출할 때 일반적인 사용자 이름/비밀번호 인증이 아닌 키 페어 인증을 사용하는 것을 지원합니다. 이 인증 메서드에는 2048비트(최소) RSA 키 페어가 필요합니다. OpenSSL을 사용하여 PEM(Privacy Enhanced Mail) 공개-개인 키 페어을 생성합니다. 공개 키는 Snowflake 클라이언트를 사용하는 Snowflake 사용자에게 할당됩니다.

공개/개인 키 페어를 구성하려면:

1. 터미널 창의 명령줄에서 암호화된 개인 키를 생성합니다.

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

   Copy

   개인 키 파일을 암호화하기 위해 사용된 암호 구문을 입력하라는 메시지가 OpenSSL에 표시됩니다. Snowflake는 강력한 암호 구문을 사용하여 개인 키를 보호하는 것을 권장합니다. 이 암호 구문을 기록해 둡니다. Snowflake에 연결할 때 이 암호 구문을 입력해야 합니다. 암호 구문은 개인 키를 보호하기 위한 용도로만 사용되며, 절대로 Snowflake로 전송되지 않습니다.

   샘플 PEM 개인 키

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

   Copy

2. 명령줄에서 개인 키를 참조하여 공개 키를 생성합니다.

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

   Copy

   샘플 PEM 공개 키

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

   Copy

3. 공개 및 개인 키 파일을 로컬 디렉터리로 복사하여 저장합니다. 파일 경로를 기록해 둡니다.

   개인 키는 PKCS#8(공개 키 암호화 표준) 형식을 사용하여 저장되며 이전 스테이지에서 지정한 암호 구문을 사용하여 암호화되지만, 파일은 운영 체제에서 제공하는 파일 권한 방식을 사용하여 무단 액세스로부터 보호되어야 한다는 점에 유의하십시오. 파일을 사용하지 않을 때 파일을 보호하는 것은 사용자의 책임입니다.

4. ALTER SECURITY INTEGRATION 을 사용하여 통합 오브젝트에 공개 키를 할당합니다. 예:

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

   Copy

   참고

   • 계정 관리자만 ALTER SECURITY INTEGRATION 명령을 실행할 수 있습니다.

   • 명령에서 공개 키 헤더와 푸터를 제외합니다.

   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

   참고

   OAUTH_CLIENT_RSA_PUBLIC_KEY_2_FP 속성에 대한 설명은 이 항목의 키 순환 에서 제공됩니다.

5. 아래 샘플 코드를 수정하여 실행합니다. 이 코드는 개인 키를 사용하여 JWT를 인코딩한 다음, 해당 토큰을 Snowflake 인증 서버로 전달합니다.

   • 보안 매개 변수를 업데이트합니다.

     • <개인_키>: 텍스트 편집기에서 rsa_key.p8 파일을 열고 BEGIN 머리글과 END 바닥글 사이의 줄을 복사합니다.

   • 세션 매개 변수를 업데이트합니다.

     • <account_identifier>: 계정(Snowflake에서 제공)의 전체 이름을 지정합니다.

   • JSON 웹 토큰(JWT) 필드를 업데이트합니다.

     post body

     다음 표준 필드(《클레임》)를 갖는 JSON 오브젝트:

     속성	데이터 타입	필수	설명
     iss	문자열	예	client_id.public_key_fp 형식으로 JWT를 발급한 주체를 지정합니다. 여기서 client_id 는 OAuth 클라이언트 통합의 클라이언트 ID이며 public_key_fp 는 확인 중에 사용되는 공개 키의 지문입니다.
     sub	문자열	예	account_identifier.client_id 형식의 JWT 주체입니다. 여기서 account_identifier 는 Snowflake 계정의 전체 이름이며 client_id 는 OAuth 클라이언트 통합의 클라이언트 ID입니다. 계정이 호스팅된 클라우드 플랫폼(AWS 또는 Azure) 및 리전에 따라, 전체 계정 이름에 추가 세그먼트가 필요할 수 있습니다. 자세한 내용은 토큰 엔드포인트 아래의 account 변수 설명을 참조하십시오.
     iat	타임스탬프	아니요	토큰이 발급된 시간입니다.
     exp	타임스탬프	예	토큰이 만료되어야 하는 시간입니다. 이 기간은 상대적으로 짧아야 합니다(예: 몇 분).

   샘플 코드

   private_key 값에는 -----BEGIN 머리글과 -----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

   토큰이 생성된 후 토큰 엔드포인트로의 요청에서 제출합니다. 요청에서는 다음과 같이 클라이언트 ID 및 클라이언트 시크릿에서 일반적으로 사용되는 기본 인증 형식이 아닌 전달자 인증 형식이 인증 헤더로 필요합니다.

   "Authorization: Bearer JWT_TOKEN"
   

   Copy

오류 코드¶

인증 흐름, 토큰 요청 또는 교환 중 또는 OAuth 흐름 완료 후 Snowflake 세션 생성 시 OAuth와 관련된 오류 코드 목록 및 JSON blob에 반환된 오류에 대해서는 오류 코드 를 참조하십시오.

역할에 대한 사용자 동의 사전 승인하기¶

보안 관리자(즉, SECURITYADMIN 역할의 사용자) 또는 이상은 클라이언트가 지정된 역할 및 통합을 사용하여 사용자에 대한 세션을 시작하는 동의를 사전에 승인할 수 있습니다. 이 동의는 ADD DELEGATED AUTHORIZATION 키워드와 함께 ALTER USER 를 사용하여 허가됩니다. 이러한 위임된 권한이 부여되지 않은 경우에는 사용자가 인증한 후에 반드시 역할에 대한 동의를 승인해야 합니다. 이러한 위임된 권한 부여도 취소할 수 있습니다.

자세한 내용은 OAuth에 대한 사용자 동의 관리하기 섹션을 참조하십시오.