Microsoft Teams 및 Microsoft 365 Copilot용 Cortex Agents¶

OAuth 리소스 주체에 대한 동의 부여¶

Cortex Agents 봇 OAuth 리소스 애플리케이션 서비스 주체에 대한 동의를 부여하려면 다음을 수행합니다.

1. 브라우저에서 ``https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=5a840489-78db-4a42-8772-47be9d833efe``로 이동합니다. 여기서, :samp:`{tenant-id}`는 해당 조직의 Microsoft 테넌트 ID입니다.

   아직 로그인하지 않은 경우 로그인하라는 메시지가 표시됩니다.

   애플리케이션에 필요한 권한을 보여주는 Permission requested 대화 상자가 나타납니다.

2. :ui:`Accept`를 선택하여 요청된 권한을 부여합니다.

OAuth 클라이언트 주체에 대한 동의 부여¶

이 프로세스에는 두 개의 대화 상자가 표시됩니다. 각각은 OAuth 리소스 주체에 대한 대화 상자와 유사하지만 요청된 권한은 다릅니다.

Cortex Agents 봇 Snowflake OAuth 클라이언트 애플리케이션 서비스 주체에 대한 동의를 부여하려면 다음을 수행합니다.

1. 브라우저에서 ``https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=bfdfa2a2-bce5-4aee-ad3d-41ef70eb5086``로 이동합니다. 여기서, :samp:`{tenant-id}`는 해당 조직의 Microsoft 테넌트 ID입니다.

   애플리케이션에 필요한 권한 세트 중 하나를 보여주는 Permissions requested (1 of 2) 대화 상자가 나타납니다.

2. :ui:`Accept`를 선택하여 요청된 권한을 부여합니다.

   두 번째 권한 대화 상자(Permissions requested (2 of 2))가 나타납니다.

3. :ui:`Accept`를 선택하여 요청된 권한을 부여합니다.

{
  "error": {
    "code": "ServiceError",
    "message": "Missing required query string parameter: code. Url = https://unitedstates.token.botframework.com/.auth/web/redirect?admin_consent=True&tenant=<TENANT-ID>"
  }
}

권한 부여 확인¶

두 애플리케이션 모두에 대한 동의를 부여한 후, Microsoft Entra ID 포털의 Enterprise applications 섹션을 확인하여 권한 부여가 완료되었는지 확인할 수 있습니다.

1. 필요한 경우 `Microsoft Entra 관리 센터<https://entra.microsoft.com/>`_에 로그인합니다.

2. 검색 상자에 “엔터프라이즈 애플리케이션”을 입력한 후 결과에서 :ui:`Enterprise applications`를 선택하여 엔터프라이즈 애플리케이션으로 이동합니다.

3. All applications 목록에서 방금 동의를 부여한 두 애플리케이션인 Snowflake Cortex Agents 봇 OAuth 리소스 및 Snowflake Cortex Agents 봇 OAuth 클라이언트를 찾습니다. 이를 수행하는 쉬운 방법은 “Snowflake Cortex Agents”를 검색하는 것입니다.

   두 애플리케이션이 모두 목록에 표시되면 권한이 올바르게 부여된 것입니다. 하나 또는 두 애플리케이션 모두 누락된 경우, 다시 한 번 동의를 부여합니다.

Entra ID를 외부 OAuth 공급자로 활성화하기¶

Snowflake 보안 통합 오브젝트는 외부 OAuth 공급자와의 통합을 나타내며, 이 경우 Microsoft Entra ID를 의미합니다. 이러한 통합을 통해 Snowflake는 Microsoft Teams 또는 Copilot에 로그인한 사용자를 인증할 수 있습니다.

다음의 SQL 문은 통합을 생성하기 위한 주석이 달린 템플릿입니다. 이 명령은 ACCOUNTADMIN이 있는 역할에 의해 실행되어야 합니다. tenant-id 자리 표시자를 해당 Microsoft 테넌트 ID로 대체합니다.

