External OAuth용 사용자 지정 인증 서버 구성하기

이 항목에서는 Snowflake에서 External OAuth 보안 통합을 생성하여 클라이언트가 사용자 지정 인증 서버로 인증하여 Snowflake 데이터에 액세스할 수 있도록 하는 방법을 설명합니다.

인증 서버가 사용자 지정 공급자가 아니라 지원되는 ID 공급자(IdP) 인 경우 특정 IdP 구성에 초점을 맞춘 항목을 참조하십시오.

이 항목의 내용:

External OAuth 토큰 페이로드 요구 사항

사용자 지정 인증 서버가 Snowflake에 보내는 액세스 토큰은 다음 페이로드 정보를 포함해야 합니다. 클레임 열에 대한 자세한 내용은 JWT 클레임 을 참조하십시오.

클레임

설명

scp

범위입니다. 액세스 토큰에서 범위 목록입니다.

범위

범위입니다.

액세스 토큰에서 쉼표로 구분된 범위 문자열입니다.

Snowflake는 사용자 지정 인증 서버에 대한 External OAuth 보안 통합을 생성 하거나 수정 할 때 EXTERNAL_OAUTH_SCOPE_DELIMITER 속성을 설정하여 공백(즉, ' ')과 같은 구분 기호에 대한 단일 문자 지정을 지원합니다.

Snowflake 계정에서 이 속성을 활성화하려면 Snowflake 지원 에 문의하십시오.

aud

대상 그룹입니다. 액세스 토큰의 대상이 되는 수신자를 URI 문자열로 나타냅니다.

exp

만료 시간입니다. 이 시간 또는 이후에 액세스 토큰이 처리되지 않아야 하는 만료 시간을 나타냅니다.

iss

발급자입니다. 액세스 토큰을 URI 문자열로 발급한 주체를 나타냅니다.

iat

발급 시간입니다. 필수 항목입니다. JWT가 발급된 시간을 나타냅니다.

참고

Snowflake는 nbf (not before의 약자로 이전 아님을 의미) 클레임을 지원하며, 이는 이 시간 전에 액세스 토큰이 처리되지 않아야 하는 시간을 나타냅니다.

사용자 지정 인증 서버에서 nbf (이전 아님) 클레임을 지원하는 경우에는 선택적으로 액세스 토큰에 nbf 클레임을 포함할 수 있습니다.

토큰에 필수 정보가 포함되는지 확인하려면 이 JSON 웹 토큰 사이트에서 토큰을 테스트할 수 있습니다.

대표적인 예로, PAYLOAD: DATA 인터페이스에는 토큰 페이로드가 다음과 같이 표시됩니다.

{
  "aud": "<audience_url>",
  "iat": 1576705500,
  "exp": 1576709100,
  "iss": "<issuer_url>",
  "scp": [
    "session:role:analyst"
  ]
}
Copy

구성 절차

다음 단계에서는 사용자 지정 서버 및 환경을 구성하여 Snowflake 보안 통합을 생성하기 위해 필요한 값을 얻을 수 있는 상황을 가정합니다.

중요

이 항목의 단계는 사용자 지정 인증 서버를 구성하는 방법을 보여주는 대표적인 예 입니다.

환경을 원하는 상태로 구성하고 원하는 OAuth 흐름을 구성할 수도 있습니다. 단, External OAuth 보안 통합 에 대하여 필요한 정보를 얻을 수 있어야 합니다.

다음 단계는 Snowflake에서 External OAuth 보안 통합을 생성하기 위해 필요한 정보를 얻기 위한 가이드라는 점에 유의하십시오.

사용자 지정 인증 서버를 구성하기 전에 내부 보안 정책을 참조하여 자신이 속한 조직이 모든 규정 및 규정 준수 요구 사항을 충족하는지 확인하십시오.

External OAuth를 사용하기 위한 주요 환경 값 얻기

IdP 및 인증 서버를 구성할 때 다음 값을 수집하여 External OAuth 보안 통합을 정의해야 합니다.

발급자 URL:

external_oauth_issuer 매개 변수와 함께 이 URL을 포함합니다.

RSA 공개 키:

external_oauth_rsa_public_key 매개 변수와 함께 이 값을 포함합니다.

대상 그룹 URLs:

대상 그룹 URL이 1개 이상 필요한 경우 external_oauth_audience_list 매개 변수에서 각 URL을 쉼표로 구분합니다.

범위 속성:

이 값을 scp 또는 scope 로 설정할 수 있습니다. 기본적으로 이 값은 scp 입니다.

external_oauth_scope_mapping_attribute 매개 변수의 값을 이 값으로 설정할 수 있습니다.

기본값 scp 를 사용하지 않는 경우 external_oauth_scope_mapping_attribute 매개 변수의 값을 scope 로 설정합니다.

자세한 내용은 External OAuth 토큰 페이로드 요구 사항 섹션을 참조하십시오.

