Snowflake OAuth 개요

Snowflake OAuth는 Snowflake 내장 OAuth 서비스를 사용해 OAuth 기반 인증을 제공해요.

이 주제는 Snowflake OAuth와 Snowflake를 OAuth 리소스이자 인가 서버로 사용해 Snowflake 데이터에 안전하게 접근하는 방법을 설명해요.

Snowflake OAuth는 Snowflake 내장 OAuth 서비스를 사용하며 다음 애플리케이션을 지원해요:

출처: Snowflake OAuth overview

본문

Snowflake OAuth 인가 흐름

OAuth 인가 흐름은 다음과 같아요:

클라이언트에서 사용자가 OAuth로 Snowflake에 연결을 시도해요. 애플리케이션은 Snowflake 인가 서버에 인가 요청을 보내고, 인가 서버는 사용자에게 접근을 승인할지 묻는 인가 화면을 표시해요.
사용자가 Snowflake 로그인 이름과 비밀번호를 제출하면, 클라이언트가 사용자 세션에서 특정 역할(예: SYSADMIN 또는 CUSTOM_ROLE1)로 Snowflake에 접근하도록 허용할지 묻는 동의 화면이 표시돼요. 사용자는 세션에서 특정 역할을 사용하는 데 동의를 제출해요. Snowflake 인가 서버는 인가 코드를 클라이언트로 다시 보내요.
클라이언트는 인가 코드를 Snowflake 인가 서버로 다시 보내 액세스 토큰과, 선택적으로 나중에 새 액세스 토큰을 얻을 수 있게 하는 리프레시 토큰을 요청해요. Snowflake 인가 서버는 인가 코드를 수락하고 Snowflake 리소스 서버의 사용자 리소스에 특정한 액세스 토큰을 클라이언트에 제공해요. 인가 요청의 설정에 따라 인가 서버는 특정 리소스에 연결된 새 액세스 토큰을 얻기 위한 리프레시 토큰을 발급해요.
클라이언트는 액세스 토큰을 Snowflake 리소스 서버로 보내요. 리소스 서버는 유효한 액세스 토큰을 인식하고 인가된 역할로 사용자 세션을 만들어요. 이제 클라이언트는 액세스 토큰이 지정한 역할로 제한된 Snowflake 리소스에 접근할 수 있어요.

기본적으로 Snowflake는 ACCOUNTADMIN, ORGADMIN, GLOBALORGADMIN, SECURITYADMIN 역할의 인증을 차단해요. 이러한 고권한 역할이 인증하도록 허용하려면 ALTER ACCOUNT 명령으로 OAUTH_ADD_PRIVILEGED_ROLES_TO_BLOCKED_LIST 계정 매개변수를 FALSE로 설정하세요.

액세스 토큰은 수명이 짧아요: 일반적으로 10분. 액세스 토큰이 만료되면 클라이언트는 리프레시 토큰을 보내 새 액세스 토큰을 얻을 수 있어요. 현재 액세스 토큰이 만료될 때마다 리프레시 토큰이 Snowflake 인가 서버로 보내져 새 액세스 토큰을 요청해요(3-6단계). 통합이 리프레시 토큰 전송을 막도록 구성되면 사용자는 위의 단계를 반복해 클라이언트를 다시 인가해야 해요. Snowflake OAuth 흐름에서 수명이 긴 토큰이 주는 위험을 제한하려면 일회용 리프레시 토큰을 사용할 수 있어요.

일회용 리프레시 토큰

일회용 리프레시 토큰을 사용해 리프레시 토큰의 도난이나 재사용을 완화할 수 있어요. 자세한 내용은 Snowflake OAuth 보안 통합용 일회용 리프레시 토큰을 참조하세요.

로컬 애플리케이션

Snowflake는 로컬 애플리케이션(즉, 데스크톱 애플리케이션)이 Snowflake OAuth로 인증하도록 설정하는 간단한 방법을 제공해요. 애플리케이션은 단일 연결 옵션을 설정해 인증할 수 있으며 추가 설정이 필요 없어요. 자세한 내용은 로컬 애플리케이션용 Snowflake OAuth 사용을 참조하세요.