CREATE OR REPLACE SECURITY INTEGRATION entra_id_cortex_agents_integration
    TYPE = EXTERNAL_OAUTH
    ENABLED = TRUE
    EXTERNAL_OAUTH_TYPE = AZURE
    EXTERNAL_OAUTH_ISSUER = 'https://login.microsoftonline.com/<tenant-id>/v2.0'
    EXTERNAL_OAUTH_JWS_KEYS_URL = 'https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys'
    EXTERNAL_OAUTH_AUDIENCE_LIST = ('5a840489-78db-4a42-8772-47be9d833efe')
    EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = ('email', 'upn')
    EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = 'email_address'
    EXTERNAL_OAUTH_ANY_ROLE_MODE = 'ENABLE'

이 명령어에 사용할 수 있는 매개 변수의 전체 참조는 :doc:`/sql-reference/sql/create-security-integration-oauth-external`을 참조하세요.

EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM 및 EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE 매개 변수는 Entra ID를 Snowflake ID에 연결합니다. 인증에 성공하려면, JWT에서 지정된 클레임의 값이 Snowflake의 사용자 오브젝트에 지정된 특성의 값과 정확히 일치해야 합니다. Snowflake에서 권장하는 두 가지 주요 구성은 다음과 같습니다.

• 사용자 주체 이름(UPN)에 의한 매핑: EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM 매개 변수를 ‘upn’으로 설정하고, EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE 매개 변수를 ‘LOGIN_NAME’으로 설정합니다.

• 이메일 주소에 의한 매핑: EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM 매개 변수를 ‘email’로 설정하고, EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE 매개 변수를 ‘EMAIL_ADDRESS’로 설정합니다.

위의 예시 문은 이메일 주소 매핑 구성을 사용하지만, EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM 매개 변수에 UPN을 지정하여 EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE만 변경해 매핑 방식을 변경할 수 있습니다.

또한 이 예시 문은 사용자의 기본 역할이 사용되도록 EXTERNAL_OAUTH_ANY_ROLE_MODE를 활성화합니다.

OAuth 범위에 대한 자세한 내용은 범위 섹션을 참조하세요.

Cortex Agent 정의 준비하기¶

보안 통합이 구성된 후에는 Snowflake 내에서 에이전트의 환경 및 정의를 준비해야 합니다. 여기에는 필요한 데이터베이스 오브젝트를 생성하고 에이전트의 로직을 단일 JSON 오브젝트 내에서 정의하는 작업이 포함됩니다. 정의는 에이전트의 지침, 해당 도구(예: Cortex Analyst 및 Cortex Search), 해당 도구를 위한 리소스를 지정합니다. 스키마 정의는 몇 가지 추가 사항이 포함된 :ref:`Cortex Agent API 요청 본문 스키마 <label-cortex-agent-rest-api-request_body>`를 따릅니다. 다음은 JSON 오브젝트의 최상위 구조입니다.

{
    "model": ...,
    "response_instruction": ...,
    "experimental": ...
    "tools": ...
    "tool_resources": ...
    "tool_choice": ...
    "starter_prompts": ...
}

에이전트 정의를 Snowflake 스테이지에 업로드하고, 해당 에이전트를 사용할 모든 최종 사용자가 액세스할 수 있도록 합니다.

검색 결과 및 대화형 안내를 위해 두 가지 필드 옵션을 설정하여 사용자 경험을 향상할 수 있습니다.

• 검색 인용문에는 검색 도구의 tool_resources 정의에서 두 개의 필드 옵션을 제공하여 사람이 읽을 수 있는 제목과 출처 문서로의 직접 링크를 부여할 수 있습니다.

  • :code:`title_column`은 문서에서 사람이 읽을 수 있는 제목을 포함하는 열입니다.

  • :code:`id_column`은 문서에 대한 고유 식별자를 포함하는 열로, Cortex Search가 해당 문서로의 링크를 생성하는 데 사용합니다.

• 에이전트 정의 최상위 수준의 starter_prompts 필드에서 사용자가 질문을 구성하는 데 도움을 주기 위해 시작 프롬프트를 제공할 수 있습니다.

  {
      ....
      "starter_prompts": ["prompt #1", "prompt #2", ...],
      ...
  }
  

  Copy

최종 사용자에게 필요한 권한 부여하기¶

Teams에서 최종 사용자가 Cortex Agent와 상호작용하려면, 기본 Snowflake 역할(또는 기타 지정된 역할)에 모든 기본 오브젝트에 대한 권한이 부여되어야 합니다.