사용자 속성:

이 속성은 IdP에서 사용자를 식별하기 위한 속성을 참조합니다. external_oauth_user_mapping_claim 매개 변수에 이 속성 값을 포함합니다.

Snowflake 사용자 속성:

사용자를 식별하기 위한 Snowflake의 속성입니다. external_oauth_snowflake_user_mapping_attribute 매개 변수에 이 값을 포함합니다.

Snowflake에서 External OAuth 보안 통합 만들기

이 단계에서는 Snowflake에서 External OAuth 보안 통합을 만듭니다. External OAuth 보안 통합은 Snowflake가 사용자 지정 인증 서버와 안전하게 통신하고 이 서버에서 액세스 토큰의 유효성을 검사할 수 있으며 액세스 토큰과 연결된 사용자 역할을 기반으로 Snowflake 데이터에 대한 사용자 액세스를 제공하도록 보장합니다. 자세한 내용은 CREATE SECURITY INTEGRATION 을 참조하십시오.

중요

계정 관리자 또는 전역 CREATE INTEGRATION 권한이 있는 역할만 이 SQL 명령을 실행할 수 있습니다.

External OAuth 보안 통합 매개 변수 값에서는 대/소문자가 구분되며 External OAuth 보안 통합에 입력한 값은 환경의 해당 값과 일치해야 합니다. 값의 대/소문자가 일치하지 않으면 액세스 토큰을 확인할 수 없어 인증이 실패하게 됩니다.

Snowflake에서 External OAuth 보안 통합 만들기

create security integration external_oauth_custom
    type = external_oauth
    enabled = true
    external_oauth_type = custom
    external_oauth_issuer = '<authorization_server_url>'
    external_oauth_rsa_public_key = '<public_key_value>'
    external_oauth_audience_list = ('<audience_url_1>', '<audience_url_2>')
    external_oauth_token_user_mapping_claim = 'upn'
    external_oauth_snowflake_user_mapping_attribute = 'login_name';
Copy

외부 OAuth 보안 통합 수정하기

외부 OAuth 보안 통합은 보안 통합에서 ALTER 문을 실행하여 업데이트할 수 있습니다.

자세한 내용은 ALTER SECURITY INTEGRATION(External OAuth) 섹션을 참조하십시오.

External OAuth가 포함된 ANY 역할 사용하기

Snowflake에서 보안 통합을 생성하기 위한 구성 단계에서 OAuth 액세스 토큰에는 범위 정의가 포함됩니다. 그러므로 런타임 시점에 외부 OAuth 보안 통합을 사용하면 OAuth 클라이언트와 사용자 모두 OAuth 액세스 토큰에 정의되지 않은 역할을 사용할 수 없습니다.

액세스 토큰의 유효성을 검사하고 세션을 생성한 후 ANY 역할은 OAuth 클라이언트 및 사용자가 자체 역할을 결정하는 것을 허용합니다. 필요한 경우 클라이언트 또는 사용자는 OAuth 액세스 토큰에 정의된 역할과 다른 역할로 전환할 수 있습니다.

ANY 역할을 구성하려면 범위를 SESSION:ROLE-ANY 로 정의하고 external_oauth_any_role_mode 매개 변수를 사용하여 보안 통합을 구성합니다. 이 매개 변수에서 사용할 수 있는 3가지 문자열 값은 다음과 같습니다.

  • DISABLE 로 지정하면 OAuth 클라이언트 또는 사용자가 역할(즉, use role <역할>;)을 전환할 수 없습니다. 기본값입니다.

  • ENABLE 로 지정하면 OAuth 클라이언트 또는 사용자가 역할을 전환할 수 있습니다.

  • ENABLE_FOR_PRIVILEGE 로 지정하면 OAuth 클라이언트 또는 사용자가 USE_ANY_ROLE 권한을 가진 클라이언트 또는 사용자에 대해서만 역할을 전환할 수 있습니다. 사용자가 사용할 수 있는 1개 이상의 역할에 이 권한을 부여하고 취소할 수 있습니다. 예:

    grant USE_ANY_ROLE on integration external_oauth_1 to role1;
    
    Copy
    revoke USE_ANY_ROLE on integration external_oauth_1 from role1;
    
    Copy

보안 통합을 다음과 같이 정의합니다.

create security integration external_oauth_1
    type = external_oauth
    enabled = true
    external_oauth_any_role_mode = 'ENABLE'
    ...
Copy

External OAuth가 포함된 보조 역할 사용하기

기본 역할에 대해 원하는 범위가 외부 토큰으로 전달되는데, 사용자의 기본 역할(session:role-any) 또는 사용자에게 부여된 특정 역할(session:role:<역할_이름>)입니다.

기본적으로 Snowflake는 세션에서 사용자(즉, DEFAULT_SECONDARY_ROLES)에 대한 기본 보조 역할 을 활성화하지 않습니다.

