Snowflake Agent Identity 완벽 해설

서론

안녕하세요! Nowcast의 데이터 엔지니어 켑빈(Kebin)입니다.

Claude Code와 같은 코딩 에이전트로부터 Snowflake를 다룰 기회가 늘어나고 있습니다. 편리한 반면, 연결 시 인간 사용자의 키페어나 PAT를 그대로 에이전트에 전달하는 경우가 있을지 모릅니다.

이 방법으로는 Snowflake 입장에서 에이전트의 작업과 인간의 작업을 구분할 수 없으며, 에이전트를 위한 제어도 불가능합니다. 여기서 유용하게 쓰이는 것이 Snowflake의 Agent Identity입니다.

본 기사에서는 Agent Identity의 기능을 Identify / Audit / Govern / Control 네 가지 관점으로 정리한 후, 에이전트에게 어떤 주체와 어떤 인증 방식으로 Snowflake에 연결해야 하는지를 비교합니다.

에이전트 인증 정보의 과제

Nowcast에서는 엔지니어가 개발할 때 코딩 에이전트를 로컬 PC에서 직접 실행하기보다는 주로 DevContainer 내에서 실행합니다. 에이전트 측 권한 설정으로 어느 정도는 방어할 수 있지만, 로컬 PC 상에서는 인간용 인증 정보가 읽혀져 연결에 사용될 위험이 남아있기 때문입니다. 따라서 DevContainer에 마운트하는 Snowflake나 AWS 등의 인증 정보도 제한하고, 필요 최소한의 권한만 전달하도록 하고 있습니다.

하지만 실행 환경을 분리하더라도, 에이전트에게 전달되는 Snowflake 인증 정보가 인간의 것이라면, Snowflake 입장에서 볼 때는 인간이 작업하는 것과 다를 바 없습니다. 인간 사용자의 권한을 그대로 에이전트에 사용하게 하면 다음과 같은 문제가 발생합니다.

• 에이전트로 식별할 수 없음 - 누가 했는지(인간인지 에이전트인지) Snowflake 측에서 구분할 수 없음

• 나중에 '어떤 에이전트가, 누구를 대리하여, 어떤 데이터에 접근했는지' 설명할 수 없음

• 에이전트에 대한 통제/제어가 불가능함

• 권한이 너무 큼 - 인간 사용자 모든 역할(Role) 및 권한을 에이전트가 사용할 수 있게 되어 기존의 과도하게 넓은 권한까지 그대로 승계됨 (과잉 공유 문제)

• 에이전트는 비결정적이며 프롬프트 인젝션 등으로 외부에서 조작될 수 있으므로, 오작동이나 탈취의 영향이 사용자 권한 전체로 확산될 수 있음

• 인증 정보가 장기적임 - 키페어나 유효 기간이 긴 PAT는 장기적인 인증 정보임

• 에이전트 실행 환경(환경 변수, 설정 파일 등)에 놓이게 되면서 누출 경로가 인간 이용 시보다 증가함

• 에이전트만 멈출 수 없음 - 에이전트가 예상치 못한 움직임을 보여도, 인증 정보를 무효화하면 인간의 작업도 멈춤

즉, 에이전트에 전달하는 인증 정보는 '에이전트로 식별 가능해야 함', '역할이 제한되어야 함', '단기적이어야 함', '인간과 분리되어야 함' 네 가지 요건을 충족하는 것이 요구됩니다. 이 문제의식은 Snowflake의 Engineering Blog에서도 자세히 다루어지고 있습니다.

Snowflake Agent Identity의 전체 개요

개요

이전 장에서 언급된 과제를 해결하기 위한 메커니즘이 바로 Snowflake의 Agent Identity입니다. Agent Identity는 특정 하나의 기능을 지칭하는 것이 아니라, '이 세션은 에이전트에 의한 것인가'라는 정보를 축으로 에이전트의 식별(Identify) · 감사(Audit) · 데이터 보호(Govern) · 제어(Control)를 종합적으로 다루기 위한 기능군입니다.