• Cortex Agents 항목의 :ref:`액세스 제어 요구 사항 섹션<label-cortex_agents_access_control>`에 나열된 모든 권한

• 에이전트의 JSON 정의가 포함된 단계에 대한 READ 액세스 권한

• 에이전트에 할당된 웨어하우스에 대한 USAGE 액세스 권한

Teams 스토어에서 앱 설치¶

모든 사용자는 Microsoft Teams 스토어에서 Cortex Agents 앱을 설치해야 합니다. 앱을 설치하려면 Teams 앱 스토어에서 “Snowflake Cortex Agents”를 검색한 후, :ui:`Add`를 클릭하여 앱을 설치합니다.

Teams 앱에 Snowflake 계정 연결¶

Teams에서 Cortex Agents 앱과 처음 상호작용하는 사용자에게는 Snowflake 계정을 앱에 연결하라는 메시지가 표시됩니다. 이 단계가 성공하려면 해당 사용자에게 Snowflake의 ACCOUNTADMIN 또는 SECURITYADMIN 역할이 있어야 합니다.

요약하자면, Snowflake에서 모든 사용자의 기본 역할에는 Cortex Agents 항목의 :ref:`액세스 제어 요구 사항 섹션<label-cortex_agents_access_control>`에 설명된 대로 에이전트의 오브젝트에 액세스하기 위한 필수 권한이 있어야 합니다. 또한 에이전트의 JSON 정의가 포함된 스테이지에 대한 READ 액세스 권한 및 에이전트의 웨어하우스에 대한 USAGE 액세스 권한이 필요합니다. (사용자의 기본 역할은 사용자 프로필의 DEFAULT_ROLE 설정으로 지정됩니다.)

보안 통합은 기본적으로 Snowflake의 주요 관리 역할을 차단합니다. 따라서 Teams 봇을 설정할 사용자의 기본 역할로 관리 역할(예: ACCOUNTADMIN)을 사용할 수 없습니다. 이 제한 사항에 대한 자세한 내용은 CREATE SECURITY INTEGRATION 항목의 BLOCKED_ROLES_LIST 섹션을 참조하세요.

Snowflake는 필요한 권한이 있는 전용 비관리자 역할을 생성하고 이를 설정 사용자의 기본값으로 설정할 것을 권장합니다. 또는 다음과 같이 SECONDARY ROLES 메커니즘을 사용하여 사용자의 기본 역할을 변경하지 않고 추가 권한을 부여할 수 있습니다.

GRANT ROLE <integration_specific_role> TO USER <user_name>;
ALTER USER <user_name> SET DEFAULT_SECONDARY_ROLES = ('<integration_specific_role>');

Teams 봇을 설정하려면 다음 단계를 따릅니다.

1. Teams 유인을 위해 관리자가 Snowflake를 구성해야 한다는 안내문 아래에 있는 :ui:`I’m the Snowflake administrator`를 클릭하면 프로세스가 시작됩니다.

2. 지정된 위치에 Snowflake 계정 URL을 입력합니다.

   이 URL을 찾으려면 Snowsight에 로그인한 후 페이지 왼쪽 하단의 계정 선택기를 클릭합니다. URL의 호스트 이름 부분이 메뉴 상단에 표시되며, 이는 your-organization-your-account 형식으로 구성됩니다. 전체 URL은 :samp:`{your-organization}-{your-account}.snowflakecomputing.com`입니다.

   구성 마법사는 URL이 Azure US East 2 리전의 유효한 Snowflake 인스턴스로 연결되는지 확인하고, 사용자가 해당 인스턴스에 대한 액세스 권한과 필요한 관리 권한을 보유하고 있는지 확인합니다.

   참고

   보안 통합이 “Microsoft Identity Platform 액세스 토큰 v2.0”을 사용하도록 설정해야 한다는 경고가 표시될 수 있습니다. 이 경고는 무시해도 됩니다. Snowflake 보안 통합 토큰 형식은 호환됩니다.

