Cortex Agents para Microsoft Teams e Microsoft 365 Copilot¶

Concessão de consentimento para a entidade do OAuth Resource¶

Para conceder consentimento para a entidade de serviço do aplicativo Cortex Agents Bot OAuth Resource:

1. No seu navegador, acesse https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=5a840489-78db-4a42-8772-47be9d833efe, em que tenant-id é o ID do locatário da Microsoft da sua organização.

   Se você ainda não tiver se conectado, receberá uma solicitação para fazer isso.

   A caixa de diálogo Permission requested é exibida, mostrando a permissão que o aplicativo exige.

2. Selecione Accept para conceder a permissão solicitada.

Concessão de consentimento para a entidade do OAuth Client¶

Esse processo exibe duas caixas de diálogo. Cada uma é semelhante à da entidade do OAuth Resource, mas as permissões solicitadas são diferentes.

Para conceder consentimento para a entidade de serviço do aplicativo Cortex Agents Bot Snowflake OAuth Client:

1. No seu navegador, acesse https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=bfdfa2a2-bce5-4aee-ad3d-41ef70eb5086, em que tenant-id é o ID do locatário da Microsoft da sua organização.

   A caixa de diálogo Permissions requested (1 of 2) é exibida, mostrando um conjunto de permissões que o aplicativo exige.

2. Selecione Accept para conceder as permissões solicitadas.

   A segunda caixa de diálogo de permissão é exibida (Permissions requested (2 of 2)).

3. Selecione Accept para conceder as permissões solicitadas.

{
  "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>"
  }
}

Confirmação de concessões de permissões¶

Após conceder o consentimento para ambos os aplicativos, você pode confirmar se as permissões foram concedidas com sucesso verificando a seção Enterprise applications do portal Microsoft Entra ID.

1. Faça login no Centro de administração do Microsoft Entra se necessário.

2. Acesse Enterprise Applications digitando “enterprise applications” na caixa de pesquisa e selecione Enterprise applications nos resultados.

3. Na lista All applications, encontre os dois aplicativos para os quais você acabou de conceder o consentimento: Snowflake Cortex Agents Bot OAuth Resource e Snowflake Cortex Agents Bot OAuth Client. Uma maneira fácil de fazer isso é pesquisar por “Snowflake Cortex Agent”.

   Se ambos os aplicativos aparecerem na lista, as permissões foram concedidas corretamente. Se um ou ambos os aplicativos estiverem ausentes, tente conceder o consentimento novamente.

Habilitação do Entra ID como um provedor OAuth externo¶

Um objeto de integração de segurança do Snowflake representa uma integração com um provedor OAuth externo, neste caso, o Microsoft Entra ID. Essa integração permite que o Snowflake autentique usuários conectados ao Microsoft Teams ou ao Copilot.

A instrução SQL a seguir é um modelo anotado para a criação da integração. Este comando deve ser executado por uma função com privilégios ACCOUNTADMIN. Substitua os espaços reservados tenant-id pelo ID do seu locatário da Microsoft.

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'

Consulte CREATE SECURITY INTEGRATION (OAuth externo) para obter uma referência completa dos parâmetros disponíveis para esse comando.

Juntos, os parâmetros EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM e EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE vinculam uma identidade Entra ID a uma identidade Snowflake. Para que a autenticação seja bem-sucedida, o valor da declaração especificada em JWT deve corresponder exatamente ao valor do atributo especificado em um objeto de usuário no Snowflake. As duas configurações principais que o Snowflake recomenda são:

• Mapeamento por nome principal do usuário (UPN): Defina o parâmetro EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM como “upm” e o parâmetro EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE como “LOGIN_NAME”.

• Mapeamento por endereço de e-mail: Defina o parâmetro EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM como “email” e o parâmetro EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE como “EMAIL_ADDRESS”.

A instrução de exemplo acima usa a configuração de mapeamento de endereço de e-mail, mas também especifica UPN no parâmetro EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM, permitindo que você altere o método de mapeamento mudando apenas EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE.

A instrução de exemplo também habilita EXTERNAL_OAUTH_ANY_ROLE_MODE para que a função padrão do usuário seja usada.

Para obter mais informações sobre escopos OAuth, consulte Escopos.

Preparação da definição do Cortex Agent¶

Depois que a integração de segurança estiver configurada, você deve preparar o ambiente e a definição do agente no Snowflake. Isso envolve a criação dos objetos de banco de dados necessários e a definição da lógica do agente em um único objeto JSON. A definição do especifica as instruções do agente, as ferramentas dele (como Cortex Analyst e Cortex Search) e os recursos para essas ferramentas. A definição do esquema segue o esquema do corpo da solicitação da API Cortex Agent com algumas adições. A seguir, veja a estrutura de nível superior do objeto JSON:

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

Carregue a definição do agente em um estágio do Snowflake e certifique-se de que ela esteja acessível a todos os usuários finais que usarão o agente.

Você pode aprimorar a experiência do usuário definindo dois campos opcionais para resultados de pesquisa e orientação de conversação:

• As referências de pesquisa podem receber um título legível e um link direto para o documento de origem, fornecendo dois campos opcionais na definição tool_resources da ferramenta de pesquisa:

  • title_column é uma coluna que contém o título legível de um documento.

  • id_column é uma coluna que contém um identificador exclusivo para o documento, que o Cortex Search usa para construir um link para o documento.

• Prompts iniciais podem ser fornecidos para orientar os usuários na formulação de suas perguntas no campo starter_prompts no nível superior da definição do agente.

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

  Copy

Concessão dos privilégios necessários aos usuários finais¶

Para que os usuários finais interajam com sucesso com um Cortex Agent no Teams, sua função padrão do Snowflake (ou outra função designada) deve ter concessões de privilégios em todos os objetos subjacentes:

• Todas as permissões listadas na seção de requisitos de controle de acesso do tópico Cortex Agents

• Acesso READ ao estágio que contém a definição JSON do agente

• USAGE no warehouse designado ao agente

Instalar o aplicativo da loja do Teams¶

Todos os usuários devem instalar o aplicativo Cortex Agents da loja do Microsoft Teams. Para instalar o aplicativo, pesquise «Snowflake Cortex Agents» na loja de aplicativos do Teams e clique em Add para instalar o aplicativo.

Conectar sua conta Snowflake ao aplicativo do Teams¶

O primeiro usuário a interagir com o aplicativo Cortex Agents no Teams é solicitado a conectar a conta Snowflake dele ao aplicativo. Esse usuário deve ter a função ACCOUNTADMIN ou SECURITYADMIN no Snowflake para que esta etapa seja bem-sucedida.

Recapitulando, a função padrão de cada usuário no Snowflake deve ter os privilégios necessários para acessar os objetos do agente, conforme descrito na seção de requisitos de controle de acesso do tópico Cortex Agents, juntamente com acesso READ ao estágio que contém a definição JSON do agente e USAGE no warehouse do agente. (A função padrão do usuário é especificada pela configuração DEFAULT_ROLE no perfil do usuário.)

As integrações de segurança bloqueiam as principais funções administrativas do Snowflake por padrão. Portanto, você não pode usar funções administrativas como ACCOUNTADMIN como a função padrão para o usuário que vai configurar o bot do Teams. Para obter informações sobre essa restrição, consulte BLOCKED_ROLES_LIST no tópico CREATE SECURITY INTEGRATION.

O Snowflake recomenda que você crie uma função dedicada e não administrativa com as permissões necessárias e a defina como padrão para o usuário de configuração. Como alternativa, use o mecanismo SECONDARY ROLES para conceder permissões adicionais sem alterar a função padrão principal do usuário, da seguinte forma:

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

Para configurar o bot do Teams, siga estas etapas:

1. Clique em I’m the Snowflake administrator, abaixo do aviso informando que um administrador precisa configurar o Snowflake para o convite do Teams, para iniciar o processo.

2. Informe sua conta Snowflake URL onde indicado.

   Para encontrar esse URL, faça login no Snowsight e clique no seletor de contas no canto inferior esquerdo da página. A parte do nome do host do URL é exibida na parte superior do menu e está no formato your-organization-your-account. O URL completo é your-organization-your-account.snowflakecomputing.com.

   O assistente de configuração verifica se o URL leva a uma instância válida do Snowflake na região do Azure US East 2 e confirma se o usuário tem acesso a ela e os privilégios administrativos necessários.

   Nota

   Você poderá ver um aviso solicitando que a integração de segurança utilize o «token de acesso da plataforma de identidade da Microsoft v2.0». Você pode ignorar esse aviso com segurança; o formato do token de integração de segurança do Snowflake é compatível.

3. Após a verificação, um formulário será exibido solicitando os seguintes detalhes de configuração:

   • Alias ​​da conta: um nome amigável para esta conta Snowflake que aparece na interface do Teams, por exemplo, «Análise de Vendas».

   • Caminho de definição do agente: o caminho totalmente qualificado para o arquivo de definição JSON do agente em um estágio do Snowflake, no formato @stage_name/path_to_definition_file, como @my_cortex_agents/my_agent.json.

   • Warehouse padrão: o nome do warehouse do Snowflake que o agente usa para executar consultas.

   Insira essas informações e clique em Finalize account configuration.

Após a validação final da configuração, o aplicativo Teams será conectado à sua conta Snowflake e o agente estará pronto para uso.

Configuração da função padrão¶

A primeira etapa na solução de problemas de acesso é verificar a configuração da função padrão do usuário. Para verificar essa configuração, execute o comando DESCRIBE USER e verifique a propriedade DEFAULT_ROLE na saída. Se a função padrão do usuário estiver incorreta, altere-a usando o comando ALTER USER.

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

Se alterar a função primária DEFAULT_ROLE do usuário não for viável, você pode usar o mecanismo de funções secundárias do Snowflake. Um usuário pode executar ações usando os privilégios combinados de suas funções primária e secundária ativa. Isso permite que você conceda uma função adicional específica de integração ao usuário sem alterar a função primária.