기반이 되는 것은 식별(Identify)입니다. Snowflake가 세션을 에이전트에 의한 것으로 판정할 수 있어야만, 감사(Audit) · 데이터 보호(Govern) · 제어(Control)가 작동합니다.

네 가지 기능을 정리하면 다음과 같습니다.

Agent Identity의 공식 문서는 각 기능 간의 관계나 설정 방법을 잘 정리되어 있으므로, 먼저 이곳을 한 번 쭉 읽어보는 것이 좋습니다.

위임형과 자율형

Agent Identity에서는 에이전트의 움직임으로 다음 두 가지가 예상됩니다.

• 위임형 (Delegated): 사용자의 대리인으로서, 해당 사용자의 세션에서 작동합니다. 에이전트용 경로로 연결한 경우, Snowflake는 세션을 agent-active (IS_AGENT_ACTIVATED = TRUE) 상태로 표시합니다. -
• 자율형 (Autonomous): 전용의 SERVICE_AGENT 사용자로 작동합니다. 해당 사용자의 세션은 항상 agent-active가 됩니다.

어느 쪽이 될지는 에이전트 유형이 아니라, 어떤 사용자로서 연결시키는지에 따라 결정됩니다. 예를 들어 Claude Code에서도, PERSON 사용자의 대리인으로 연결하면 위임형이고, SERVICE_AGENT 사용자로 연결하면 자율형입니다.

SERVICE_AGENT는 기존의 PERSON이나 SERVICE에 추가된 새로운 사용자 유형입니다. SERVICE와 마찬가지로 비밀번호나 SAML SSO를 통한 로그인 및 MFA 등록은 할 수 없으며, WIF(Workload Identity Federation)・키 쌍・PAT(Personal Access Token)으로 인증합니다.

식별 / Identify

Agent Identity의 출발점은 세션이 에이전트에 의한 것인지 아닌지를 Snowflake가 식별할 수 있다는 것입니다. 세션이 에이전트에 의한 것으로 판정된 경우, SYS_CONTEXT의 SNOWFLAKE$CURRENT 네임스페이스에 있는 IS_AGENT_ACTIVATED가 TRUE를 반환합니다.

SELECT
SYS_CONTEXT('SNOWFLAKE$CURRENT', 'IS_AGENT_ACTIVATED') AS is_agent,
SYS_CONTEXT('SNOWFLAKE$CURRENT', 'AGENT_TYPE') AS agent_type;
...

IS_AGENT_ACTIVATED = TRUE가 되는 경우는 다음 케이스입니다.

표에서 볼 수 있듯이 agent-active 여부는 어떤 경로・어떤 사용자로 연결했는지에 따라 결정되며, 클라이언트 측 설정으로 전환할 수는 없습니다.

감사 / Audit

에이전트 세션을 식별할 수 있게 되면, 그 정보는 감사용 뷰에 반영됩니다. 대표적인 예시는 다음 두 가지입니다.

• QUERY_HISTORY의 agent_type 열 - 직접 쿼리를 실행한 에이전트의 종류가 기록됩니다.
• 값은 CORTEX_AGENT/CORTEX_LITE_AGENT/EXTERNAL_AGENT

어떤 것 중 하나 - Claude Code와 같은 외부 에이전트는 EXTERNAL_AGENT가 됩니다.

• ACCESS_HISTORY의 agents_info 열: 객체 접근에 관여한 에이전트 정보가 직접 접근한 에이전트부터 최상위 에이전트 순서로 저장됩니다.
• 예를 들어, Cortex Agent가 툴을 호출하여 쿼리를 실행한 경우, 배열에는 해당 Cortex Agent가 가장 먼저 포함되고, 호출하는 쪽(호출원)에 상위 에이전트가 있다면 그 뒤에 이어집니다.

이들을 조합하면 '어떤 사용자가 어떤 에이전트를 호출했고, 어떤 쿼리를 실행했으며, 어떤 객체에 접근했는지'라는 일련의 흐름을 추적할 수 있습니다.