3. 이 검증 과정을 통과하면 다음 구성 세부 정보를 요청하는 양식이 나타납니다.

   • 계정 별칭: Teams 인터페이스에 표시되는 이 Snowflake 계정의 사용자 친화적인 이름입니다(예: “Sales Analytics”).

   • 에이전트 정의 경로: Snowflake 스테이징 내 에이전트의 JSON 정의 파일의 정규화된 전체 경로이며, @stage_name/path_to_definition_file 형식으로 구성됩니다(예: @my_cortex_agents/my_agent.json).

   • 기본 웨어하우스: 에이전트가 쿼리를 실행하는 데 사용하는 Snowflake 웨어하우스의 이름입니다.

   이 정보를 입력한 후 :ui:`Finalize account configuration`을 클릭합니다.

설정이 최종 검증을 통과하면 Teams 앱이 Snowflake 계정에 연결되며 에이전트를 사용할 준비가 완료됩니다.

기본 역할 설정¶

액세스 문제 해결의 첫 번째 단계는 사용자의 기본 역할 설정을 확인하는 것입니다. 이 설정을 확인하려면 DESCRIBE USER 명령을 실행하고 출력에서 DEFAULT_ROLE 속성을 확인합니다. 사용자의 기본 역할이 올바르지 않은 경우, ALTER USER 명령을 사용하여 변경합니다.

ALTER USER <user_name> SET DEFAULT_ROLE = '<correct_role>';

사용자의 기본 DEFAULT_ROLE을 변경할 수 없는 경우, Snowflake의 보조 역할 메커니즘을 사용할 수 있습니다. 사용자는 자신의 기본 역할과 활성 보조 역할의 결합된 권한을 사용하여 작업을 수행할 수 있습니다. 이를 통해 사용자의 기본 역할을 변경하지 않고도 통합 전용의 추가 역할을 부여할 수 있습니다.

Cortex Agents 통합에 보조 역할을 추가하려면 다음과 같은 SQL 명령을 사용합니다. 사용자에게 이미 할당된 보조 역할을 제거하지 않도록 하려면, DESCRIBE USER 출력에서 DEFAULT_SECONDARY_ROLES 속성을 확인합니다. 통합 전용 역할을 추가하는 경우 이러한 기존 역할을 포함합니다.

DESCRIBE USER <user_name>;  -- take note of DEFAULT_SECONDARY_ROLES
GRANT ROLE <integration_specific_role> TO USER <user_name>;
ALTER USER <user_name> SET DEFAULT_SECONDARY_ROLES = ('<pre_existing_role_1>', ....,
    '<integration_specific_role>');

필수 권한¶

사용자의 기본 역할(또는 기본 보조 역할)에는 아래에 설명된 권한이 있어야 합니다.

• SNOWFLAKE.CORTEX_USER 역할을 통한 Cortex AI 기능 액세스. 기본적으로 이 역할은 PUBLIC 역할에 부여되므로, 모든 사용자가 Cortex AI 기능에 액세스할 수 있습니다. 조직에서 SNOWFLAKE.CORTEX_USER를 PUBLIC 에서 제거한 경우, 에이전트가 실행되는 역할에 이를 명시적으로 부여해야 합니다.

• 에이전트가 Cortex Analyst 도구를 사용하는 경우, 해당 역할에는 다음 권한도 부여되어야 합니다.

  • 의미 체계 모델에서 참조되는 모든 데이터베이스 및 스키마에 대한 USAGE 액세스 권한

  • 의미 체계 모델에서 참조되는 모든 테이블 및 뷰에 대한 SELECT 액세스 권한

  • 의미 체계 모델 파일이 포함된 스테이지에 대한 READ 액세스 권한

• 에이전트가 Cortex Search Service를 사용하는 경우, 해당 역할에는 사용되는 특정 서비스에 대한 USAGE 액세스 권한이 있어야 합니다.

OAuth 액세스 토큰이 유효하지 않음(오류 코드 390303)¶

이 오류는 보안 통합에서 하나 이상의 속성 값이 잘못되어 Snowflake가 Entra ID에서 수신한 액세스 토큰을 검증하지 못함을 나타낼 수 있습니다. 이를 해결하려면 보안 통합에서 다음 필드를 확인합니다. 특히, URLs에서 테넌트 ID가 올바른지 확인합니다.