세션에서 사용자의 기본 보조 역할을 활성화하고 External OAuth를 사용하는 동안 USE SECONDARY ROLES 명령의 실행을 허용하려면 다음 단계를 완료하십시오.

  1. 연결을 위한 보안 통합을 구성합니다. (CREATE SECURITY INTEGRATION을 사용하여) 보안 통합을 만들 때나 나중에 (ALTER SECURITY INTEGRATION을 사용하여) EXTERNAL_OAUTH_ANY_ROLE_MODE 매개 변수 값을 ENABLE 또는 ENABLE_FOR_PRIVILEGE로 설정합니다.

  2. 토큰의 범위 속성에서 session:role-any 의 정적 값을 전달하도록 인증 서버를 구성합니다. 범위 매개 변수에 대한 자세한 내용은 External OAuth 개요 섹션을 참조하십시오.

External OAuth에서 클라이언트 리디렉션 사용하기

Snowflake는 지원되는 Snowflake 클라이언트에서 클라이언트 리디렉션과 External OAuth 사용을 포함하여, External OAuth에서의 클라이언트 리디렉션 사용을 지원합니다.

자세한 내용은 클라이언트 연결 리디렉션하기 섹션을 참조하십시오.

External OAuth가 포함된 네트워크 정책 사용하기

현재는 네트워크 정책을 외부 OAuth 보안 통합에 추가할 수 없습니다. 하지만 전체 Snowflake 계정에 광범위하게 적용되는 네트워크 정책을 계속 구현할 수 있습니다.

사용 사례에서 OAuth 보안 통합과 관련된 네트워크 정책이 필요한 경우 Snowflake OAuth 를 사용하십시오. 이 접근 방식을 사용하면 Snowflake OAuth 네트워크 정책을 Snowflake 계정에 적용될 수 있는 다른 네트워크 정책과 구분할 수 있습니다.

자세한 내용은 네트워크 정책 섹션을 참조하십시오.

External OAuth로 복제 사용하기

Snowflake는 원본 계정에서 대상 계정으로의 외부 OAuth 보안 통합의 복제 및 장애 조치/장애 복구를 지원합니다.

자세한 내용은 여러 계정에 보안 통합 및 네트워크 정책 복제 섹션을 참조하십시오.

절차 테스트하기

사용자 지정 인증 서버의 구성을 테스트하는 방법:

  1. 테스트 사용자가 IdP에 있고 비밀번호가 설정되었는지 확인합니다.

  2. login_name 속성 값이 <외부_oauth_토큰_사용자_매핑_클레임> 으로 설정된 테스트 사용자가 Snowflake에 있는지 확인합니다.

  3. OAuth 2.0 클라이언트를 등록합니다.

  4. 다음과 같이 OAuth 2.0 클라이언트가 사용자 지정 토큰 엔드포인트에 POST 요청을 할 수 있도록 허용합니다.

    • 리소스 소유자로 설정된 권한 부여 타입

    • clientID 및 시크릿이 포함된 HTTP 기본 인증 헤더

    • 사용자 이름 및 비밀번호가 포함된 FORM 데이터

    • 범위 포함

샘플 명령에서는 ANALYST 사용자 지정 역할을 요청하며 session:role:analyst 가 사용자 지정 인증 서버에 정의된 것으로 가정합니다.

cURL을 사용하여 액세스 토큰을 획득하는 예는 다음과 같습니다.

curl -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
  --user <OAUTH_CLIENT_ID>:<OAUTH_CLIENT_SECRET> \
  --data-urlencode "username=<IdP_USER_USERNAME>" \
  --data-urlencode "password=<IdP_USER_PASSWORD>" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "scope=session:role:analyst" \
  <IdP_TOKEN_ENDPOINT>
Copy

외부 OAuth를 사용하여 Snowflake에 연결하기

보안 통합을 구성하고 액세스 토큰을 얻은 후에는 다음 중 하나를 사용하여 Snowflake에 연결할 수 있습니다.

다음 사항을 참고하십시오.

  • authenticator 매개 변수를 oauth 로 설정하고 token 매개 변수를 external_oauth_access_token 으로 설정해야 합니다.

  • token 값을 URL 쿼리 매개 변수로 전달할 때는 token 값을 URL로 인코딩해야 합니다.

  • token 값을 속성 오브젝트(예: JDBC 드라이버)로 전달할 때는 수정할 필요가 없습니다.

예를 들어, Python Connector를 사용하는 경우에는 연결 문자열을 아래와 같이 설정해야 합니다.

ctx = snowflake.connector.connect(
   user="<username>",
   host="<hostname>",
   account="<account_identifier>",
   authenticator="oauth",
   token="<external_oauth_access_token>",
   warehouse="test_warehouse",
   database="test_db",
   schema="test_schema"
)
Copy

이제 외부 OAuth을 사용하여 안전하게 Snowflake에 연결할 수 있습니다.