데이터 보호 / Govern

IS_AGENT_ACTIVATED를 사용하면 에이전트 경유 세션인지 여부에 따라 데이터 보호 정책의 동작을 변경할 수 있습니다.

다음은 마스킹(Masking) 정책의 예시입니다. 사용자 역할에서는 접근이 허용되더라도, 위임형 에이전트를 통해 이루어진 세션에는 민감 데이터를 반환하지 않도록 합니다.

CREATE OR REPLACE MASKING POLICY email_agent_mask AS (val STRING) RETURNS STRING ->
CASE
WHEN SYS_CONTEXT('SNOWFLAKE$CURRENT', 'IS_AGENT_ACTIVATED')::BOOLEAN = TRUE THEN '********'
...

마스킹 정책 외에도 행 접근 정책(Row Access Policy)이나 집계 정책(Aggregation Policy) 등에서 유사한 분기가 가능합니다. 응용 사례는 다음 기사에서 자세히 다루고 있습니다.

또한, 정책이 의도대로 작동하는지 확인하려면 POLICY_CONTEXT가 유용합니다. 실제로 에이전트를 실행하지 않아도 에이전트 세션을 가상으로 재현하여 쿼리를 실행할 수 있습니다.

EXECUTE USING POLICY_CONTEXT(
SNOWFLAKE$CURRENT_ACTIVATED_AGENT_TYPES => ('EXTERNAL_AGENT')
) AS
...

실행 결과 IS_AGENT_ACTIVATED가 TRUE이고, AGENT_TYPE이 EXTERNAL_AGENT를 반환하는 것을 보고 에이전트 세션을 재현할 수 있음을 확인했습니다.

제어 / Control

Restricted Session Scope (RSS)

세션을 에이전트에 의한 것으로 식별할 수 있다면, 해당 에이전트가 실행할 수 있는 작업을 사용자 역할에 허용된 권한의 일부로 제한할 수 있습니다. 이것이 **Restricted Session Scope (RSS)**입니다.

RSS는 권한의 상한선을 정하는 메커니즘입니다. 실제로 사용할 수 있는 권한은 사용자 권한과의 공통 부분으로 한정되며, 사용자가 가지고 있지 않은 권한이 RSS에 의해 부여되는 일은 없습니다.

RSS를 사용하려면 세션 정책(Session Policy)에 AGENT_RESTRICTED_SESSION_SCOPE를 설정하고, 이 정책을 계정 또는 사용자에게 적용해야 합니다. 이 상한선은 세션이 agent-active(IS_AGENT_ACTIVATED가 TRUE)일 때만 효력이 발생하므로, 같은 사용자라도 사람이 작업하는 동안에는 영향을 받지 않습니다.

대표적인 사용 사례는 다음과 같습니다:

• 계정 전체를 읽기 전용으로 설정 (AI 관련 객체 이용은 허용)
• 운영 환경(Production)은 읽기 전용, Sandbox와 개인 DB만 쓰기 가능하게 설정
• ACCOUNTADMIN / SYSADMIN / SECURITYADMIN과 같은 특권 역할 차단
• 데이터 조작은 허용하되, 권한 부여 및 객체 관리는 차단
• AI 이용이 승인된 DB로 접근을 제한

Predefined RSS

Snowflake는 미리 정의된 RSS로서 SNOWFLAKE$DATA_READ / SNOWFLAKE$DATA_READ_WITH_AI / SNOWFLAKE$DATA_READ_PROGRAM_USAGE의 3가지를 제공합니다. 세션 정책에 설정하는 것만으로 이용할 수 있으며, 각각의 정의는 RSS 문서의 말미에 기재되어 있습니다.

CREATE SESSION POLICY mydb.governance.agent_policy
AGENT_RESTRICTED_SESSION_SCOPE = 'SNOWFLAKE$DATA_READ';

RSS 설정 예시 및 주의사항

설정 예시