파트너 애플리케이션

지원을 구성하려면 파트너 애플리케이션용 Snowflake OAuth 구성을 참조하세요.

공개 인터넷을 거치지 않고 OAuth를 사용하는 방법은 PrivateLink 및 SaaS 클라이언트와 함께 Snowflake OAuth 사용을 참조하세요.

커스텀 클라이언트

Snowflake는 조직에서 구성한 커스텀 클라이언트를 지원해요. 지원을 구성하려면 커스텀 클라이언트용 Snowflake OAuth 구성을 참조하세요.

Snowflake OAuth 네트워크 트래픽 제한

네트워크 정책을 Snowflake OAuth 보안 통합과 연결해, 클라이언트가 인가 서버인 Snowflake에 토큰을 요청할 때 네트워크 트래픽을 제한할 수 있어요. 이 네트워크 정책은 클라이언트가 리소스 서버인 Snowflake를 쿼리할 때의 네트워크 트래픽도 관리해요.

Snowflake OAuth 보안 통합과 네트워크 정책을 연결하려면 통합을 만들거나 업데이트할 때 NETWORK_POLICY 매개변수를 설정하세요. 예를 들어:

CREATE SECURITY INTEGRATION td_oauth_int2
  TYPE = oauth
  ENABLED = true
  OAUTH_CLIENT = tableau_desktop
  OAUTH_REFRESH_TOKEN_VALIDITY = 36000
  BLOCKED_ROLES_LIST = ('SYSADMIN')
  NETWORK_POLICY = 'allow_private_ip_only';

Snowflake OAuth 보안 통합과 연결된 네트워크 정책은 사용자와 인가 서버인 Snowflake 사이의 네트워크 트래픽에는 영향을 주지 않아요. 사용자가 브라우저로 인증할 때 네트워크 트래픽은 사용자와 연결된 네트워크 정책에 의해 제한돼요.

다음 다이어그램은 어떤 네트워크 정책이 클라이언트와 사용자의 네트워크 트래픽을 관리하는지 보여줘요.

사용자와 연결된 네트워크 정책이 관리해요. 사용자 수준 네트워크 정책이 없으면 계정 수준 정책이 관리해요.
보안 통합과 연결된 네트워크 정책이 관리해요. 통합 수준 네트워크 정책이 없으면 계정 수준 정책이 관리해요.

로컬 애플리케이션용 네트워크 정책

내장 SNOWFLAKE$LOCAL_APPLICATION 통합의 경우, 로컬 애플리케이션이 별도의 인가 서버가 없어 사용자의 네트워크 환경에서 실행되므로 토큰 요청에 사용자 수준 네트워크 정책도 고려돼요. 이러한 요청의 우선순위는 사용자, 그다음 통합, 그다음 계정 순서예요.

로컬 애플리케이션에 대한 자세한 내용은 로컬 애플리케이션용 Snowflake OAuth 사용을 참조하세요.

PrivateLink 및 SaaS 클라이언트와 함께 Snowflake OAuth 사용

Claude.ai나 ChatGPT 커넥터 같은 SaaS 호스팅 클라이언트에서 Snowflake OAuth를 사용할 때 인가 코드 흐름은 두 개의 서로 다른 네트워크 컨텍스트에 걸쳐 실행돼요:

인가 요청은 사용자의 브라우저에서 만들어져요. 브라우저는 사용자의 네트워크에서 실행되며 PrivateLink 계정 URL에 도달해 인가 단계를 완료할 수 있어요.
토큰 요청은 SaaS 공급업체의 백엔드에서 Snowflake로 직접 이루어지는 서버 간 호출이에요. 그 서버가 공개 인터넷에 있으므로 PrivateLink 호스트 이름을 해석할 수 없어요. 따라서 토큰 엔드포인트는 공개 Snowflake URL이어야 해요.

