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 범위에 대한 자세한 내용은 범위 섹션을 참조하세요.

사용자 프로비저닝 요구 사항¶

앞서 설명한 매핑 구성을 사용하여 인증을 성공적으로 수행하려면 다음 요구 사항이 충족되는지 확인하세요.

• Entra ID 사용자와 Snowflake 사용자 사이에는 엄격한 일대일 매핑이 존재합니다. 통합을 사용할 모든 Entra ID 사용자에 대해 Snowflake 사용자를 지정하거나 생성합니다.

• 각 Entra ID 사용자는 정확히 한 명의 Snowflake 사용자에게 매핑됩니다. 이메일 매핑의 경우 Entra ID 기본 이메일은 Snowflake 사용자의 EMAIL_ADDRESS와 정확히 일치해야 합니다. UPN 매핑의 경우 Entra ID UPN은 Snowflake 사용자의 LOGIN_NAME과 정확히 일치해야 합니다.

수동 관리 노력을 줄이기 위해 Entra ID와 Snowflake 간의 자동 사용자 프로비저닝 및 프로비저닝 해제를 선택적으로 구성할 수 있습니다. `자동 프로비저닝 구성<https://learn.microsoft.com/en-us/entra/identity/saas-apps/snowflake-provisioning-tutorial>`_을 참조하세요.

Cortex Agent 생성 및 구성¶

보안 통합을 생성한 후 하나 이상의 :doc:`Cortex Agent 오브젝트</user-guide/snowflake-cortex/cortex-agents-rest-api>`가 Teams 또는 Microsoft 365 Copilot 통합에 사용할 Snowflake 계정에 존재하는지 확인합니다.

사용하려는 작동 중인 에이전트가 이미 있는 경우 이 단계에서 추가 작업이 필요하지 않습니다.

새 에이전트를 만들려면 :ref:`지침<label_snowflake_agents_create>`을 따르세요.

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>`에 설명된 대로 에이전트의 오브젝트에 액세스할 수 있는 필수 권한이 있어야 합니다.

보안 통합은 기본적으로 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 = ('ALL');

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

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

2. 지정된 위치에 Snowflake 계정 URL을 입력하고 :ui:`Connect Snowflake account`를 선택합니다.

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

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

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

기본 역할 설정¶

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

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

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

Cortex Agents 통합에 보조 역할을 추가하려면 다음과 같은 SQL 명령을 사용합니다.

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

필수 권한¶

통합을 실행할 역할(각 사용자의 기본 역할 또는 허용된 보조 역할)에 :ref:`액세스 제어 요구 사항 섹션<label-cortex_agents_access_control>`에 설명된 권한이 있는지 확인합니다.

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: 해당 매개 변수가 활성화된 경우, 사용자의 기본 역할이 포함되어 있지 않은지 확인합니다.