여기서는 특권 역할(privileged role)의 사용을 금지하고, 데이터 읽기(data read)만 허용하는 RSS를 계정 수준에서 강제하는 예를 소개합니다.

USE ROLE ACCOUNTADMIN;
-- Step 1: RSS 객체 생성
CREATE RESTRICTED SESSION SCOPE governance_db.policies.agent_rss AS $$
...

이 상태에서 CoCo가 USE ROLE SYSADMIN을 실행하게 하면, 다음과 같은 오류가 발생합니다.

Role 'SYSADMIN' is not permitted by the restricted session scope active on this session (allowed roles: []; blocked roles: [ACCOUNTADMIN, SYSADMIN, SECURITYADMIN, USERADMIN]). Choose a role in the allowed set and not in the blocked set, or if you applied it, recreate a session with a new scope, or contact an account administrator if this was applied as part of admin managed policy.

blocked_roles에 관한 주의사항

blocked_roles를 사용할 때 주의할 점은 역할 계층(role hierarchy)이 아니라 역할 이름 그 자체로 판별된다는 것입니다.

• blocked role은 primary role로도 secondary role로도 활성화될 수 없습니다.
• 다만, blocked role이 부여된 다른 역할을 primary로 사용한 경우, 해당 역할이 상속받는 권한(blocked role에서 유래한 것을 포함)은 박탈되지 않습니다.

예를 들어 SYSADMIN을 차단하더라도, SYSADMIN을 부여한 커스텀 역할인 DATA_ADMIN으로 세션을 열면, DATA_ADMIN을 통해 SYSADMIN의 권한이 작동합니다.

따라서 blocked_roles는 '특권 역할을 직접 사용하지 못하게 한다'는 개념으로 이해하고, 권한의 상한선은 privilege_scopes (allowed_privileges)로 결정하는 것이 좋습니다. 위의 예시에서는 privilege_scopes로 data read에 한정했기 때문에, 가령 상속을 통해 특권 역할에서 유래한 권한이 부여되더라도 실제로 사용할 수 있는 것은 data read 범위 내에 머무릅니다.

인증 방식 선택지 비교

지금까지 살펴본 기능 중 Audit / Govern / Control은 방침이 결정되면 그것을 정책(policy)이나 RSS로 구현하기만 하면 됩니다. 반면 Identify는 에이전트를 어떤 주체로서, 어떤 인증 방식으로 연결할 것인지의 선택지가 많아, 무엇을 채택해야 할지 명확하지 않습니다.

에이전트를 인증하는 주체에는 인간 사용자(PERSON), 개인별 SERVICE_AGENT 사용자, 유스케이스별 SERVICE_AGENT 사용자의 3가지가 있으며, 각각 사용할 수 있는 인증 방식이 몇 가지 있습니다. 이 조합들을 앞서 언급한 네 가지 요구사항에 '감사로 누구의 대리인인지 추적할 수 있는지'를 추가하여 다섯 가지로 비교하면 다음과 같습니다.

참고로 External OAuth (IS_AGENTIC = TRUE)도 선택지가 될 수 있지만, Nowcast에서는 External OAuth를 사용하지 않으므로 이번에는 대상에서 제외합니다.

범례: ○ 충족 / △ 조건부 충족 / × 미충족

PERSON의 키 쌍 / PAT-
Named Key Pair와 PAT은 발급 시 ROLE_RESTRICTION으로 역할을, DAYS_TO_EXPIRY로 유효 기간을 지정할 수 있습니다 (ALTER USER … ADD KEY PAIR / ALTER USER … ADD PROGRAMMATIC ACCESS TOKEN) - 다만 유효 기간이 일 단위가 최소이므로 단기적은 △입니다.

• 에이전트 전용으로 발급해 두면, 해당 키나 토큰만 무효화함으로써 사람의 작업을 멈추지 않고 에이전트만 중단할 수 있습니다.