• EXTERNAL_OAUTH_ISSUER: 이는 올바른 Entra ID 발급자 URL로 설정해야 하며, https://login.microsoftonline.com/<tenant-id>/v2.0 형식으로 구성됩니다. 여기서, :samp:`{tenant-id}`는 해당 조직의 Microsoft 테넌트 ID입니다.

• EXTERNAL_OAUTH_JWS_KEYS_URL: 이는 올바른 JWS 키 URL로 설정되어야 하며, https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys 형식으로 구성됩니다. 여기서, :samp:`{tenant-id}`는 해당 조직의 Microsoft 테넌트 ID입니다.

• EXTERNAL_OAUTH_AUDIENCE_LIST: 여기에는 Cortex Agents Bot OAuth 리소스 애플리케이션의 올바른 대상(애플리케이션 ID 5a840489-78db-4a42-8772-47be9d833efe)이 포함되어야 합니다.

ALTER SECURITY INTEGRATION 명령을 사용하여 잘못된 값을 업데이트합니다.

사용자 이름 또는 비밀번호가 잘못됨(오류 코드 390304)¶

이 오류 메시지는 Entra ID에서 전송된 사용자 식별자와 Snowflake의 해당 사용자 레코드 간의 불일치를 나타냅니다. 이는 일반적으로 Entra ID가 정확히 하나의 Snowflake 사용자와 매핑되지 않기 때문입니다. 이 오류는 Snowflake 사용자가 존재하지 않는 경우(또는 매핑된 UPN이나 이메일 주소가 잘못된 경우), 매핑이 여러 Snowflake 사용자로 확인되는 경우(예: 이메일 주소를 사용하여 매핑을 수행하고 여러 사용자가 동일한 주소를 공유하는 경우)에 발생할 수 있습니다.

이 오류 메시지에는 로그인을 시도한 사용자의 UPN 및 이메일이 포함됩니다. 이 정보를 사용하여 DESCRIBE USER 명령을 통해 영향을 받은 사용자의 구성을 확인합니다. 사용자의 NAME 또는 EMAIL 속성이 해당 사용자에 대한 Entra ID의 동일 속성 값과 일치하는지 확인합니다. 이메일 주소 매핑을 사용하는 경우, Snowflake 계정의 모든 사용자에 대해 이메일 주소가 고유한지 확인합니다.

액세스 토큰에 역할이 나열되지 않거나 필터링됨(오류 코드 390317)¶

이 오류는 Snowflake가 OAuth 액세스 토큰의 정보를 기반으로 사용자에게 역할을 할당할 수 없는 경우에 발생합니다. 액세스 토큰은 session:role-any 범위로 구성되어 있으며, 이를 통해 사용자는 Snowflake에서 자신에게 할당된 모든 역할을 수행할 수 있습니다. 그러나 이러한 동작을 허용하려면 보안 통합을 명시적으로 구성해야 합니다.

DESCRIBE SECURITY INTEGRATION 명령을 사용하여 EXTERNAL_OAUTH_ANY_ROLE_MODE 속성의 값을 확인한 후, 해당 값을 ENABLE 또는 ``ENABLE_FOR_LOGIN``로 변경합니다.

DESCRIBE SECURITY INTEGRATION entra_id_cortex_agents_integration;

ALTER SECURITY INTEGRATION entra_id_cortex_agents_integration
    SET EXTERNAL_OAUTH_ANY_ROLE_MODE = 'ENABLE';

연결 문자열에 지정된 역할이 이 사용자에게 부여되지 않음(오류 코드 390186)¶

이 오류는 Snowflake 보안 통합에서 사용자의 기본 역할이 보안 통합을 사용하는 것을 허용하지 않는 경우에 발생합니다.

이 문제를 해결하려면 DESCRIBE SECURITY INTEGRATION 출력에서 다음 속성을 확인합니다.

• EXTERNAL_OAUTH_ALLOWED_ROLES_LIST: 해당 매개 변수가 활성화된 경우, 사용자의 기본 역할이 포함되어 있는지 확인합니다.

• EXTERNAL_OAUTH_BLOCKED_ROLES_LIST: 해당 매개 변수가 활성화된 경우, 사용자의 기본 역할이 포함되어 있지 않은지 확인합니다.