Para adicionar uma função secundária para a integração de Cortex Agents, use comandos SQL como os seguintes. Para garantir que você não remova nenhuma função secundária já designada ao usuário, observe a propriedade DEFAULT_SECONDARY_ROLES na saída de DESCRIBE USER. Inclua essas funções pré-existentes ao adicionar a função específica da integração.

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

Permissões necessárias¶

A função padrão do usuário (ou uma função secundária padrão) deve possuir os privilégios descritos abaixo.

• Acesso à função AI do Cortex por meio da função SNOWFLAKE.CORTEX_USER. Por padrão, essa função é concedida à PUBLIC, para que todos os usuários possam acessar as funções AI do Cortex. Se a sua organização removeu SNOWFLAKE.CORTEX_USER de PUBLIC, você deve concedê-la explicitamente à função sob a qual o agente é executado.

• Se o agente utilizar a ferramenta Cortex Analyst, a função também deverá ter os seguintes privilégios:

  • USAGE em todos os bancos de dados e esquemas referenciados no modelo semântico

  • SELECT em todas as tabelas e visualizações referenciadas no modelo semântico

  • Acesso READ ao cenário que contém o(s) arquivo(s) do modelo semântico

• Se o agente utilizar um Cortex Search Service, a função deverá ter USAGE no serviço específico utilizado.

Token de acesso OAuth inválido (código de erro 390303)¶

Este erro pode indicar que um ou mais valores de propriedade na integração de segurança estão incorretos, impedindo o Snowflake de validar o token de acesso recebido do Entra ID. Para corrigir isso, verifique os seguintes campos na integração de segurança. Em particular, verifique se o ID do locatário está correto nos URLs.

• EXTERNAL_OAUTH_ISSUER: deve ser definido como o URL do emissor do Entra ID correto, que está no formato https://login.microsoftonline.com/<tenant-id>/v2.0, em que tenant-id é o ID do locatário da Microsoft da sua organização.

• EXTERNAL_OAUTH_JWS_KEYS_URL: deve ser definido como o URL correto das chaves JWS, que estão no formato https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys, em que tenant-id é o ID do locatário da Microsoft da sua organização.

• EXTERNAL_OAUTH_AUDIENCE_LIST: deve incluir o público correto para o aplicativo Cortex Agents Bot OAuth Resource, que é o ID de aplicativo 5a840489-78db-4a42-8772-47be9d833efe.

Atualize os valores incorretos com o comando ALTER SECURITY INTEGRATION.

Nome de usuário ou senha incorretos (código de erro 390304)¶

Esta mensagem de erro indica uma incompatibilidade entre o identificador de usuário enviado pelo Entra ID e o registro do usuário correspondente no Snowflake, geralmente porque o Entra ID não mapeia exatamente um usuário Snowflake. Isso pode ocorrer quando o usuário Snowflake não existe (ou o UPN ou endereço de e-mail mapeado está incorreto) ou quando o mapeamento é resolvido para vários usuários Snowflake (por exemplo, se o mapeamento for realizado usando um endereço de e-mail e vários usuários compartilharem o mesmo endereço).

A mensagem de erro inclui o UPN e o e-mail do usuário que tentou efetuar login. Use essas informações para verificar a configuração do usuário afetado usando o comando DESCRIBE USER. Certifique-se de que a propriedade NAME ou EMAIL do usuário corresponda ao valor da mesma propriedade no Entra ID para o usuário correspondente. Se estiver usando o mapeamento de endereços de e-mail, certifique-se de que o endereço de e-mail seja exclusivo para todos os usuários da conta Snowflake.

Função não listada no token de acesso ou foi filtrada (código de erro 390317)¶

Esse erro ocorre quando o Snowflake não consegue designar uma função ao usuário com base nas informações do token de acesso OAuth. O token de acesso está configurado com o escopo session:role-any, que permite que o usuário assuma qualquer uma das funções designadas a ele no Snowflake. No entanto, a integração de segurança deve ser configurada explicitamente para permitir esse comportamento.

Use o comando DESCRIBE SECURITY INTEGRATION para verificar o valor da propriedade EXTERNAL_OAUTH_ANY_ROLE_MODE e, em seguida, altere-o para ENABLE ou 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';

A função especificada na cadeia de conexão não foi concedida a este usuário (código de erro 390186)¶

Este erro ocorre quando a integração de segurança do Snowflake não permite que a função padrão do usuário utilize a integração.

Para resolver isso, verifique as seguintes propriedades na saída de DESCRIBE SECURITY INTEGRATION:

• EXTERNAL_OAUTH_ALLOWED_ROLES_LIST: Se o parâmetro estiver habilitado, verifique se ele contém a função padrão do usuário.

• EXTERNAL_OAUTH_BLOCKED_ROLES_LIST: Se o parâmetro estiver habilitado, verifique se ele não contém a função padrão do usuário.