• PAT은 인증 정책 (PAT_POLICY)으로 유효 기간 상한을 강제할 수 있습니다. 반면, Named Key Pair의 DAYS_TO_EXPIRY는 임의 지정이며, 생략하면 무기한이 됩니다. 2026년 9월 말 시점에서는 인증 정책으로 유효 기간을 강제하는 수단이 없습니다 - 모두 사용자는 PERSON이므로 agent-active가 되지 않으며, 식별할 수 없습니다.

Named Key Pair와 PAT은 발급 시-
SSO (externalbrowser)-
세션은 사람 본인의 것과 구별할 수 없으며, 역할 전환이나 secondary roles도 그대로 사용할 수 있습니다.

• Snowflake OAuth (IS_AGENTIC = TRUE)-
  integration의 ALLOWED_ROLES_LIST와 OAuth에서 요청하는 session:role:<role> 스코프에 따라 사용할 역할을 제한할 수 있습니다 - access token의 유효 기간은 짧고, refresh token의 유효 기간도 integration 측에서 설정할 수 있어 단기적인 인증 정보로 만들 수 있습니다.

• integration을 무효화하면 에이전트만 중단할 수 있습니다.

• integration의-
  managed MCP server 경유-
  세션은 자동으로 agent-active가 됩니다.

• 역할은 OAuth에서 요청하는 scope에 의해 결정되며, 서버 측에서는 OAUTH_SCOPES_SUPPORTED로 제시하는 scope를 제어할 수 있습니다. 다만, Claude처럼 역할 지정에 대응하지 않는 클라이언트는 session:role:all을 요청하므로 사용자의 DEFAULT_ROLE이 사용됩니다 (Snowflake-managed MCP server) - MCP 서버에서 공개한 툴(Cortex Agent, SQL 실행, UDF 등)만 사용할 수 있으므로, Snowflake CLI나 dbt를 사용하는 개발 용도에는 적합하지 않습니다.

• 개인별 SERVICE_AGENT-
  식별과 분리는 충족하지만, 감사상 별 사용자이기 때문에

• 사용 사례별 SERVICE_AGENT - 사용자 수는 줄일 수 있지만, 사용 사례를 어느 수준으로 분리할지 검토해야 합니다.

• 또한 여러 사람이 같은 사용자를 사용하게 되므로 '누구의 대리인지'가 사라져 개인 코딩 에이전트 인증이라는 맥락에는 적합하지 않습니다.

PERSON + Snowflake OAuth 설정 예시 및 주의사항

지금까지의 비교를 종합해 볼 때, 개인 코딩 에이전트를 Snowflake에 연결하는 방법으로는 **PERSON 사용자 + Snowflake OAuth (IS_AGENTIC = TRUE)**가 가장 좋은 선택지라고 생각합니다. 네 가지 요구 사항을 모두 충족하며, 감사(audit) 시 '누구의 대리인지'를 추적할 수 있는 유일한 선택지이기 때문입니다.

구체적인 예시로, DevContainer 내의 Snowflake CLI가 IS_AGENTIC = TRUE OAuth 통합(integration)을 통해 토큰을 획득하여 연결하는 구성을 소개합니다. 세션이 agent-active 상태가 되므로, 계정 수준의 세션 정책에 설정된 RSS가 그대로 적용됩니다.

Security Integration 생성하기

먼저 에이전트용 Security Integration을 생성합니다.

CREATE OR REPLACE SECURITY INTEGRATION claude_code_agent
TYPE = OAUTH
ENABLED = TRUE
...

설계상의 핵심 포인트는 다음과 같습니다:

