CREATE SECURITY INTEGRATION

CREATE SECURITY INTEGRATION (External OAuth)

계정에 새 External OAuth 보안 인티그레이션(security integration)을 만들거나 기존 인티그레이션을 교체하는 명령이에요. External OAuth 보안 인티그레이션은 클라이언트가 타사 인가 서버를 사용해 Snowflake와 상호작용하는 데 필요한 액세스 토큰을 얻을 수 있게 해요.

출처: 문서

본문

계정에 새 External OAuth 보안 인티그레이션을 만들거나 기존 인티그레이션을 교체해요. External OAuth 보안 인티그레이션은 클라이언트가 타사 인가 서버를 사용해 Snowflake와 상호작용하는 데 필요한 액세스 토큰을 얻을 수 있게 해요.

⚠️ 주의: Microsoft Azure Active Directory에 대한 언급은 Microsoft Entra ID를 가리켜요.

다른 유형(예: Snowflake OAuth)의 보안 인티그레이션을 만드는 방법은 CREATE SECURITY INTEGRATION을 참고해요.

함께 보기: ALTER SECURITY INTEGRATION (External OAuth), DROP INTEGRATION, SHOW INTEGRATIONS

구문 (Syntax)

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>' | ('<string_literal>' [ , '<string_literal>' , ... ] ) } ]
  [ 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>' | ('<string_literal>' [ , '<string_literal>' , ... ] ) } ]
  [ EXTERNAL_OAUTH_ANY_ROLE_MODE = { DISABLE | ENABLE | ENABLE_FOR_PRIVILEGE } ]
  [ EXTERNAL_OAUTH_SCOPE_DELIMITER = '<string_literal>' ]
  [ EXTERNAL_OAUTH_SCOPE_MAPPING_ATTRIBUTE = '<string_literal>' ]
  [ IS_AGENTIC = { TRUE | FALSE } ]
  [ NETWORK_POLICY = '<network_policy>' ]
  [ COMMENT = '<string_literal>' ]

필수 매개변수 (Required parameters)

name 인티그레이션의 식별자(즉 이름)를 지정하는 문자열로, 계정 안에서 고유해야 해요.

또한 식별자는 반드시 알파벳 문자로 시작해야 하며, 전체 식별자 문자열이 큰따옴표로 묶이지 않는 한 공백이나 특수 문자를 포함할 수 없어요 (예: "My object"). 큰따옴표로 묶인 식별자는 대소문자를 구분해요.

자세한 내용은 식별자 요구 사항(Identifier requirements)을 참고해요.

TYPE = EXTERNAL_OAUTH External OAuth 인티그레이션을 Snowflake OAuth 인티그레이션과 구분해요.

ENABLED = { TRUE | FALSE } 인티그레이션의 운영을 시작할지 일시 중지할지를 지정해요.

• TRUE는 인티그레이션 정의에 지정된 매개변수에 따라 인티그레이션이 실행되도록 해요.
• FALSE는 유지보수를 위해 인티그레이션을 일시 중지해요. Snowflake와 타사 서비스 사이의 어떤 인티그레이션도 작동하지 않아요.

값은 대소문자를 구분하지 않아요. 기본값은 TRUE예요.

EXTERNAL_OAUTH_TYPE = { OKTA | AZURE | PING_FEDERATE | CUSTOM } OAuth 2.0 인가 서버가 Okta, Microsoft Entra ID, Ping Identity PingFederate, 또는 사용자 지정 OAuth 2.0 인가 서버라고 지정해요.

EXTERNAL_OAUTH_ISSUER = 'string_literal' OAuth 2.0 인가 서버를 정의하는 URL을 지정해요.

EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = { 'string_literal' | ('string_literal' [ , 'string_literal' , ... ] ) } 액세스 토큰을 사용자 레코드에 매핑할 액세스 토큰 클레임(claim) 또는 클레임들을 지정해요.

클레임의 데이터 유형은 문자열 또는 문자열 목록이어야 해요.

EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = { 'LOGIN_NAME' | 'EMAIL_ADDRESS' } 액세스 토큰을 사용자 레코드에 매핑하는 데 사용해야 하는 Snowflake 사용자 레코드 속성을 나타내요.

선택 매개변수 (Optional parameters)

EXTERNAL_OAUTH_JWS_KEYS_URL = { 'string_literal' | ('string_literal' [ , 'string_literal' , ... ] ) } External OAuth 액세스 토큰을 검증하기 위해 공개 키나 인증서를 다운로드할 수 있는 HTTPS URL 또는 HTTPS URL 목록을 지정해요.

EXTERNAL_OAUTH_TYPE 매개변수를 AZURE로 설정하면 최대 3개의 URL을 지정할 수 있어요. 예를 들어 두 URL을 지정하려면 다음 구문을 사용해요.

EXTERNAL_OAUTH_JWS_KEYS_URL = ('https://example.ca', 'https://example.co.uk')

EXTERNAL_OAUTH_TYPE 매개변수를 OKTA, PING_FEDERATE, 또는 CUSTOM으로 설정하면 URL 하나만 지정할 수 있어요. 예를 들어:

EXTERNAL_OAUTH_JWS_KEYS_URL = 'https://example.ca'

EXTERNAL_OAUTH_RSA_PUBLIC_KEY = public_key1 -----BEGIN PUBLIC KEY-----와 -----END PUBLIC KEY----- 헤더 없이 Base64로 인코딩된 RSA 공개 키를 지정해요.

Snowflake는 다음 알고리즘으로 생성된 암호화 키를 지원해요.

• RSA 디지털 서명 알고리즘 RS256, RS384, RS512.
• (Python 드라이버 전용) 타원 곡선 디지털 서명 알고리즘(ECDSA) ES256 (P-256), ES384 (P-384), ES512 (P-521).

이 서명들은 각각 SHA-256, SHA-384, SHA-512 해시 알고리즘을 사용해요.

EXTERNAL_OAUTH_RSA_PUBLIC_KEY_2 = public_key2 -----BEGIN PUBLIC KEY-----와 -----END PUBLIC KEY----- 헤더 없이 두 번째 RSA 공개 키를 지정해요. 키 회전(key rotation)에 사용돼요.

EXTERNAL_OAUTH_BLOCKED_ROLES_LIST = ( 'role_name' [ , 'role_name' , ... ] ) 클라이언트가 기본 역할(primary role)로 설정할 수 없는 역할 목록을 지정해요. 이 목록의 역할은 External OAuth 인가 서버의 액세스 토큰을 기반으로 Snowflake 세션을 만들 때 사용할 수 없어요.

기본적으로 이 목록에는 ACCOUNTADMIN, ORGADMIN, GLOBALORGADMIN, SECURITYADMIN 역할이 포함돼요. 이 권한 있는 역할들을 목록에서 제거하려면 ALTER ACCOUNT 명령으로 EXTERNAL_OAUTH_ADD_PRIVILEGED_ROLES_TO_BLOCKED_LIST 계정 매개변수를 FALSE로 설정해요.

EXTERNAL_OAUTH_ALLOWED_ROLES_LIST = ( 'role_name' [ , 'role_name' , ... ] ) 클라이언트가 기본 역할로 설정할 수 있는 역할 목록을 지정해요.

이 목록의 역할은 External OAuth 인가 서버의 액세스 토큰을 기반으로 Snowflake 세션을 만들 때 사용할 수 있어요.

⚠️ 주의: 이 매개변수는 ACCOUNTADMIN, ORGADMIN, GLOBALORGADMIN, SECURITYADMIN 시스템 역할을 지원해요. 이렇게 높은 권한의 역할을 기본 역할로 설정한 Snowflake 세션을 만들 때는 주의를 기울여야 해요.

EXTERNAL_OAUTH_AUDIENCE_LIST = { 'string_literal' | ('string_literal' [ , 'string_literal' , ... ] ) } 고객의 Snowflake 계정 URL(즉 <account_identifier>.snowflakecomputing.com)을 사용하는 것 외에 액세스 토큰의 audience 검증에 대한 추가 값을 지정해요. 자세한 내용은 계정 식별자(Account identifiers)를 참고해요.

Power BI SSO 사용 시 이 매개변수에 대한 자세한 내용은 Power BI SSO 보안 인티그레이션(Power BI SSO security integrations)을 참고해요.

현재 External OAuth Custom Clients에 대해서만 여러 audience URL을 지정할 수 있어요. 각 URL은 작은따옴표로 감싸고 URL마다 쉼표로 구분해야 해요. 예를 들어:

EXTERNAL_OAUTH_AUDIENCE_LIST = ('https://example.com/api/v2/', 'https://example.com')

EXTERNAL_OAUTH_ANY_ROLE_MODE = { DISABLE | ENABLE | ENABLE_FOR_PRIVILEGE } OAuth 클라이언트 또는 사용자가 OAuth 액세스 토큰에 정의되지 않은 역할을 사용할 수 있는지 지정해요. Power BI와 Snowflake 통합에서는 이 매개변수가 활성화되어도 Power BI 사용자가 역할을 전환할 수 없음에 주의해요.

• DISABLE: OAuth 클라이언트 또는 사용자가 역할을 전환할 수 없게 해요 (즉 USE ROLE role;). 기본값.

• ENABLE: OAuth 클라이언트 또는 사용자가 역할을 전환할 수 있게 해요.

• ENABLE_FOR_PRIVILEGE: OAuth 클라이언트 또는 사용자가 USE_ANY_ROLE 권한이 있는 클라이언트 또는 사용자에게만 역할을 전환할 수 있게 해요. 이 권한은 사용자에게 제공되는 하나 이상의 역할에 부여·회수할 수 있어요. 예를 들어:

  GRANT USE_ANY_ROLE ON INTEGRATION external_oauth_1 TO role1;
  

  REVOKE USE_ANY_ROLE ON INTEGRATION external_oauth_1 FROM role1;
  

값은 선택적으로 작은따옴표로 묶을 수 있어요 (즉 DISABLE 또는 'DISABLE').

EXTERNAL_OAUTH_SCOPE_DELIMITER = 'string_literal' 인가 토큰의 범위 구분자를 지정하며, 기본 구분자 ','를 재정의해요. 구분자는 쉼표(',')나 공백(' ') 같은 단일 문자일 수 있어요.

이 속성은 EXTERNAL_OAUTH_TYPE 매개변수를 CUSTOM으로 설정한 경우에만 사용할 수 있어요.

EXTERNAL_OAUTH_SCOPE_MAPPING_ATTRIBUTE = 'string_literal' 액세스 토큰을 계정 역할에 매핑하기 위한 액세스 토큰 클레임을 지정해요.

이 매개변수는 scp 또는 scope로만 설정할 수 있어요.

이 매개변수는 EXTERNAL_OAUTH_TYPE 매개변수를 CUSTOM으로 설정한 경우에만 사용할 수 있어요.

IS_AGENTIC = { TRUE | FALSE } 이 인티그레이션으로 인증된 세션을 에이전트 세션으로 취급해야 하는지 지정해요.

TRUE로 설정하면 Snowflake가 이 인티그레이션으로 인증된 모든 세션을 에이전트 세션으로 자동 인식해, 해당 세션에서 IS_AGENT_ACTIVATED가 TRUE를 반환하게 해요.

• 기본값: FALSE

NETWORK_POLICY = 'network_policy' 기존 네트워크 정책을 지정해요. 이 네트워크 정책은 클라이언트에서 Snowflake로의 네트워크 트래픽을 제어해요.

자세한 내용은 External OAuth의 네트워크 트래픽 제한(Restricting network traffic for External OAuth)을 참고해요.

COMMENT = 'string_literal' 인티그레이션에 대한 설명(comment)을 지정해요.

• 기본값: 값 없음

접근 제어 요구 사항 (Access control requirements)

이 작업을 실행하는 데 사용하는 역할(role)은 최소한 다음 권한을 가져야 해요.

권한 (Privilege)	객체 (Object)	비고
CREATE INTEGRATION	Account	기본적으로 ACCOUNTADMIN 역할만 이 권한을 가져요. 필요에 따라 추가 역할에 부여될 수 있어요.

지정된 권한 집합으로 사용자 지정 역할을 만드는 방법은 사용자 지정 역할 만들기(Creating custom roles)를 참고해요. 보호 가능한 객체에 대해 SQL 작업을 수행하기 위한 역할과 권한 부여의 일반적인 내용은 접근 제어 개요(Overview of Access Control)를 참고해요.

사용 메모 (Usage notes)

메타데이터에 관해서는 다음 사항에 주의해요.

⚠️ 주의: 고객은 Snowflake 서비스를 사용할 때 (User 객체를 제외하고) 개인 데이터·민감 데이터·수출 통제 데이터·기타 규제 데이터를 메타데이터로 입력하지 않도록 해야 해요. 자세한 내용은 Snowflake의 메타데이터 필드를 참고해요.

OR REPLACE와 IF NOT EXISTS 절은 서로 배타적이에요. 같은 문에서 둘 다 사용할 수 없어요.

CREATE OR REPLACE <object> 문은 원자적(atomic)으로 동작해요. 즉, 객체를 교체할 때 기존 객체는 삭제되고 새 객체는 단일 트랜잭션 안에서 생성돼요.

External OAuth 보안 인티그레이션은 OAUTH_AUTHORIZATION_SERVER 매개변수를 사용해 Snowflake 관리 MCP 서버에 바인딩할 수 있어요. 인티그레이션이 스키마·데이터베이스·계정에 바인딩되면 Snowflake가 인티그레이션의 발급자(issuer) URL을 Protected Resource Metadata(RFC 9728)에 알려요. 그러면 MCP 클라이언트가 조직의 ID 공급자를 자동으로 검색하고 사용할 수 있어요. OAUTH_SCOPES_SUPPORTED 매개변수를 사용해 광고할 OAuth 범위를 제어해요. 자세한 내용은 MCP 서버용 External OAuth 인증 구성을 참고해요.

예시 (Examples)

Microsoft Entra ID 예시

다음 예시는 Microsoft Entra ID OAuth 2.0 인가 서버용 External OAuth 보안 인티그레이션을 만들어요.

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

DESCRIBE INTEGRATION으로 인티그레이션 설정을 봐요.

DESC SECURITY INTEGRATION external_oauth_azure_1;

Okta 예시

다음 예시는 Okta OAuth 2.0 인가 서버용 External OAuth 보안 인티그레이션을 만들어요.

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

DESCRIBE INTEGRATION으로 인티그레이션 설정을 봐요.

DESC SECURITY INTEGRATION external_oauth_okta_1;

Microsoft Power BI SSO 예시

예시는 다음을 참고해요.

• Power BI 보안 인티그레이션 만들기
• B2B 게스트 사용자와 Power BI SSO 사용

더 알아보기 (Learn more)

• CREATE SECURITY INTEGRATION — 보안 인티그레이션 생성
• ALTER SECURITY INTEGRATION (External OAuth) — 인티그레이션 수정