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.

Requisitos de provisionamento de usuários¶

Para garantir a autenticação bem-sucedida usando a configuração de mapeamento descrita anteriormente, certifique-se de que os seguintes requisitos sejam atendidos:

• Existe um mapeamento rigoroso de um para um entre usuários do Entra ID e usuários do Snowflake. Designar ou criar um usuário Snowflake para cada usuário do Entra ID que utilizará a integração.

• Cada usuário do Entra ID é mapeado para exatamente um usuário do Snowflake. Para mapeamento de e-mail, o e-mail primário do Entra ID deve corresponder exatamente ao EMAIL_ADDRESS do usuário Snowflake Para mapeamento de UPN, o UPN do Entra ID deve corresponder exatamente ao LOGIN_NAME do usuário Snowflake.

Para reduzir o esforço de administração manual, você tem a opção de configurar o provisionamento e desprovisionamento automático de usuários no Entra ID para Snowflake. Consulte Configuração do provisionamento automático.

Criação e configuração do Cortex Agents¶

Depois de criar a integração de segurança, certifique-se de que pelo menos um objeto do Cortex Agent exista em sua conta Snowflake para a integração com o Teams ou o Microsoft 365 Copilot para uso.

Se você já tem um agente de trabalho que deseja usar, nenhuma outra ação é necessária para esta etapa.

Para criar um novo agente, siga as instruções.

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.

Para redimensionar, 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 do Cortex Agents.

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 as permissões adicionais sem alterar a função padrão primária do usuário, como segue:

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

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. Forneça o URL de sua conta Snowflake onde indicado, e selecione Connect Snowflake account.

   Para encontrar o URL dessa conta, 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.

Após a validação final da configuração, o aplicativo Teams será conectado à sua conta Snowflake e os agentes estarão 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 esta configuração, use o comando DESCRIBE USER. 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.

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

Permissões necessárias¶

Certifique-se de que a função sob a qual a integração será executada (a função padrão de cada usuário ou funções secundárias permitidas) tenha as concessões descritas na seção de requisitos de controle de acesso.

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 configurado para o URL correto do emissor do Entra ID, que está no formato https://login.microsoftonline.com/tenant-id/v2.0, em que tenant-id é o ID de locatário da Microsoft de sua organização.

• EXTERNAL_OAUTH_JWS_KEYS_URL: deve ser definido como o URL correto das chaves JWS, que está no formato https://login.microsoftonline.com/tenant-id/discovery/v2.0/keys, em que tenant-id é o ID de 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 a identidade do usuário do Entra ID não mapeia exatamente para um usuário Snowflake. Isso pode ocorrer quando o usuário Snowflake não existe, quando 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. Ao utilizar o mapeamento de endereços de e-mail, cada usuário na conta Snowflake que utilizará a integração deve ter um endereço de e-mail exclusivo.

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.