• client_secret은 DevContainer 내에 위치하며 에이전트가 읽을 수 있으므로, 비밀 정보로 취급할 수 없습니다. 따라서 OAUTH_CLIENT_TYPE = 'PUBLIC'으로 설정하고, OAUTH_ENFORCE_PKCE = TRUE로 PKCE를 필수화합니다.
• 통합(integration)은 역할(role)별로 분리하지 않고, 필요한 역할이 늘어나면 ALLOWED_ROLES_LIST에 추가합니다. 아울러 BLOCKED_ROLES_LIST로 특권 역할을 명시적으로 거부하고, OAUTH_USE_SECONDARY_ROLES = NONE으로 secondary roles를 통한 권한 사용도 불가능하게 합니다.
• refresh token의 유효 기간은 8시간 정도로 설정합니다 (AWS의 일일 로그인과 유사한 운영 방식). 더 나아가 OAUTH_SINGLE_USE_REFRESH_TOKENS_REQUIRED = TRUE로 refresh token을 일회용으로 만들어 유출되어도 재사용하기 어렵게 합니다.
• NETWORK_POLICY를 사용하여 토큰 사용이 가능한 연결원을 통합(integration) 단위로 제한합니다. - 샌드박스와 프로덕션처럼, refresh token의 기한이나 네트워크 정책을 다르게 하고 싶을 때만 통합(integration)을 분리합니다.

connections.toml 설정하기

Snowflake CLI 측에서는 connections.toml에 OAuth 연결 설정을 추가합니다.

[agent]
account = "<org>-<account>"
user = "<your_user_name>"
...

OAUTH_SINGLE_USE_REFRESH_TOKENS_REQUIRED = TRUE 통합에 연결하므로, 클라이언트 측에서도 oauth_enable_single_use_refresh_tokens = true를 지정합니다.

DevContainer에서 인증하기

VS Code의 DevContainer에서는 컨테이너 내에서 snow를 실행하면 동의 화면이 호스트 측 브라우저에 열리고, 동의 후에는 http://localhost:8001/snowflake/oauth-redirect로 리다이렉트됩니다. 이 리다이렉트를 컨테이너 내부의 Snowflake CLI가 받을 수 있도록, devcontainer.json에서 포트를 포워딩(forward)합니다.

"forwardPorts": [8001],
"portsAttributes": {
"8001": {
...

자동 포워딩에 맡길 경우, 호스트 측 8001번이 사용 중일 때 다른 포트로 이동(shift)되어 리다이렉트가 도착하지 않을 수 있습니다. requireLocalPort: true를 사용합니다.

이렇게 하면 포트가 어긋나지 않고 에러가 발생하기 때문에 바로 알아챌 수 있습니다.

또한, connections.toml은 호스트의 ~/.snowflake를 마운트하지 않고 컨테이너 전용으로 두도록 합니다. 이는 사람 사용자의 연결 설정이 에이전트에게 보이지 않게 하기 위함입니다.

최초 인증은 Claude Code가 아닌 사람이 컨테이너 내부 터미널에서 실행합니다.

snow connection test -c agent

한 번 인증하면 토큰이 캐시되므로, 이후부터는 Claude Code를 통해 브라우저를 열지 않고 snow를 실행할 수 있습니다.

동작 확인

먼저 세션이 agent-active 상태인지 확인합니다.

snow sql -c agent -q 'SELECT SYS_CONTEXT($$SNOWFLAKE$CURRENT$$, $$IS_AGENT_ACTIVATED$$) AS is_agent, SYS_CONTEXT($$SNOWFLAKE$CURRENT$$, $$AGENT_TYPE$$) AS agent_type, CURRENT_SECONDARY_ROLES() AS secondary_roles' 

+-----------------------------------------------------+ 
| IS_AGENT | AGENT_TYPE | SECONDARY_ROLES | 
|----------+----------------+-------------------------|
...

PERSON 사용자로 남아있으면서 IS_AGENT_ACTIVATED가 TRUE가 되고, OAUTH_USE_SECONDARY_ROLES = NONE으로 인해 secondary roles도 비활성화된 것을 알 수 있습니다.

또한, 이 연결로 실행한 쿼리는 QUERY_HISTORY에서도 agent_type이 EXTERNAL_AGENT로 기록됩니다.

SELECT query_text, user_name, role_name, agent_type 
FROM TABLE(snowflake.information_schema.query_history(result_limit => 10)) 
ORDER BY start_time DESC;