SaaS MCP 클라이언트를 구성할 때는 PrivateLink URL이 아닌 공개 Snowflake 계정 URL을 사용하세요. 인가 단계에서 Snowflake가 사용자의 브라우저를 PrivateLink 인가 엔드포인트로 리다이렉트하길 원한다면 OAuth 보안 통합에서 USE_PRIVATELINK_FOR_AUTHORIZATION_ENDPOINT = TRUE를 활성화하세요.

이 제약은 SaaS 클라이언트에만 적용돼요. Claude Desktop이나 Cursor처럼 사용자의 머신에서 실행되는 클라이언트는 사용자의 네트워크에서 연결하므로 PrivateLink URL을 직접 사용할 수 있어요.

USE_PRIVATELINK_FOR_AUTHORIZATION_ENDPOINT 설정에 대한 정보는 CREATE SECURITY INTEGRATION (Snowflake OAuth)과 ALTER SECURITY INTEGRATION (Snowflake OAuth)을 참조하세요.

오류 코드

Snowflake OAuth와 관련된 오류 코드 설명은 아래 표를 참조하세요:

오류 코드	오류	설명
390302	OAUTH_CONSENT_INVALID	주어진 사용자에 대한 동의를 생성하거나 검증하는 데 문제 발생.
390303	OAUTH_ACCESS_TOKEN_INVALID	Snowflake 세션을 만들려 할 때 제공된 액세스 토큰이 만료되었거나 잘못됨.
390304	OAUTH_AUTHORIZE_INVALID_RESPONSE_TYPE	인가 엔드포인트의 매개변수로 잘못된 `response_type`이 제공됨(대부분 `code`여야 함).
390305	OAUTH_AUTHORIZE_INVALID_STATE_LENGTH	인가 엔드포인트의 매개변수로 제공된 state 매개변수가 2048자를 초과함.
390306	OAUTH_AUTHORIZE_INVALID_CLIENT_ID	제공된 `client_id`와 연결된 통합이 존재하지 않음.
390307	OAUTH_AUTHORIZE_INVALID_REDIRECT_URI	인가 엔드포인트의 매개변수로 주어진 `redirect_uri`가 제공된 `client_id`와 연결된 통합의 `redirect_uri`와 일치하지 않거나 `redirect_uri`가 올바르게 형식화되지 않음.
390308	OAUTH_AUTHORIZE_INVALID_SCOPE	요청된 스코프가 유효한 스코프가 아니거나, 요청된 스코프를 사용자에게 완전히 부여할 수 없음.
390309	OAUTH_USERNAMES_MISMATCH	인증하려던 사용자가 액세스 토큰에 연결된 사용자와 다름.
390311	OAUTH_AUTHORIZE_INVALID_CODE_CHALLENGE_PARAMS	코드 챌린지 또는 코드 챌린지 메서드가 없거나, 잘못되었거나, 지원되지 않음.

추가로 다음 오류는 RFC에서 가져온 것이며 실패한 토큰 요청 또는 교환 중에 생성된 JSON blob에서 반환돼요:

오류	설명
invalid_client	클라이언트 인증 관련 실패가 있었음. 예: 클라이언트를 알 수 없거나, 클라이언트 secret 불일치, 잘못된 `client_secret_basic` 인코딩. 클라이언트의 IP 주소를 차단하는 네트워크 정책도 이 오류를 반환할 수 있음. 지원되는 방법과 인코딩은 클라이언트 인증을 참조.
invalid_grant	제공된 인가 그랜트 또는 리프레시 토큰이 유효하지 않거나, 만료되었거나, 철회되었거나, 인가 요청에 사용된 리다이렉션 URI와 일치하지 않거나, 다른 클라이언트에 발급됨.
unsupported_grant_type	Snowflake가 현재 지원하지 않는 그랜트 유형이 제공됨(현재 지원되는 그랜트 유형은 "refresh_token"과 "authorization_code"뿐임).
invalid_request	요청이 잘못 구성되었거나 처리할 수 없음.

Snowflake OAuth 개요